Registry / http-networking / bouncy

bouncy

JSON →
librarypost-r5jsnpmunverified

bouncy is a low-level Node.js library that provides HTTP proxy and routing capabilities by wrapping `net.Server`. It allows programmatic redirection of raw HTTP traffic based on request headers (like `Host`), paths, or methods. Developers define routing logic within a callback function, gaining fine-grained control over request and response streams for tasks like load balancing or host-based multiplexing. Version `3.2.2` was published in October 2014, and the project shows no significant activity since then, indicating it is abandoned. It differs from higher-level HTTP frameworks by operating directly with Node.js's `net` and `tls` modules, offering a more primitive, stream-oriented approach to proxying.

http-networking
npm install bouncy
github ↗package ↗
INSTALL
IMPORT
SIG · BOUNCY
B
bouncy
http-networkingjavascriptvpost-r5
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

bouncy
✓ const bouncy = require('bouncy');
✗ import bouncy from 'bouncy';
bouncy is a CommonJS module. Direct ESM import (`import bouncy from 'bouncy'`) will result in a runtime error or require an explicit CommonJS wrapper or bundler configuration in modern Node.js environments.
server.listen
✓ server.listen(8000);
✗ bouncy.listen(8000);
The `bouncy` function returns a `net.Server` instance, so you call `.listen()` on the returned server object, not on `bouncy` itself.
bounce callback arity (req, res, bounce)
✓ bouncy(function (req, res, bounce) { /* ... */ });
✗ bouncy(function (req, bounce) { /* ... */ }); // If you need 'res'
The callback function passed to `bouncy` will receive `(req, res, bounce)` if its arity is 3, otherwise it receives `(req, bounce)`. If you need access to the `res` object to manipulate the response directly (e.g., set status codes for unhandled requests), ensure your function signature includes `res`.

This quickstart demonstrates how to use `bouncy` to create a host-based HTTP router. It sets up two backend servers on ports 8001 and 8002, and a `bouncy` proxy on port 8000. Requests are routed to different backends based on the `Host` header, or handled directly by the proxy, showing basic routing and direct response capabilities.

const bouncy = require('bouncy'); const http = require('http'); // Create a simple backend server 1 const backend1 = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end(`Hello from backend 8001 (Host: ${req.headers.host}, Path: ${req.url})`); }); backend1.listen(8001, () => console.log('Backend 8001 listening.')); // Create a simple backend server 2 const backend2 = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end(`Hello from backend 8002 (Host: ${req.headers.host}, Path: ${req.url})`); }); backend2.listen(8002, () => console.log('Backend 8002 listening.')); // Create the bouncy proxy server const proxyServer = bouncy(function (req, res, bounce) { console.log(`Incoming request for Host: ${req.headers.host}, URL: ${req.url}`); if (req.headers.host === 'beep.example.com') { console.log('Routing to 8001'); bounce(8001); } else if (req.headers.host === 'boop.example.com') { console.log('Routing to 8002'); bounce(8002, { path: '/custom-path' }); // Example of path modification } else if (req.url === '/admin') { // Example of direct response from proxy without bouncing res.statusCode = 200; res.end('Admin dashboard via proxy.'); } else { console.log('No route found, sending 404.'); res.statusCode = 404; res.end('No such host or route found.'); } }); proxyServer.listen(8000, () => console.log('Proxy server listening on port 8000.')); console.log('\nTo test, use curl or modify your /etc/hosts file:\n'); console.log(' curl -H "Host: beep.example.com" http://localhost:8000'); console.log(' curl -H "Host: boop.example.com" http://localhost:8000'); console.log(' curl http://localhost:8000/admin'); console.log(' curl http://localhost:8000/unknown-host');
Debug
Known issues
breakingThe `bouncy` package is abandoned and has not been updated since 2014. It is unlikely to receive security patches, bug fixes, or compatibility updates for newer Node.js versions or HTTP standards. Using it in production environments is highly discouraged due to potential security vulnerabilities and lack of maintenance.
fix
Consider migrating to a actively maintained proxy library like `http-proxy`, `node-http-proxy`, or `express-http-proxy` for modern Node.js applications.
affects: >=3.2.2
gotchaWhen configuring an HTTPS router using `bouncy`, `opts.key` and `opts.cert` are required. For environments with multiple SSL certificates requiring Server Name Indication (SNI), `opts.SNICallback` must be provided, following Node.js `tls.createServer` documentation. Misconfiguration can lead to failed HTTPS connections or certificate errors.
fix
Ensure `opts.key`, `opts.cert`, and `opts.SNICallback` (if needed) are correctly supplied to the `bouncy` constructor according to the Node.js `tls` module documentation. Test with tools like `openssl s_client` or `curl -v` to diagnose SSL/TLS handshake issues.
affects: >=3.0.0
gotchaThe callback function passed to `bouncy` receives different arguments based on its arity. A function declared with two arguments (`function (req, bounce)`) will not receive the `res` (response) object, which is crucial for sending direct responses or modifying headers before bouncing. To access `res`, the function must be declared with three arguments (`function (req, res, bounce)`).
fix
Always declare the callback function with three arguments, `function (req, res, bounce)`, if you intend to interact with the HTTP response object (e.g., `res.statusCode = 404; res.end('Not Found');`).
affects: >=1.0.0
gotcha`bouncy` operates at a relatively low level, directly piping streams. This means it doesn't automatically handle higher-level HTTP features or complex middleware chains common in modern web frameworks. Custom logic for things like authentication, rate limiting, or advanced request manipulation must be implemented manually within the `bouncy` callback.
fix
Be aware that `bouncy` provides a foundational proxy mechanism. Integrate `bouncy` within a larger application structure or use it for simpler, dedicated proxy tasks. For complex API gateways or advanced routing, consider full-featured proxy solutions or web frameworks with built-in proxy capabilities.
affects: All versions
Errors
Common errors & fixes
TypeError: bouncy is not a function
Attempting to use `bouncy` in a modern Node.js ESM context with `import bouncy from 'bouncy';` without proper configuration.
fix
Ensure your project is configured for CommonJS, or use `const bouncy = require('bouncy');` in a CommonJS module. If you must use ESM, consider a dynamic `import('bouncy')` after `require` is globally defined, or use a bundler that handles CJS-to-ESM conversion.
Error: self-signed certificate in certificate chain (or similar SSL/TLS error)
Incorrect or incomplete SSL/TLS configuration (`opts.key`, `opts.cert`) for an HTTPS proxy, or issues with certificate authorities.
fix
Verify that `opts.key` and `opts.cert` point to valid SSL certificate and private key files. For self-signed certificates in development, you might need to use `NODE_TLS_REJECT_UNAUTHORIZED=0` (not for production) or configure your client to trust the self-signed certificate.
RangeError: 'port' option should be a number
Providing a non-numeric value or an invalid port number to the `bounce()` function or `server.listen()`.
fix
Ensure that the port argument passed to `bounce()` or `server.listen()` is a valid integer between 1 and 65535. For example, `bounce(8001);` not `bounce('8001');` (though `bouncy`'s sugar syntax might handle string ports, it's best practice to use numbers).
Upgrade
Version history
post-r5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
OpenAI (training)
1
Resources
githubhttps://github.com/substack/bouncy ↗
packagehttps://www.npmjs.com/package/bouncy ↗
bouncy — npm install bouncy · libregistry