nexus
AdaptersNode IPC

Concepts

Understand daemon, client, socket, and session behavior in Node IPC.

This page explains the adapter mental model. Read Quick start first if you want working code before concepts.

Daemon And Client Roles

The node-ipc adapter models one local daemon process and one or more local clients.

The daemon:

  • listens on a filesystem Unix socket
  • exposes Nexus services
  • owns the socket lifecycle

The client:

  • connects to a daemon socket
  • gets Nexus proxies from an acquired connection
  • calls services exposed by the daemon

Both sides are normal Nexus runtimes. The adapter only supplies endpoint wiring and metadata.

Client-Provided Services And Startup Dials

A client can provide services to its daemon. If the daemon creates the client process, start the daemon listener first, spawn the client, and passively wait with daemonNexus.connect({ where, timeout: 10_000 }).

usingNodeIpcClient({
  appId: "worker-B",
  connectTo: [{ context: "node-ipc-daemon", appId: "owner-A" }],
}).provide(WorkerToken, workerService);

Match the spawned client’s unique identity in where. Passive connection waits for an authorized ready session, not provider discovery or merely socket open. Register services before the client publishes its application-ready identity marker when the daemon needs those services immediately. connectTo is one-shot, does not block ready(), does not retry, and does not acquire a service; the daemon need not expose a service.

ConnectionTarget Vs Socket Address

Nexus targets use NodeIpcConnectionTarget. The adapter maps exact targets to socket addresses.

ConnectionTarget example:

{ context: "node-ipc-daemon", appId: "example-app", instance: "default" }

Socket address example:

{ kind: "path", path: "/run/user/1000/nexus/example-app/default.sock" }

Keep this distinction clear:

  • exact targets are part of Nexus connection intent
  • socket addresses are adapter transport details

Application code should normally target the exported Node IPC target shape. Custom address resolvers are the escape hatch when the application owns a specific socket layout.

Adapter Pre-Auth vs Core Policy

Shared-secret pre-auth is an adapter gate. It proves the peer knows the configured token before the socket is handed to Nexus core.

Core policy is the shared Nexus authorization layer. It decides whether authenticated or unauthenticated peers may complete the logical handshake and call services.

The common pattern is:

  1. node-ipc validates the shared secret
  2. node-ipc records connection.observed.authenticated
  3. policy.canConnect checks the connection fact
  4. policy.canCall checks service access

ContextMeta Vs ConnectionMeta

Endpoint metadata is logical identity declared by the process.

Daemon metadata shape:

{
  context: "node-ipc-daemon";
  appId: string;
  instance?: string;
  pid: number;
}

Client metadata shape:

{
  context: "node-ipc-client";
  appId: string;
  pid: number;
}

Connection metadata is adapter-observed data:

{
  observed: {
    socket: NodeIpcSocketAddress;
    authenticated: boolean;
    authMethod?: "none" | "shared-secret";
  };
}

The adapter does not currently claim OS-verified peer pid, uid, or gid. Treat pid in endpoint metadata as diagnostic self-declared data unless peer credential support is implemented later.

Framing vs Serialization

Unix sockets are byte streams. The adapter must restore packet boundaries before Nexus core can process packets.

The frame format is:

[uint32 byteLength][ArrayBuffer packet bytes]

Framing does not define Nexus message semantics. It only says where one packet ends and the next begins.

Serialization still belongs to core. Current BinarySerializer is compact Nexus JSON encoded as UTF-8 bytes, not MessagePack.

Session-Bound Handles

Raw Nexus proxies and remote refs are tied to the logical connection that created them.

If the daemon restarts or the socket disconnects:

  • old proxies should fail
  • old remote refs should be treated as invalid
  • clients should create a new proxy after reconnecting

This keeps lifecycle boundaries explicit. The raw core proxy does not silently retarget itself to a new daemon session.

Runtime Boundary

The adapter is a local IPC adapter, not a network adapter.

It does not provide:

  • cross-machine transport
  • TLS
  • global service or target discovery outside the application’s target-to-socket workflow
  • durable reconnecting proxy handles
  • OS peer credential authorization

Those features can be added above or below the adapter, but they are not part of the current package contract.

Edit this page on GitHub