{"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,"search_vec":"'1.23.2':26 '3':3,7 'activ':10 'address':74 'api':43,65 'applic':117 'balanc':41 'build':37 'capabl':34 'cocalc':106 'complet':49 'comprehens':67 'current':23 'depend':71 'differenti':46 'enhanc':54 'ensur':109 'error':87 'explicit':79 'fetch':64 'fix':80 'full':59 'function':122 'gateway':44 'http':1,5,18,94 'http-proxi':4,17,93 'http/2':60 'http/https':30 'includ':47 'integr':116 'javascript':123 'jupyterhub':108 'key':45 'known':81 'leak':83 'librari':20,78 'like':104 'load':40 'logic':118 'maintain':11,58 'major':102 'modern':12 'node.js':22 'origin':92 'packag':72 'popular':16 'present':88 'product':100 'programm':29 'project':103 'provid':28 'proxi':2,6,19,33,39,95,120 'reliabl':113 'revers':38 'rewrit':13,50 'safeti':56 'secur':75 'server':121 'socket':82 'solut':114 'stabl':111 'suitabl':35 'support':61 'type':55 'typescript':52,124 'uncatch':85 'unmaintain':91 'updat':68 'use':98 'version':25 'via':62 'vite':105 'vulner':76 'websocket':32,86","created_at":"2026-04-21T19:18:06.502939+00:00","updated_at":"2026-04-21T19:18:06.502939+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sagemathinc/http-proxy-3","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/http-proxy-3","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}