http-echo-server

library2.1.1jsnpmunverified

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.

testing http-networking

npm install http-echo-server

github ↗package ↗

INSTALL

IMPORT

SIG · HTTP-ECHO-SERVER

http-echo-server

testingjavascriptv2.1.1

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.

createServer

✓ import createServer from 'http-echo-server';

✗ import { createServer } from 'http-echo-server';

While primarily a CLI tool, the package exposes a `createServer` function for programmatic use. This function is a default export.

createServer (CommonJS)

✓ const createServer = require('http-echo-server');

✗ const { createServer } = require('http-echo-server');

For CommonJS environments, the `createServer` function is the default export of the module.

CLI usage

✓ npx http-echo-server

✗ node http-echo-server

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`.

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.

// Start the server via npx in a terminal // npx http-echo-server 8080 & // Wait a moment for the server to start, then test it in another terminal: // curl -X POST -d 'Hello World' -H 'Content-Type: text/plain' http://localhost:8080/test-path?param=value // Expected output from the server console (or what curl receives) will be the raw request: // POST /test-path?param=value HTTP/1.1 // Host: localhost:8080 // User-Agent: curl/7.88.1 // Accept: */* // Content-Type: text/plain // Content-Length: 11 // // Hello World // To use programmatically (less common, but possible): const createServer = require('http-echo-server'); async function startProgrammaticEchoServer() { const server = await createServer(8081); console.log(`Programmatic echo server started on port ${server.address().port}`); // Example curl for programmatic server: // curl -X GET http://localhost:8081/programmatic-test } startProgrammaticEchoServer();

http-echo-server --version

Debug

Known issues

gotchaThe server makes no attempt to understand the incoming HTTP request. It replies with the raw TCP stream content.

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.

affects: >=2.0.0

gotchaThe server terminates the TCP connection exactly 2 seconds after the first data packet is received, regardless of whether the full request has been transmitted.

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.

affects: >=2.0.0

gotchaWhen 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.

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.

affects: >=2.0.0

Errors

Common errors & fixes

Error: listen EADDRINUSE: address already in use :::<port>

The specified port for the HTTP echo server is already occupied by another process.

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.

command not found: http-echo-server

The `http-echo-server` executable is not found in the system's PATH.

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.

Upgrade

Version history

2.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/watson/http-echo-server ↗

packagehttps://www.npmjs.com/package/http-echo-server ↗