Addressing
Configure and diagnose Node IPC Unix socket addressing.
Node-ipc addressing maps exact NodeIpcConnectionTarget values to filesystem Unix socket paths.
Default ConnectionTarget
The daemon target is:
{
context: "node-ipc-daemon";
appId: string;
instance?: string;
}instance defaults to default.
Use instances when one app has more than one local daemon role:
usingNodeIpcDaemon({ appId: "example-app", instance: "indexer" });
usingNodeIpcDaemon({ appId: "example-app", instance: "sync" });Default Filesystem Paths
When XDG_RUNTIME_DIR is set, the default path is:
$XDG_RUNTIME_DIR/nexus/<appId>/<instance>.sockWhen XDG_RUNTIME_DIR is not set, the fallback is:
/tmp/nexus-<uid>/<appId>/<instance>.sockExamples:
/run/user/1000/nexus/example-app/default.sock
/tmp/nexus-1000/example-app/default.sockSegment Validation
The default resolver rejects unsafe appId and instance segments.
Rejected examples:
- empty strings
...- values containing
/ - values containing
\ - values that make the final socket path exceed the Unix socket path limit
This keeps target input from becoming path traversal.
Custom Resolver
Use a custom resolver when your application owns a specific socket layout.
usingNodeIpcClient({
appId: "example-app",
resolveAddress(target) {
if (target.context !== "node-ipc-daemon") return null;
if (target.appId !== "example-app") return null;
return { kind: "path", path: "/run/user/1000/example-app.sock" };
},
});Returning null means the target is not resolvable. Nexus treats that as an address error instead of guessing another path.
Custom paths must be absolute filesystem paths and must fit the platform socket path limit.
Runtime Directory Safety
Daemon startup creates adapter-owned directories with user-private permissions where possible.
The adapter checks the directories it owns before binding:
- symlink directories are rejected
- non-directories are rejected
- unsafe group/world-writable runtime roots are rejected
- normal system ancestors such as
/,/run,/run/user, and/tmpare allowed when they have safe ownership semantics
The adapter should not silently chmod directories it does not own. If you use a custom path under an unsafe directory, fix the directory ownership and permissions explicitly in your application or installer.
Existing Socket Paths
If the socket path already exists, daemon startup checks whether it belongs to a live daemon.
Outcomes:
- live socket: startup fails with
E_IPC_ADDRESS_IN_USE - stale socket file: the adapter removes it and starts listening
- regular file: startup fails
- symlink: startup fails
- cleanup error: startup fails with
E_IPC_STALE_SOCKET_CLEANUP_FAILED
The adapter does not blindly unlink unknown filesystem entries.
Abstract Socket Addresses
The public address type reserves an abstract socket form:
{ kind: "abstract", name: string }Filesystem path sockets are the default supported path. Treat abstract namespace support as reserved unless the package docs and tests for your target version explicitly cover it.