http-loro

CLI to spin up an HTTP server that mirrors the exact headers and body it receives, allowing you to configure the HTTP status code through a query string parameter.

(ver en español)

Installation

npm install -g http-loro

Usage

http-loro <port> [https] [options]

Basic HTTP example:

http-loro 3000

Any request sent to http://localhost:3000 will respond with:

• The same body that was received.
• The same headers that were received.
• A status code configurable via ?status=<code> (defaults to 200).

Request example

curl -i -X POST "http://localhost:3000/echo?status=201" \
  -H "Content-Type: application/json" \
  -d '{"message":"hola"}'

The response will have status code 201, preserve the sent headers, and return the same body.

Development scripts

• npm run dev: Runs the TypeScript CLI with tsx for a fast feedback loop.
• npm run start: Builds (through the prepare hook) and runs the compiled binary from dist on port 3000.
• npm run build: Emits the compiled output into dist/ via TypeScript (tsc).
• npm test: Executes the Mocha suite directly against the .ts sources.
• npm run lint: Checks code style and common issues via ESLint.

HTTPS mode (optional)

http-loro can also start an HTTPS server. This is useful for testing integrations that require https:// (Secure cookies, SameSite, etc.).

There are two ways to use it:

1. Quick shortcut: http-loro <port> https

This shortcut enables HTTPS using the default development certificates in ./certs/server.key and ./certs/server.crt:

http-loro 1234 https

These files are usually generated by the development flow (npm run dev:https), but you can create them yourself as well.

2. Direct binary usage with options

If you already have a certificate and key (for example in ./certs/server.key and ./certs/server.crt):

http-loro 3443 --https --key ./certs/server.key --cert ./certs/server.crt

Supported options:

• --https: enables HTTPS mode.
• --key <path>: path to the private key (PEM).
• --cert <path>: path to the certificate (PEM).
• --ca <path>: optional CA (PEM).
• --pfx <path>: PFX/PKCS#12 file (alternative to key/cert).
• --passphrase <value>: passphrase for the key or the PFX.

PFX example:

http-loro 3443 --https --pfx ./certs/server.pfx --passphrase MiPassphrase

3. Development mode with a self-signed certificate

For local development, the project includes a self-contained flow that generates a self-signed certificate using Node.js (compatible with Windows, macOS, and Linux):

npm run dev:https

This command:

1. Runs npm run dev:https-cert, which:

• Generates (if they do not exist) ./certs/server.key and ./certs/server.crt using the selfsigned library.
• Reuses them if they already exist.

2. Starts the server at https://localhost:3443 using those files.

Note: because it is a self-signed certificate, browsers and some tools will show a security warning; this is expected for development.

test/tests.http contains ready-to-use HTTP and HTTPS request examples.

Local hacking

To work directly from source without installing globally:

git clone https://github.com/matiasmuller/http-loro.git
cd http-loro
npm install
npm run dev 3000

The CLI accepts the same arguments when run with npm run dev (they are forwarded to tsx).

Requirements

• Node.js 18 or newer.

You do not need external tools like OpenSSL: the entire HTTPS development flow relies only on Node.js and NPM dependencies, so it works on Windows, macOS, and Linux.

---

CLI para levantar un servidor HTTP que refleja exactamente los headers y el cuerpo recibidos, permitiendo configurar el código de estado HTTP mediante un parámetro en la query string.

(see in english)

Instalación

npm install -g http-loro

Uso

http-loro <puerto> [https] [opciones]

Ejemplo básico HTTP:

http-loro 3000

Luego, cualquier request enviada a http://localhost:3000 responderá con:

• El mismo cuerpo recibido.
• Los mismos headers recibidos.
• Un código de estado configurable mediante ?status=<codigo> (por defecto 200).

Ejemplo de request

curl -i -X POST "http://localhost:3000/echo?status=201" \
  -H "Content-Type: application/json" \
  -d '{"message":"hola"}'

La respuesta tendrá código 201, conservará los headers enviados y devolverá el mismo cuerpo.

Scripts disponibles

• npm run dev: Ejecuta el binario TypeScript con tsx para un ciclo de pruebas rápido.
• npm run start: Compila previamente (a través de prepare) y ejecuta el binario en dist en el puerto 3000.
• npm run build: Genera la salida en dist/ con TypeScript (tsc).
• npm test: Corre la suite de Mocha directamente sobre los .ts.
• npm run lint: Analiza el código con ESLint para detectar problemas comunes.

Modo HTTPS (opcional)

http-loro también puede levantar un servidor HTTPS. Esto es útil para probar integraciones que requieren https:// (cookies Secure, SameSite, etc.).

Hay dos formas de usarlo:

1. Atajo sencillo: http-loro <puerto> https

Este atajo activa HTTPS usando los certificados por defecto de desarrollo en ./certs/server.key y ./certs/server.crt:

http-loro 1234 https

Normalmente estos ficheros los genera el flujo de desarrollo (npm run dev:https), pero también puedes crearlos tú mismo.

2. Uso directo del binario con opciones

Si ya tienes un certificado y clave (por ejemplo en ./certs/server.key y ./certs/server.crt):

http-loro 3443 --https --key ./certs/server.key --cert ./certs/server.crt

Opciones soportadas:

• --https: activa el modo HTTPS.
• --key <ruta>: ruta a la clave privada (PEM).
• --cert <ruta>: ruta al certificado (PEM).
• --ca <ruta>: CA opcional (PEM).
• --pfx <ruta>: fichero PFX/PKCS#12 (alternativa a key/cert).
• --passphrase <valor>: passphrase para la clave o el PFX.

Ejemplo con PFX:

http-loro 3443 --https --pfx ./certs/server.pfx --passphrase MiPassphrase

3. Modo desarrollo con certificado autofirmado

Para desarrollo local, el proyecto incluye un flujo autónomo que genera un certificado autofirmado usando Node.js (compatible con Windows, macOS y Linux):

npm run dev:https

Este comando:

1. Ejecuta npm run dev:https-cert, que:

• Genera (si no existen) ./certs/server.key y ./certs/server.crt usando la librería selfsigned.
• Si ya existen, los reutiliza.

2. Arranca el servidor en https://localhost:3443 usando esos ficheros.

Nota: al ser un certificado autofirmado, los navegadores y algunas herramientas mostrarán una advertencia de seguridad; para desarrollo esto es esperado.

En test/tests.http hay ejemplos de peticiones HTTP y HTTPS listas para usar.

Hacking local

Para trabajar directamente desde el código fuente sin instalar globalmente:

git clone https://github.com/matiasmuller/http-loro.git
cd http-loro
npm install
npm run dev 3000

El binario acepta los mismos argumentos cuando se ejecuta con npm run dev (se reenvían a tsx).

Requisitos

• Node.js 18 o superior.

No se requieren herramientas externas como OpenSSL: todo el flujo de HTTPS de desarrollo se basa únicamente en Node.js y dependencias NPM, por lo que es compatible con Windows, macOS y Linux.