bhttp-ts

A BHTTP (RFC 9292: Binary Representation of HTTP Messages) encoder and decoder for the Request/Response interface of Fetch API.

This module works on Node.js, Cloudflare Workers, and other JavaScript runtimes supporting the Fetch API.

Note: This is a fork of dajiaji/bhttp-js, converted from Deno to a standard npm package.

Installation

npm install bhttp-ts

Usage

Encode/Decode Request

import { BHttpDecoder, BHttpEncoder } from "bhttp-ts";

const req = new Request("https://www.example.com/hello.txt", {
  method: "GET",
  headers: {
    "User-Agent": "curl/7.16.3 libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3",
    "Accept-Language": "en, mi",
  },
});

// Encode a Request object to a BHTTP binary
const encoder = new BHttpEncoder();
const binReq = await encoder.encodeRequest(req);

// Decode the BHTTP binary to a Request object
const decoder = new BHttpDecoder();
const decodedReq = decoder.decodeRequest(binReq);

Encode/Decode Response

import { BHttpDecoder, BHttpEncoder } from "bhttp-ts";

const res = new Response("Hello World!", {
  status: 200,
  headers: { "Content-Type": "text/plain" },
});

// Encode a Response object to a BHTTP binary
const encoder = new BHttpEncoder();
const binRes = await encoder.encodeResponse(res);

// Decode the BHTTP binary to a Response object
const decoder = new BHttpDecoder();
const decodedRes = decoder.decodeResponse(binRes);

Streaming API

For indeterminate-length messages, use the streaming encoders and decoder:

import {
  BHttpRequestStreamEncoder,
  BHttpResponseStreamEncoder,
  BHttpStreamDecoder,
} from "bhttp-ts";

// Streaming request encoding
const reqEncoder = new BHttpRequestStreamEncoder();
yield reqEncoder.encodePreamble("POST", "https", "example.com", "/api", headers);
yield reqEncoder.encodeContentChunk(chunk1);
yield reqEncoder.encodeContentChunk(chunk2);
yield reqEncoder.encodeEnd();

// Streaming response encoding
const resEncoder = new BHttpResponseStreamEncoder();
yield resEncoder.encodePreamble(200, headers);
yield resEncoder.encodeContentChunk(chunk1);
yield resEncoder.encodeEnd(trailers);

// Streaming decode
const decoder = new BHttpStreamDecoder();
for (const chunk of incomingData) {
  for (const event of decoder.push(chunk)) {
    switch (event.type) {
      case "request-preamble":
        // event.method, event.scheme, event.authority, event.path, event.headers
        break;
      case "response-preamble":
        // event.status, event.headers
        break;
      case "content":
        // event.data
        break;
      case "trailers":
        // event.headers
        break;
    }
  }
}
for (const event of decoder.end()) {
  // handle final events
}

When working with Fetch Request and Response objects, the high-level streaming methods preserve backpressure and cancellation automatically:

const encoder = new BHttpEncoder();
const decoder = new BHttpDecoder();

const encoded = encoder.encodeRequestStream(request);
const decoded = await decoder.decodeRequestStream(encoded);

Response equivalents are encodeResponseStream and decodeResponseStream. For GET/HEAD requests and 204/205/304 responses, decoding consumes and validates the complete input through EOF before resolving, while discarding content. Other messages finish validation when their decoded body is consumed to EOF. The existing BHttpRequestStreamEncoder, BHttpResponseStreamEncoder, and BHttpStreamDecoder remain available when manual framing is required.

API

BHttpEncoder

• encodeRequest(request: Request, options?: BHttpEncoderOptions): Promise<Uint8Array> - Encode a Request to known-length BHTTP
• encodeResponse(response: Response, options?: BHttpEncoderOptions): Promise<Uint8Array> - Encode a Response to known-length BHTTP
• encodeRequestStream(request: Request, options?: BHttpEncoderOptions): ReadableStream<Uint8Array> - Encode a streaming Request to indeterminate-length BHTTP
• encodeResponseStream(response: Response, options?: BHttpEncoderOptions): ReadableStream<Uint8Array> - Encode a streaming Response to indeterminate-length BHTTP

BHttpEncoderOptions accepts padding and maxMessageSize. Padding defaults to 0 (disabled), including when only maxMessageSize is set. A positive safe integer pads the complete encoded message to that byte multiple, using zero bytes after the trailers. For example, padding: 1024 rounds a 1,100-byte message up to 2,048 bytes. Already aligned messages receive no extra padding.

const bytes = await encoder.encodeRequest(request, { padding: 1024 });
const stream = encoder.encodeResponseStream(response, { padding: 16384 });

A function policy receives the unpadded encoded size and returns the padded total, a safe integer at least as large as its input. It must never decrease as input grows, because streaming encoders check the limit as bytes arrive. Use padmeWithFloor(1024) for Padmé with a 1 KiB floor. padme implements PURBs (Nikitin et al., 2019).

maxMessageSize includes padding; exceeding it throws MessageLimitExceededError (or errors the stream). Streaming padding is emitted at EOF in bounded blocks, without buffering the whole message. Manual framing encoders remain unpadded.

Buffered encoders allocate the full padded message. maxMessageSize defaults to Number.MAX_SAFE_INTEGER, so large padding values can cause large allocations. Set an explicit encoded-size limit, for example { padding: 1024, maxMessageSize: 1048576 }.

BHttpDecoder

• decodeRequest(data: ArrayBuffer | Uint8Array): Request - Decode BHTTP to a Request
• decodeResponse(data: ArrayBuffer | Uint8Array): Response - Decode BHTTP to a Response
• decodeRequestStream(stream: ReadableStream<Uint8Array>): Promise<Request> - Decode a streaming BHTTP request
• decodeResponseStream(stream: ReadableStream<Uint8Array>): Promise<Response> - Decode a streaming BHTTP response

BHttpRequestStreamEncoder / BHttpResponseStreamEncoder

For encoding indeterminate-length messages incrementally.

BHttpStreamDecoder

For decoding BHTTP messages incrementally, emitting events as data arrives.

References

• RFC 9292: Binary Representation of HTTP Messages
• Fetch - Living Standard

License

MIT - See LICENSE for details.