Registry / http-networking / node-unix-socket

node-unix-socket

JSON →
library0.2.7jsnpmunverified

node-unix-socket is a Node.js addon, built with napi-rs and leveraging libuv, that extends Node.js's native networking capabilities to support Unix `SOCK_SEQPACKET` and `SOCK_DGRAM` sockets. It also enables the use of `SO_REUSEPORT` for TCP `net.Server` instances, offering an alternative to Node.js's built-in `cluster` module for load balancing, with kernel-level distribution. The package is currently at version 0.2.7, indicating ongoing development. It differentiates itself by providing these advanced socket types without introducing additional asynchronous runtimes, relying solely on Node.js's internal libuv. Pre-compiled binaries are shipped for common platforms, reducing the need for compilation environments. This library is particularly useful for inter-process communication patterns requiring message boundary preservation (seqpacket) or connectionless datagram communication, as well as optimizing high-throughput TCP servers. While release cadence isn't explicitly stated, its focus on specific, low-level features suggests a stable, less frequent update cycle unless major Node.js changes necessitate it.

npm install node-unix-socket
INSTALL
IMPORT
SIG · NODE-UNIX-SOCKET
N
node-unix-socket
http-networkingjavascriptv0.2.7
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SeqpacketServer
import { SeqpacketServer } from 'node-unix-socket';
const { SeqpacketServer } = require('node-unix-socket');
ESM import for SeqpacketServer, typically used for server-side sequential packet communication.
SeqpacketSocket
import { SeqpacketSocket } from 'node-unix-socket';
const { SeqpacketSocket } = require('node-unix-socket');
ESM import for SeqpacketSocket, used as a client or peer for sequential packet communication. Note that Seqpacket sockets are not supported on macOS.
DgramSocket
import { DgramSocket } from 'node-unix-socket';
const { DgramSocket } = require('node-unix-socket');
ESM import for DgramSocket, enabling connectionless Unix datagram communication. The package exports a single class for both server and client roles in this context.

This example demonstrates how to set up a SeqpacketServer and connect a SeqpacketSocket client to it, sending multiple messages while preserving message boundaries, then cleaning up the socket file.

import { SeqpacketServer, SeqpacketSocket } from 'node-unix-socket'; import os from 'os'; import path from 'path'; import fs from 'fs'; const bindPath = path.resolve(os.tmpdir(), './my_seqpacket.sock'); // Ensure the socket file does not exist from previous runs try { fs.unlinkSync(bindPath); } catch (e) { // Ignore if file does not exist } // Create and start a Seqpacket server const server = new SeqpacketServer(); server.listen(bindPath); server.on('connection', (socket) => { console.log('Server: Client connected'); socket.on('data', (buf) => { console.log('Server: received', buf.toString()); }); socket.on('end', () => { console.log('Server: Client disconnected'); }); }); server.on('listening', () => { console.log(`Server listening on ${bindPath}`); }); server.on('error', (err) => { console.error('Server error:', err); }); // Create and connect a Seqpacket client const client = new SeqpacketSocket(); client.connect(bindPath, () => { console.log('Client: Connected to server'); const data = ['hello, ', 'w', 'o', 'r', 'l', 'd']; for (const str of data) { client.write(Buffer.from(str)); console.log(`Client: Sent '${str}'`); } client.end(() => { console.log('Client: Disconnected, closing server in 1 sec...'); setTimeout(() => server.close(), 1000); }); }); client.on('error', (err) => { console.error('Client error:', err); server.close(); // Ensure server closes on client error }); // Clean up on process exit process.on('exit', () => { try { fs.unlinkSync(bindPath); console.log('Cleaned up socket file.'); } catch (e) { // Ignore if file already removed or never created } });
Debug
Known issues
gotchaSOCK_SEQPACKET sockets are explicitly noted as not working on macOS. Attempting to use them on this platform will result in an error or undefined behavior.
fix
Ensure your deployment environment for SOCK_SEQPACKET sockets is Linux. For cross-platform compatibility, consider alternative IPC mechanisms like standard TCP sockets or other specialized libraries.
affects: >=0.1.0
gotchaThe behavior of SO_REUSEPORT can vary significantly across different operating systems, potentially leading to unexpected load balancing or connection distribution patterns compared to Node.js's native cluster module.
fix
Thoroughly test SO_REUSEPORT behavior on all target operating systems and Node.js versions. Consult OS-specific documentation and network stack behavior for accurate expectations. Implement robust monitoring to ensure connections are distributed as intended.
affects: >=0.1.0
gotchaAs a native Node.js addon, `node-unix-socket` relies on pre-compiled binaries. If a pre-built binary is not available for your specific Node.js version, architecture, or operating system, you may encounter compilation errors during installation.
fix
Check the project's supported platforms table in the README. Ensure your Node.js version, OS, and architecture match. If issues persist, refer to the `napi-rs` and Node.js N-API documentation for setting up a compilation environment, which may require specific toolchains (e.g., Python, C++ compiler, Node.gyp).
affects: >=0.1.0
Errors
Common errors & fixes
Error: The module '\path\to\node_modules\node-unix-socket\index.node' was compiled against a different Node.js version
The native addon was compiled for a different Node.js ABI version than the one currently running. This often happens after updating Node.js or when `npm install` was run with a different Node.js version.
fix
Rebuild the native modules for your current Node.js version by running `npm rebuild node-unix-socket` or `npm install` again. Ensure your Node.js version is supported by the package.
Error: bind EINVAL
This typically indicates an invalid argument was provided to the `bind` method, such as a malformed socket path or an unsupported operation for the specific socket type/OS.
fix
Double-check the socket path for validity and correct permissions. For `SOCK_SEQPACKET` or `SOCK_DGRAM` sockets, ensure the operating system (e.g., macOS for `SOCK_SEQPACKET`) actually supports the requested operation. Verify the path is absolute and within acceptable length limits for the OS.
Error: connect ENOENT / No such file or directory
The client attempted to connect to a Unix domain socket path that does not exist or has been removed. This usually means the server is not listening on that path.
fix
Ensure the server is running and has successfully created the socket file at the specified path before the client attempts to connect. Verify the path used by the client exactly matches the path the server is binding to. Check file system permissions if the path exists but is inaccessible.
Upgrade
Version history
0.2.7latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Amazon
1
Resources
node-unix-socket — npm install node-unix-socket · libregistry