Skip to content
Hoody Documentation
Download Page (.md)

Hoody Pipe

Section titled “Hoody Pipe”

The Pipe API streams data directly between HTTP clients over a single, shared URL. Data flows from sender to receiver with no server-side storage — useful for transferring files, text, or media between machines, containers, or browser sessions. Use these endpoints to send data, receive data, embed a video player, monitor transfer progress, or build a custom client on top of the Hoody Pipe service.

Web Interface

Section titled “Web Interface”

GET /api/v1/pipe

Section titled “GET /api/v1/pipe”

Returns the Hoody Pipe web interface — an HTML page for sending files or text to a pipe path from the browser. Also accessible at / (root alias).

This endpoint takes no parameters.

{
  "description": "HTML page with the Hoody Pipe web interface",
  "content": {
    "text/html": {
      "schema": {
        "type": "string"
      }
    }
  }
}
 
const html = await client.pipe.ui.getIndex();

GET /api/v1/pipe/noscript

Section titled “GET /api/v1/pipe/noscript”

Returns a pure HTML form for file/text upload that works without JavaScript. Useful in restricted browser environments or when JavaScript is disabled.

The page uses a CSP with a style nonce that blocks scripts. Path values are sanitized (leading slashes stripped, only URL-safe characters retained).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathquerystringNoPre-fill the pipe path. Only URL-safe characters allowed.
modequerystringNoInput mode: file for file picker, text for textarea. Allowed values: file, text. Default: "file".
{
  "description": "HTML form page with CSP nonce",
  "content": {
    "text/html": {
      "schema": {
        "type": "string"
      }
    }
  }
}
 
const html = await client.pipe.ui.getNoScript({
  path: "myfile",
  mode: "file"
});

Service Info

Section titled “Service Info”

GET /api/v1/pipe/health

Section titled “GET /api/v1/pipe/health”

Returns the standardized 9-field health response. Unauthenticated. Only reachable at /api/v1/pipe/health — a bare /health returns 404 with the body [ERROR] '/health' is not a valid path. Use '/api/v1/pipe/health'.\n. Methods other than GET/HEAD/OPTIONS return 405 with [ERROR] Method <verb> is not allowed.\n and Allow: GET, HEAD, OPTIONS.

This endpoint takes no parameters.

{
  "status": "ok",
  "service": "hoody-pipe",
  "built": "2024-01-15T10:30:00.000Z",
  "started": "2024-01-20T08:00:00.000Z",
  "memory": {
    "rss": 52428800,
    "heap": 15728640
  },
  "fds": 128,
  "pid": 12345,
  "ip": "10.0.0.5",
  "userAgent": "curl/8.4.0"
}
 
const health = await client.pipe.health.check();

GET /api/v1/pipe/help

Section titled “GET /api/v1/pipe/help”

Returns plain text usage instructions showing how to send and receive data using curl. The help text includes the server’s own URL (derived from the Host header) so examples can be copied and run directly. Sections cover receiving data, sending files/text/directories with curl -T, ?download and ?filename control, ?video browser playback, ?progress transfer monitoring, and end-to-end encryption with OpenSSL. Also accessible at /help.

This endpoint takes no parameters.

Hoody Pipe 1.6.1
Streaming Data Transfer over HTTP


======= Get  =======
curl https://pipe.example.com/mypath
 
const helpText = await client.pipe.info.getHelp();

Data Transfer

Section titled “Data Transfer”

GET /api/v1/pipe/{path}

Section titled “GET /api/v1/pipe/{path}”

Receive data from the specified pipe path. The response blocks until a sender connects and starts streaming. Once established, the response body contains the sender’s data with original headers forwarded.

Lifecycle:

  1. Receiver GETs a path — request blocks
  2. When a sender POSTs/PUTs to the same path with matching n, the pipe establishes
  3. Response starts streaming with the sender’s data
  4. Response completes when the sender finishes uploading

Headers forwarded from sender:

  • Content-Type — sender’s content type (dangerous types rewritten to text/plain; foreign params dropped except a safe charset)
  • Content-Length — only when the sender provided a valid ^\d{1,19}$ value AND the body is non-multipart (multipart parts use chunked encoding)
  • Content-Disposition — if provided (e.g. attachment; filename="report.pdf"); a sender-supplied inline is upgraded to attachment unless the effective Content-Type is on the inline-safe allowlist (image/audio/video/text/plain/application/pdf, excluding image/svg+xml)
  • X-Piping — custom metadata from sender
  • X-Hoody-Pipe — custom metadata from sender

Forwarded headers are CRLF-sanitized (Content-Disposition, X-Piping, X-Hoody-Pipe) to prevent header injection.

Download control: Receivers can override Content-Disposition behavior using query parameters:

  • ?download — force attachment disposition (triggers browser download)
  • ?download=false — suppress Content-Disposition entirely (always display inline)
  • ?filename=custom.txt — set a custom download filename (implies ?download)

These work per-receiver — with n=2, one receiver can download while the other displays inline.

Multi-receiver: When n > 1, all receivers get identical copies via lockstep fan-out — each chunk is written to every receiver before the next chunk is read from the sender. Memory is bounded to roughly one chunk per receiver, with no per-receiver queuing. The slowest receiver paces the entire transfer.

Connection ordering: The receiver can connect before the sender — the server holds the connection until the sender arrives (up to 5-minute TTL).

Security headers on response:

  • X-Robots-Tag: none — prevents indexing
  • X-Content-Type-Options: nosniff
  • CORS headers reflecting the receiver’s Origin

Also accessible without prefix (e.g. GET /myfile). Reserved paths (/help, /noscript, etc.) return their own content on GET instead of acting as pipe receivers.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesPipe path name to receive from — must match the path used by the sender.
nqueryintegerNoExpected number of receivers. Must match the sender’s n value exactly — a mismatch returns 400. When n > 1, the pipe waits for all n receivers and the sender before streaming. Default: 1.
downloadquerystringNoControl whether the response triggers a browser download. ?download, ?download=true, ?download=yes, ?download=1 force Content-Disposition: attachment. ?download=false, ?download=no, ?download=0 suppress Content-Disposition entirely. Absent — passthrough sender’s Content-Disposition as-is.
filenamequerystringNoSet a custom download filename. Implies ?download — the response will have Content-Disposition: attachment; filename="<value>". Null bytes, CRLF, path separators, leading dots, and control characters are stripped. Truncated to 255 characters.
videoquerystringNoReturn an HTML page with an embedded MSE (MediaSource Extensions) video player instead of raw pipe data. The player page fetches the raw stream internally — no pipe receiver slot is consumed. Only serves the HTML player when the client sends Accept: text/html. Values: ?video, ?video=true, ?video=yes, ?video=1 show the player. ?video=false, ?video=no, ?video=0 return a normal pipe receiver.
progressquerystringNoReturn real-time transfer progress as a Server-Sent Events (SSE) stream or HTML dashboard. Does NOT consume a pipe receiver slot. Accept: text/event-stream returns SSE. Accept: text/html returns an HTML dashboard. Values: ?progress, ?progress=true, ?progress=yes, ?progress=1 show progress. ?progress=false, ?progress=no, ?progress=0 return a normal pipe receiver.
Terminal window
curl https://pipe.example.com/api/v1/pipe/mypath
 
const stream = await client.pipe.receive({ path: "mypath" });

POST /api/v1/pipe/{path}

Section titled “POST /api/v1/pipe/{path}”

Send data to the specified pipe path. The sender’s request body is streamed directly to receiver(s) when they connect — no server-side storage.

Lifecycle:

  1. Sender POSTs to a path — gets back a streaming response with [INFO] status messages
  2. Server waits for n receivers to connect (default: 1)
  3. Once all receivers connect, data streams from sender to all receivers simultaneously
  4. Sender receives [INFO] Upload complete. then [INFO] Transfer complete.

Status messages (streamed to sender as text/plain):

[INFO] Waiting for 1 receiver(s) to connect...
[INFO] Streaming to 1 receiver(s)...
[INFO] Upload complete.
[INFO] Transfer complete.

Multipart uploads: When Content-Type matches multipart/form-data, the server extracts the first file part (non-file form fields are drained and skipped) and streams its contents. The part’s Content-Type and Content-Disposition are forwarded to receivers. Content-Length is NOT forwarded for multipart inputs — the response uses chunked transfer encoding.

Custom headers: Set X-Hoody-Pipe or X-Piping request headers to forward arbitrary metadata to receivers. Each header is capped at 8 KiB (over-cap headers are dropped) and CRLF/control chars are stripped. The receiver response carries Access-Control-Expose-Headers: X-Piping, X-Hoody-Pipe only when at least one was supplied.

Content-Type safety: Dangerous MIME types that execute scripts in browsers (text/html, image/svg+xml, application/javascript, XHTML/XML, etc.) are rewritten to text/plain. Parameters are stripped except for a single safe charset.

Connection ordering: Either sender or receiver(s) can connect first — the server holds the early party until counterparts arrive.

Limits:

  • Path length: max 1024 characters
  • Receiver count (n): 1–256
  • Pending transfers: max 1000 server-wide
  • Active transfers: max 1000 server-wide
  • Unestablished pipe TTL: 5 minutes

Also accessible without prefix (e.g. POST /myfile).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesUnique pipe path name. Must not be a reserved path (/, /help, /noscript, /favicon.ico, /robots.txt).
nqueryintegerNoNumber of receivers to wait for before starting the transfer. All receivers get identical copies of the data (fan-out). Must be a positive integer, max 256. Default: 1.

Request Body

Section titled “Request Body”

Data to stream to receiver(s). Any content type is accepted.

  • Binary files: Use application/octet-stream or the file’s actual MIME type
  • Text: Use text/plain
  • Multipart: Use multipart/form-data for browser uploads — only the first file part is streamed; leading non-file form fields are drained and skipped
  • No body: An empty POST is valid — receivers get an empty response
Terminal window
curl -T myfile.png https://pipe.example.com/api/v1/pipe/secret.png
 
await client.pipe.send({
  path: "secret.png",
  body: fileBuffer
});

PUT /api/v1/pipe/{path}

Section titled “PUT /api/v1/pipe/{path}”

Identical to POST — send data to the specified pipe path. PUT is provided as an alias because curl -T file URL uses PUT, making it natural for file transfers.

Terminal window
# Send a file (uses PUT)
curl -T myfile https://pipe.example.com/api/v1/pipe/mypath


# Send stdin
echo 'hello' | curl -T - https://pipe.example.com/api/v1/pipe/mypath


# Send a directory as tar.gz
tar czf - ./mydir | curl -T - https://pipe.example.com/api/v1/pipe/mydir.tar.gz

All parameters, request body handling, status messages, and error codes are identical to POST.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesUnique pipe path name (same rules as POST — no reserved paths, max 1024 chars).
nqueryintegerNoNumber of receivers to wait for (must match receivers’ n, max 256). Default: 1.

Request Body

Section titled “Request Body”

Data to stream — any content type. Multipart/form-data supported (first file part extracted; non-file fields are skipped).

Terminal window
curl -T myfile https://pipe.example.com/api/v1/pipe/mypath
 
await client.pipe.send({
  path: "mypath",
  method: "PUT",
  body: fileBuffer
});

OPTIONS /api/v1/pipe/{path}

Section titled “OPTIONS /api/v1/pipe/{path}”

Handles CORS preflight requests for cross-origin browser access. Returns permissive CORS headers reflecting the request Origin.

Headers returned:

  • Access-Control-Allow-Origin — reflects Origin (or * if none/null)
  • Access-Control-Allow-Methods — GET, POST, PUT, OPTIONS (HEAD is supported same-origin on reserved paths only)
  • Access-Control-Allow-Headers — Content-Type, Content-Disposition, Authorization, X-Piping, X-Hoody-Pipe
  • Access-Control-Allow-Credentials — true (when Origin present and not “null”)
  • Access-Control-Max-Age — 86400 (24 hours)
  • Access-Control-Allow-Private-Network — true (when requested)

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pathpathstringYesAny path — OPTIONS is handled identically for all paths.
Terminal window
curl -X OPTIONS https://pipe.example.com/api/v1/pipe/mypath \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: POST" \
  -i
 
await client.pipe.corsPreflight({ path: "mypath" });