bufferutil

bufferutil provides low-level buffer utilities for masking and unmasking WebSocket frame payloads as specified by RFC 6455. It’s implemented as a native addon built on Node’s N-API and exposes two functions, mask and unmask, that XOR a payload buffer against a 4-byte WebSocket masking key. A pure-JavaScript fallback ships alongside the native binary so the package still works correctly, if more slowly, on platforms without a prebuilt binary.

Maintained by the websockets organization, bufferutil is best known as the optional native-acceleration dependency of the ws WebSocket library, where it removes a hot-path bottleneck in frame processing. Prebuilt binaries for common OS/architecture/Node-version combinations are published via prebuildify and loaded automatically at install time through node-gyp-build, so most consumers never need a local compiler toolchain.

What You Get

• A native N-API addon exposing mask and unmask functions for WebSocket frame buffer manipulation
• A pure-JavaScript fallback implementation (fallback.js) for platforms without a prebuilt binary
• Prebuilt binaries for common platforms distributed via prebuildify, avoiding a native compile step for most installs
• Automatic binary/fallback selection through node-gyp-build, requiring no manual configuration
• A parity test suite that validates the native implementation against the fallback across a range of buffer sizes and offsets

Common Use Cases

• Accelerating outbound WebSocket frame masking in client and server implementations
• Accelerating inbound WebSocket frame unmasking during message parsing
• Serving as an optional dependency of a custom WebSocket client or server implementation
• Cross-platform Node.js deployments that need correct masking behavior even where a native build is unavailable

Under The Hood

Architecture The package is intentionally minimal: index.js is a thin loader that asks node-gyp-build for a prebuilt native binary matching the current platform and, if that fails, falls back to a pure-JS implementation in fallback.js. The native side is a single C file (src/bufferutil.c) compiled via binding.gyp that registers two N-API functions, Mask and Unmask, through a standard NAPI_MODULE init. There is no internal layering beyond loader → implementation, which is appropriate given the package does exactly one job; changing the core masking algorithm means editing the C file and keeping fallback.js in lockstep, which the test suite enforces.

Tech Stack The native implementation is C compiled against Node’s N-API (node_api.h) via node-gyp/binding.gyp, with prebuildify producing cross-platform prebuilt binaries and node-gyp-build (the sole runtime dependency) selecting the right one at install/require time. The JavaScript surface is plain CommonJS with no framework or transpilation step. Tests run under Mocha. There is no database, web framework, or ORM involved — this is a pure computation utility.

Code Quality The Mocha test suite runs the native and fallback implementations through the same masking/unmasking assertions and additionally cross-checks their outputs against each other across multiple buffer sizes and offsets, which is a strong parity-testing pattern for a package with two independent implementations of the same logic. CI (GitHub Actions) runs the test suite across a wide matrix of OS, CPU architecture, and Node.js versions, and a separate release job builds and publishes prebuilt binaries per platform on tag pushes. Error handling in the C code relies on assert() against N-API status codes rather than graceful propagation, which is a common (if blunt) pattern in small native addons. There are no TypeScript type definitions and no lint/format tooling configured in the repository.

What Makes It Unique The masking routine aligns memory access and applies the mask in 64-bit chunks after a short alignment preamble, reducing per-byte overhead versus a naive byte-by-byte XOR loop — a standard but effective low-level optimization technique. The combination of prebuilt binaries plus an automatic pure-JS fallback is a well-established pattern in the native Node addon ecosystem rather than something unique to this package, but it’s executed cleanly here with thorough cross-platform CI coverage.