Skip to content

Domain Packages

wmux has three domain packages under internal/. Each domain is a self-contained bounded context that owns its entities, business rules, and repository interfaces. Domains never import each other; they communicate through interfaces wired by fx at startup.

daemon

Daemon lifecycle management.

The daemon domain handles everything related to the wmux process itself:

  • Auto-daemonization: When the CLI starts a new daemon, it re-execs itself as a background process (double-fork pattern), detaching from the controlling terminal.
  • PID file: Writes and locks a PID file to prevent multiple daemon instances. On startup, validates that any existing PID file refers to a running process.
  • Graceful shutdown: Listens for termination signals and orchestrates an orderly shutdown sequence (SIGTERM to child processes, then SIGKILL after a timeout).
  • Orphaned session reconciliation: On startup, scans for sessions left behind by a previous daemon crash. Reattaches to still-running PTY processes and cleans up stale state.
  • OSC sequence processing: Handles Operating System Command sequences -- cwd changes (OSC 7), desktop notifications (OSC 9/99/777), and shell-ready detection.

session

Session lifecycle and PTY management.

The session domain is the largest and most complex. It manages the full lifecycle of a terminal session from creation to cleanup:

  • PTY spawn and management: Creates pseudo-terminal pairs, spawns shell processes, and manages resize operations. Wraps the creack/pty library via the platform pty package.
  • Process tree kill: When terminating a session, sends SIGHUP to the entire process group first, then escalates to SIGKILL after a configurable timeout if processes remain.
  • Session state machine: Each session transitions through well-defined states: alive (attached and running), detached (running but no client), exited (process terminated, awaiting cleanup), and removed (fully cleaned up).
  • Backpressure: Implements high/low watermark flow control. When the output buffer exceeds the high watermark, the session pauses reading from the PTY. Reading resumes when the buffer drains below the low watermark.
  • Output batching: Coalesces PTY output into batches (16ms default interval) before sending to the client. This reduces IPC overhead and system call frequency during high-throughput output.
  • Emulator integration: Maintains a virtual terminal emulator state for each session, enabling scrollback capture and screen-level operations even when no client is attached.
  • Idle reaper: Periodically scans for sessions that have been detached beyond a configurable idle timeout, then terminates them to reclaim resources.
  • Session watchdog: Monitors session health and detects stuck or unresponsive PTY processes.

transport

IPC server and client connections.

The transport domain manages all communication between the CLI client and the daemon:

  • Unix socket listener: Listens on a Unix domain socket for incoming client connections. The socket path is derived from the user's runtime directory.
  • Binary protocol framing: Each message is framed with version, type, length, and payload fields. The protocol is defined in the platform protocol package; the transport domain handles connection-level concerns.
  • Two-channel architecture: Each client connection establishes two logical channels:
  • Control channel: Carries low-frequency request/response RPCs (create session, list sessions, resize, kill).
  • Stream channel: Carries high-frequency bidirectional PTY I/O (stdin from client, stdout/stderr from daemon).
  • Authentication handshake: On connection, the client must present a valid token. Tokens are 32-byte random values generated by the platform auth package and stored alongside the PID file.
  • Heartbeat monitoring: The transport layer sends periodic heartbeat messages to detect dead clients. If a client misses heartbeats beyond a threshold, its session is marked as detached.
  • PPID-based orphan detection: Monitors the parent process ID of connected clients. If a client's parent process dies (PPID becomes 1), the connection is treated as orphaned and cleaned up.

Platform Packages

Platform packages live under internal/platform/ and provide shared infrastructure used by domain packages. They have no knowledge of domain concepts and can be reused independently.

Package Description
ansi ANSI escape code parser. Interprets CSI, OSC, and other control sequences from raw terminal output.
auth Token-based authentication. Generates and validates 32-byte cryptographically random tokens for client-daemon handshakes.
config TOML configuration loading with hot-reload support. Built on koanf, watches config files for changes and notifies subscribers.
event Domain event bus implementing publish/subscribe. Allows domains to react to events from other domains without direct imports.
history Scrollback persistence. Stores terminal scrollback in a binary format (scrollback.bin) with a companion metadata file (meta.json).
ipc Unix socket listener abstraction. Handles socket creation, permission setting, and cleanup on shutdown.
logger Structured JSON logging. Provides a configured logger instance suitable for daemon operation where structured output is essential.
protocol Binary framing protocol. Defines the wire format: version (1 byte), message type (1 byte), payload length (4 bytes), and payload.
pty PTY spawn and management. Wraps creack/pty to provide a clean interface for creating pseudo-terminals and managing their lifecycle.
recording Session recording in asciicast v2 format. Captures timestamped terminal output for later playback with standard asciicast-compatible players.