Crate netls 

netls is a network connections viewer for daily use and automation.

This crate exposes the same functionality as the netls CLI tool through a programmatic API. The entry points are snapshot (gathered with a Filter) and the various enrich_* functions that populate optional fields on each Connection.

Modules

config

Configuration file (TOML) loading: [defaults], [profiles.<name>], [ports]. Configuration file support.

Structs

Connection

A single network connection.

ConnectionDiff

Result of diff_connections.

ConnectionKey

Stable identity key for a Connection. Internal representation is opaque; only Display, Hash, and equality are guaranteed.

FdUsage

Open file descriptors and the soft limit for a process. Populated on a Connection by enrich_fd.

Filter

Builder-style filter for snapshot.

ParseEnumError

Error returned when a string cannot be parsed into one of the library’s enum types (Proto, State, SortKey).

SnapshotResult

Result of snapshot_with_containers: connections plus any non-fatal warnings that occurred while enriching from container runtimes.

Summary

Aggregated counts of connections by protocol and TCP state. Returned by summary.

TopProcess

A single entry returned by top_connections.

Enums

Error

Errors returned by netls library functions.

Proto

Transport protocol of a connection.

SortKey

Column key accepted by sort_connections.

State

TCP connection state. Mirrors the standard TCP state machine (RFC 793). Only meaningful for Proto::Tcp.

Constants

VALID_GROUP_BY

Fields accepted by --group-by and the group_by config field.

VALID_PROTOS

Protocols accepted by --proto and the proto config field.

VALID_SORT

Columns accepted by --sort and the sort config field.

VALID_STATES

Connection states accepted by --state and the state config field.

Functions

compact_addr

Replace verbose IPv6 addresses with human-friendly aliases. [::1]:port -> localhost:port, [::]:port / [0:…:0]:port -> *:port

diff_connections

Compute the diff between two connection snapshots.

docker_proxy_service

For a docker-proxy connection, resolve the compose/container service name behind it. Returns None if the connection is not docker-proxy or if resolution fails (no PID, cmdline unreadable, daemon unreachable).

enrich_age

Populate age_secs for each connection by reading the mtime of the socket fd in /proc/<pid>/fd/. Uses the stored inode to find the exact fd symlink. Linux only - no clean equivalent on macOS.

enrich_cmdline

Populate cmdline field for each connection. On Linux: reads /proc/<pid>/cmdline (full args joined with spaces). On macOS: uses pidpath() to get the full binary path.

enrich_fd

Populate fd_usage for each connection: (open_fds, soft_limit). On Linux: reads /proc/<pid>/fd/ and /proc/<pid>/limits. On macOS: uses listpidinfo::<ListFDs> and getrlimit.

enrich_process_tree

Populate parent_chain for each connection. On Linux: walks PPid links in /proc/<pid>/status. On macOS: uses BSDInfo.pbi_ppid via libproc. Result format: “parent <- grandparent <- …” (up to 4 levels).

enrich_systemd

Populate systemd_unit for each connection from /proc/<pid>/cgroup. Extracts the last path component ending in “.service”, “.scope”, or “.slice”. Not applicable on macOS (uses launchd).

fmt_age

Format age in seconds as a human-readable string: “5s”, “3m12s”, “2h34m”, “1d3h”.

resolve_dns

Resolve remote IP addresses to hostnames in-place. Skips wildcard (*), loopback, and addresses that fail to resolve. All unique IPs are looked up concurrently under a single 2-second deadline, so total latency stays bounded regardless of how many connections are passed in.

resolve_proxy_origins

For each external connection that passes through a local proxy, return the list of originating process names (one or more).

snapshot

Return a snapshot of current network connections, optionally filtered.

snapshot_all

Return all connections without any filtering. Used internally for proxy chain analysis which needs the full picture.

snapshot_with_containers

Collect connections from the host plus all running Docker containers. Linux only - Docker runs in a VM on macOS; namespace trick does not apply.

sort_connections

Sort connections in-place by one of the supported keys.

summary

Return a summary of connections grouped by proto and state.

top_connections

Return top N processes by connection count, descending. Ties are broken by name (ascending).

Type Aliases

Result

Convenience alias for std::result::Result<T, netls::Error>.