{"id":16070,"library":"http-proxy-3","title":"HTTP Proxy 3","description":"http-proxy-3 is an actively maintained, modern rewrite of the popular `http-proxy` library for Node.js, currently at version 1.23.2. It provides programmable HTTP/HTTPS and WebSocket proxying capabilities, suitable for building reverse proxies, load balancers, or API gateways. Key differentiators include a complete rewrite in TypeScript for enhanced type safety and maintainability, full HTTP/2 support via the `fetch` API, and comprehensive updates to all dependent packages to address security vulnerabilities. The library explicitly fixes known socket leaks and uncatchable WebSocket errors present in the unmaintained original `http-proxy`. It is used in production by major projects like Vite, CoCalc, and JupyterHub, ensuring a stable and reliable solution for integrating application logic with proxy server functionality.","status":"active","version":"1.23.2","language":"javascript","source_language":"en","source_url":"https://github.com/sagemathinc/http-proxy-3","tags":["javascript","typescript"],"install":[{"cmd":"npm install http-proxy-3","lang":"bash","label":"npm"},{"cmd":"yarn add http-proxy-3","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-proxy-3","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"http-proxy-3 is primarily designed for ES Modules, though CommonJS `require` might work with transpilation or specific Node.js loader configurations. `createProxyServer` is the main factory function.","wrong":"const httpProxy = require('http-proxy-3'); const proxy = httpProxy.createProxyServer();","symbol":"createProxyServer","correct":"import { createProxyServer } from 'http-proxy-3';"},{"note":"This type definition is crucial for TypeScript users to correctly configure the proxy server instance.","symbol":"ProxyServerOptions","correct":"import type { ProxyServerOptions } from 'http-proxy-3';"},{"note":"Represents the instance returned by `createProxyServer`, useful for type annotations when working with proxy event listeners or methods like `web()` and `ws()`.","symbol":"ProxyServer","correct":"import type { ProxyServer } from 'http-proxy-3';"}],"quickstart":{"code":"import * as http from 'node:http';\nimport { createProxyServer, type ProxyServerOptions } from 'http-proxy-3';\n\n// Create a target HTTP server\nconst targetServer = http.createServer((req, res) => {\n  console.log(`Target received: ${req.method} ${req.url}`);\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('Hello from the target server!');\n});\n\ntargetServer.listen(9000, () => {\n  console.log('Target server listening on http://localhost:9000');\n});\n\n// Create a basic HTTP proxy server\nconst proxyOptions: ProxyServerOptions = {\n  target: 'http://localhost:9000',\n  ws: true // Enable websocket proxying\n};\n\nconst proxy = createProxyServer(proxyOptions);\n\n// Handle proxy errors\nproxy.on('error', (err, req, res) => {\n  console.error('Proxy Error:', err);\n  if (res && res.writeHead) {\n    res.writeHead(500, { 'Content-Type': 'text/plain' });\n    res.end('Something went wrong with the proxy.');\n  }\n});\n\n// Create a proxy listening server\nconst proxyServer = http.createServer((req, res) => {\n  console.log(`Proxying request: ${req.method} ${req.url}`);\n  proxy.web(req, res);\n});\n\nproxyServer.on('upgrade', (req, socket, head) => {\n  console.log(`Proxying websocket upgrade: ${req.url}`);\n  proxy.ws(req, socket, head);\n});\n\nproxyServer.listen(8000, () => {\n  console.log('Proxy server listening on http://localhost:8000');\n  console.log('Test with: curl http://localhost:8000');\n  console.log('Test websockets with a client connecting to ws://localhost:8000');\n});","lang":"typescript","description":"This quickstart sets up a basic HTTP and WebSocket proxy that forwards requests from port 8000 to a target server running on port 9000, demonstrating core proxying functionality and error handling."},"warnings":[{"fix":"Upgrade Node.js to version 18 or newer.","message":"http-proxy-3 requires Node.js version 18 or higher. Applications running on older Node.js runtimes must upgrade their environment before adopting this package.","severity":"breaking","affected_versions":"<1.23.0"},{"fix":"Thoroughly test existing proxy configurations after upgrading from `http-proxy`. Review and update any custom request/response handling logic that might rely on older Node.js or `http-proxy` internals.","message":"This library is a complete rewrite of `http-proxy`, addressing many longstanding issues including socket leaks and uncatchable WebSocket errors in the original package. While API compatible, direct migration from `http-proxy` may expose subtle behavioral changes or require updating code that relied on deprecated/insecure APIs (e.g., `URL` instead of `parse`).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Benchmark your application's specific use case to determine the impact. Optimize backend services or consider alternative architectures if the performance overhead is unacceptable.","message":"The README notes that using the proxy server introduces a performance penalty, with proxied operations potentially taking 'about twice as long' compared to direct connections. This should be considered for highly performance-sensitive applications.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use HTTP/2 features with caution in production environments. Monitor release notes for changes related to HTTP/2 support and be prepared to adapt configurations as the feature matures.","message":"HTTP/2 support in http-proxy-3 is achieved via the `fetch` API and is currently marked as 'experimental'. While functional and tested, the API and behavior may change in future versions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Immediately upgrade to http-proxy-3 to benefit from this and other security patches.","message":"http-proxy-3 fixes a significant security vulnerability (related to issue #1647 in the original http-party/node-http-proxy). Using older, unmaintained versions of `http-proxy` exposes applications to this vulnerability.","severity":"breaking","affected_versions":"<1.0.0 (for http-proxy-3); all versions of unpatched http-proxy"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the proxy's listening port to an available one, or stop the process currently using the port (e.g., `kill -9 <PID>` on Linux/macOS or `netstat -ano | findstr :<PORT>` followed by `taskkill /PID <PID> /F` on Windows).","cause":"The port the proxy server is trying to listen on is already in use by another process.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"fix":"Ensure the target server is running and accessible at the configured `target` address and port. Verify no firewalls are blocking the connection between the proxy and target.","cause":"The proxy server could not connect to the target server because the target server is not running or its address/port is incorrect.","error":"Error: connect ECONNREFUSED 127.0.0.1:9000"},{"fix":"Confirm that the target server correctly implements and listens for WebSocket connections. Ensure `ws: true` is set in the `createProxyServer` options if you intend to proxy WebSockets.","cause":"The proxy failed to establish a WebSocket connection to the target server, often because the target does not support WebSockets or the WebSocket server isn't running.","error":"Proxy Error: Could not proxy request /socket.io/?EIO=3&transport=websocket to ws://localhost:9000/socket.io/?EIO=3&transport=websocket (ECONNREFUSED)"},{"fix":"Provide the necessary authentication credentials in the proxy configuration if `http-proxy-3` is acting as a client to another authenticated proxy, or ensure your client accessing `http-proxy-3` provides valid credentials if `http-proxy-3` is configured to require them.","cause":"The proxy itself (or an upstream proxy) requires authentication before it will forward the request.","error":"HTTP/1.1 407 Proxy Authentication Required"},{"fix":"Inspect the responses from your target server for invalid characters or formatting in HTTP headers. This often indicates an issue with the target server's HTTP implementation.","cause":"The target server returned a malformed HTTP header, which Node.js's HTTP parser cannot interpret.","error":"Error: Parse Error: HPE_INVALID_HEADER_TOKEN"}],"ecosystem":"npm"}