{"id":13310,"library":"http-echo-server","title":"HTTP Echo Server","description":"The `http-echo-server` package provides a minimalist HTTP server designed primarily for debugging and testing network requests. It accepts any TCP connection and immediately echoes back the entire incoming TCP content as an HTTP response. Crucially, it does not parse or understand the HTTP protocol, meaning it will respond with the raw bytes received, including headers and body, without interpretation. The server will terminate the TCP connection exactly 2 seconds after the first data packet is received, regardless of whether the full request has arrived. This behavior makes it unsuitable for production environments or as a general-purpose HTTP server but highly effective for inspecting raw network traffic. The current stable version is 2.1.1. Given its utility nature, the release cadence is likely infrequent, driven by bug fixes or minor enhancements. Its key differentiator is its deliberate simplicity and lack of HTTP protocol understanding, making it a 'transparent pipe' for raw request inspection.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/watson/http-echo-server","tags":["javascript","http","tcp","echo","server","debug","debugger","test"],"install":[{"cmd":"npm install http-echo-server","lang":"bash","label":"npm"},{"cmd":"yarn add http-echo-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add http-echo-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, the package exposes a `createServer` function for programmatic use. This function is a default export.","wrong":"import { createServer } from 'http-echo-server';","symbol":"createServer","correct":"import createServer from 'http-echo-server';"},{"note":"For CommonJS environments, the `createServer` function is the default export of the module.","wrong":"const { createServer } = require('http-echo-server');","symbol":"createServer (CommonJS)","correct":"const createServer = require('http-echo-server');"},{"note":"The most common and recommended way to use this utility is via the command-line interface, either through `npx` (for local installations) or after a global `npm install -g http-echo-server`.","wrong":"node http-echo-server","symbol":"CLI usage","correct":"npx http-echo-server"}],"quickstart":{"code":"    // Start the server via npx in a terminal\n    // npx http-echo-server 8080 &\n\n    // Wait a moment for the server to start, then test it in another terminal:\n    // curl -X POST -d 'Hello World' -H 'Content-Type: text/plain' http://localhost:8080/test-path?param=value\n\n    // Expected output from the server console (or what curl receives) will be the raw request:\n    // POST /test-path?param=value HTTP/1.1\n    // Host: localhost:8080\n    // User-Agent: curl/7.88.1\n    // Accept: */*\n    // Content-Type: text/plain\n    // Content-Length: 11\n    //\n    // Hello World\n\n    // To use programmatically (less common, but possible):\n    const createServer = require('http-echo-server');\n\n    async function startProgrammaticEchoServer() {\n      const server = await createServer(8081);\n      console.log(`Programmatic echo server started on port ${server.address().port}`);\n      // Example curl for programmatic server:\n      // curl -X GET http://localhost:8081/programmatic-test\n    }\n\n    startProgrammaticEchoServer();","lang":"javascript","description":"Demonstrates starting the HTTP echo server via the command line using `npx` and testing it with `curl`, showing the raw request echoing. It also includes an example of programmatic server creation."},"warnings":[{"fix":"Understand that the server replies with the raw incoming TCP stream content, not a parsed HTTP response. Do not expect standard HTTP parsing, routing, or header interpretation beyond simple echoing.","message":"The server makes no attempt to understand the incoming HTTP request. It replies with the raw TCP stream content.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Be aware of the fixed 2-second connection timeout after initial data. Ensure your requests complete within this window or adjust expectations for partial responses, as longer requests will be cut off.","message":"The server terminates the TCP connection exactly 2 seconds after the first data packet is received, regardless of whether the full request has been transmitted.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Account for additional Heroku-specific headers (e.g., `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Request-ID`) in the echoed response when debugging Heroku deployments. The echoed content will include these additions.","message":"When deploying `http-echo-server` to Heroku, the Heroku routing stack will proxy the incoming request and add custom HTTP headers to the request before it reaches the echo server.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Choose a different port (e.g., `http-echo-server 3005`), identify and terminate the conflicting process using tools like `lsof -i :<port>` (macOS/Linux) or `netstat -ano | findstr :<port>` (Windows), or ensure no other instance of the echo server is running.","cause":"The specified port for the HTTP echo server is already occupied by another process.","error":"Error: listen EADDRINUSE: address already in use :::<port>"},{"fix":"Run the command using `npx http-echo-server` (if the package is installed locally in your project), or ensure the package is installed globally with `npm install -g http-echo-server` and your global npm bin directory is in your system's PATH.","cause":"The `http-echo-server` executable is not found in the system's PATH.","error":"command not found: http-echo-server"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"http-echo-server","cli_version":null}