Skip to main content

​
Overview

The connections API uses three main TypeScript types to represent network data: Listener, Connection, and ConnectionsData. These types are defined in lib/connections.ts and are used throughout the API responses.

​
Listener

Represents a process that is listening on a network port. 
export type Listener = {
  pid: number;
  processName: string;
  /** Label: "6379 (típico: Redis)" or container name when Docker */
  serviceLabel?: string;
  /** Set when this port is published by a Docker container (show Docker icon). */
  containerName?: string;
  /** Icon type for Process column: node, next, redis, mongo, postgres, mysql, apache, ssh, generic */
  processIconType?: string;
  address: string;
  addressDescription?: string;
  port: number;
  cmd?: string;
};

​
Fields

​
pid
number
required
Process ID of the listening process. May be 0 if the process information is not available.
​
processName
string
required
Name of the process (e.g., “node”, “redis-server”, “postgres”). Extracted from /proc/{pid}/comm. Will be "?" if the process name cannot be determined.
​
serviceLabel
string | undefined
Human-readable service label for display purposes:
  • Shows the container name for Docker-published ports
  • Shows “psys” for the psys application itself
  • Shows “6379 (typical: Redis)” format for recognized services when process name is ”?”
  • Shows ” (unknown)” for unrecognized services
  • undefined when the process name is known and not a Docker container
​
containerName
string | undefined
Docker container name if this port is published by a Docker container. Used to display Docker icon in the UI.
​
processIconType
string | undefined
Suggested icon type for UI display. Possible values:
  • "node" - Node.js processes
  • "next" - Next.js applications
  • "redis" - Redis server
  • "mongo" - MongoDB
  • "postgres" - PostgreSQL
  • "mysql" - MySQL/MariaDB
  • "apache" - Apache HTTP Server
  • "ssh" - SSH server
  • "psys" - The psys application itself
  • "generic" - Generic/unknown service
​
address
string
required
IP address the service is listening on. Common values:
  • "0.0.0.0" - All IPv4 interfaces
  • "127.0.0.1" - Localhost only (IPv4)
  • "::" - All IPv6 interfaces
  • "::1" - Localhost only (IPv6)
  • Specific IP addresses for individual interfaces
​
addressDescription
string | undefined
Human-readable description of what the address means:
  • "Listening on all IPv4 interfaces"
  • "Localhost only (IPv4)"
  • "Localhost or all IPv6"
  • "systemd-resolved (local DNS)"
  • "Local network (IPv4)"
  • "IPv6 address"
  • "Other interface"
​
port
number
required
Port number the service is listening on (0-65535).
​
cmd
string | undefined
Full command line of the process, extracted from /proc/{pid}/cmdline. Truncated to 80 characters. Null bytes are replaced with spaces.

​
Connection

Represents an established TCP connection between processes. 
export type Connection = {
  fromPid: number;
  fromProcessName: string;
  fromAddress: string;
  fromPort: number;
  toAddress: string;
  toPort: number;
  toLabel?: string;
};

​
Fields

​
fromPid
number
required
Process ID that initiated the connection.
​
fromProcessName
string
required
Name of the process that initiated the connection. Extracted from /proc/{pid}/comm.
​
fromAddress
string
required
Source IP address of the connection. Normalized for consistent display (e.g., loopback addresses standardized).
​
fromPort
number
required
Source port number (ephemeral port typically assigned by the OS).
​
toAddress
string
required
Destination IP address the connection is going to.
​
toPort
number
required
Destination port number (the service port the connection is targeting).
​
toLabel
string | undefined
Optional label identifying the destination service:
  • Docker container name if the destination is a Docker-published port
  • Known service name for common ports (“MongoDB”, “Redis”, “PostgreSQL”, “MySQL”, “Elasticsearch”, “RabbitMQ”)
  • Process name if the destination is another local process
  • undefined if the destination cannot be identified

​
ConnectionsData

The top-level response type returned by the /api/connections endpoint. 
export type ConnectionsData = {
  listeners: Listener[];
  connections: Connection[];
};

​
Fields

​
listeners
Listener[]
required
Array of all listening ports on the system. Gathered from ss -tlnp command output.
​
connections
Connection[]
required
Array of all established TCP connections. Gathered from ss -tnp command output.

​
Usage Example

import type { ConnectionsData, Listener, Connection } from '@/lib/connections';

// Fetch connections data
const response = await fetch('/api/connections');
const data: ConnectionsData = await response.json();

// Find all Redis listeners
const redisListeners: Listener[] = data.listeners.filter(
  listener => listener.processIconType === 'redis'
);

// Find all connections to port 6379 (Redis)
const redisConnections: Connection[] = data.connections.filter(
  conn => conn.toPort === 6379
);

// Get all Docker container listeners
const dockerListeners: Listener[] = data.listeners.filter(
  listener => listener.containerName !== undefined
);

​
Type Guards

// Check if a listener is from a Docker container
function isDockerListener(listener: Listener): boolean {
  return listener.containerName !== undefined;
}

// Check if a listener is the psys app itself
function isPsysListener(listener: Listener): boolean {
  return listener.processIconType === 'psys';
}

// Check if a connection has an identified destination
function hasKnownDestination(connection: Connection): boolean {
  return connection.toLabel !== undefined;
}