@procedures/http 0.0.0-stage → 0.3.0

package/src/parsers.ts

@@ -0,0 +1,184 @@
+/**
+ * The stream parsers of the HTTP procedures: the lines of NDJSON and the events of an event
+ * stream (the `text/event-stream` format of the HTML standard). Each parser reads chunks of
+ * bytes, so a line or a character can arrive in two chunks.
+ */
+
+import { HttpError } from "./errors.js";
+
+/** One line of an NDJSON stream. */
+export interface NdjsonLine {
+  /** The number of the line: the first line is 1. Blank lines count. */
+  readonly line: number;
+  readonly text: string;
+}
+
+const LF = 0x0a;
+const CR = 0x0d;
+
+function bytesOf(chunk: Uint8Array | string): Buffer {
+  return typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+}
+
+/**
+ * This function gives each line of a stream of bytes that is not blank. A line ends at LF, and a
+ * CR before the LF is removed. A line of more than `maxLineBytes` bytes throws `LINE_TOO_LARGE`.
+ * The last line can end without LF. A byte order mark at the start is removed.
+ */
+export async function* ndjsonLines(chunks: AsyncIterable<Uint8Array | string>, maxLineBytes: number, label = "http.ndjson"): AsyncGenerator<NdjsonLine, void, undefined> {
+  let pending: Buffer[] = [];
+  let pendingSize = 0;
+  let number = 0;
+  const tooLarge = (): HttpError => new HttpError("LINE_TOO_LARGE", `${label}: line ${number + 1} has more than ${maxLineBytes} bytes (maxLineBytes)`);
+  const finish = (last: Buffer): NdjsonLine | undefined => {
+    let bytes = pending.length === 0 ? last : Buffer.concat([...pending, last]);
+    pending = [];
+    pendingSize = 0;
+    if (bytes.length > 0 && bytes[bytes.length - 1] === CR) bytes = bytes.subarray(0, bytes.length - 1);
+    if (bytes.length > maxLineBytes) throw tooLarge();
+    number++;
+    let text = bytes.toString("utf8");
+    if (number === 1 && text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+    return text.trim() === "" ? undefined : { line: number, text };
+  };
+  for await (const chunk of chunks) {
+    const buffer = bytesOf(chunk);
+    let start = 0;
+    for (;;) {
+      const end = buffer.indexOf(LF, start);
+      if (end < 0) break;
+      if (pendingSize + (end - start) > maxLineBytes + 1) throw tooLarge();
+      const line = finish(buffer.subarray(start, end));
+      if (line) yield line;
+      start = end + 1;
+    }
+    if (start < buffer.length) {
+      const rest = buffer.subarray(start);
+      pendingSize += rest.length;
+      // One more byte for a CR before the LF
+      if (pendingSize > maxLineBytes + 1) throw tooLarge();
+      pending.push(Buffer.from(rest));
+    }
+  }
+  if (pendingSize > 0) {
+    const line = finish(Buffer.alloc(0));
+    if (line) yield line;
+  }
+}
+
+/** One server-sent event. */
+export interface ServerSentEvent {
+  /** The type of the event: the `event` field, or `message`. */
+  readonly event: string;
+  /** The data: the `data` fields of the event, joined with LF. */
+  readonly data: string;
+  /** The last event ID: the last `id` field of the stream, when it is not empty. */
+  readonly id?: string;
+  /** The reconnection time that the event gave with a `retry` field, in milliseconds. */
+  readonly retry?: number;
+}
+
+/**
+ * This function gives each event of an event stream. It obeys the parse rules of the HTML
+ * standard: a line ends at CR, LF or CRLF, a blank line sends the event, a line that starts with a
+ * colon is a comment, and an event without data is not sent. An event of more than
+ * `maxEventBytes` bytes throws `EVENT_TOO_LARGE`. At the end of the stream, an event without its
+ * blank line is not sent.
+ */
+export async function* sseEvents(chunks: AsyncIterable<Uint8Array | string>, maxEventBytes: number, label = "http.sse"): AsyncGenerator<ServerSentEvent, void, undefined> {
+  // The decoder removes the byte order mark and keeps a character whose bytes are in two chunks
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  let skipLf = false;
+  let data = "";
+  let dataBytes = 0;
+  let eventType = "";
+  let lastEventId = "";
+  let retry: number | undefined;
+  const tooLarge = (): HttpError => new HttpError("EVENT_TOO_LARGE", `${label}: an event has more than ${maxEventBytes} bytes (maxEventBytes)`);
+
+  /** The event of a blank line, or undefined. */
+  const dispatch = (): ServerSentEvent | undefined => {
+    const event: ServerSentEvent | undefined =
+      data === ""
+        ? undefined
+        : {
+            event: eventType === "" ? "message" : eventType,
+            data: data.endsWith("\n") ? data.slice(0, -1) : data,
+            ...(lastEventId !== "" ? { id: lastEventId } : {}),
+            ...(retry !== undefined ? { retry } : {}),
+          };
+    data = "";
+    dataBytes = 0;
+    eventType = "";
+    retry = undefined;
+    return event;
+  };
+
+  const field = (line: string): void => {
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const name = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    switch (name) {
+      case "event":
+        eventType = value;
+        break;
+      case "data":
+        dataBytes += Buffer.byteLength(value) + 1;
+        if (dataBytes > maxEventBytes + 1) throw tooLarge();
+        data += `${value}\n`;
+        break;
+      case "id":
+        if (!value.includes("\u0000")) lastEventId = value;
+        break;
+      case "retry":
+        if (/^[0-9]+$/.test(value)) retry = Number(value);
+        break;
+      default:
+        break;
+    }
+  };
+
+  const lines = function* (text: string, end: boolean): Generator<string> {
+    buffer += text;
+    let start = 0;
+    if (skipLf && buffer.length > 0) {
+      if (buffer.charCodeAt(0) === 0x0a) start = 1;
+      skipLf = false;
+    }
+    for (let i = start; i < buffer.length; i++) {
+      const code = buffer.charCodeAt(i);
+      if (code !== 0x0a && code !== 0x0d) continue;
+      yield buffer.slice(start, i);
+      if (code === 0x0d) {
+        if (i + 1 < buffer.length) {
+          if (buffer.charCodeAt(i + 1) === 0x0a) i++;
+        } else {
+          // A CR at the end of a chunk: an LF at the start of the next chunk is the same line end
+          skipLf = true;
+        }
+      }
+      start = i + 1;
+    }
+    buffer = buffer.slice(start);
+    if (!end && buffer.length > maxEventBytes) throw tooLarge();
+  };
+
+  const feed = function* (text: string, end: boolean): Generator<ServerSentEvent> {
+    for (const line of lines(text, end)) {
+      if (line === "") {
+        const event = dispatch();
+        if (event) yield event;
+      } else {
+        field(line);
+      }
+    }
+  };
+
+  for await (const chunk of chunks) {
+    yield* feed(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }), false);
+  }
+  yield* feed(decoder.decode(), true);
+}

package/src/policy.ts

@@ -0,0 +1,192 @@
+/**
+ * The host policy of the HTTP procedures (roadmap R38): the hosts that a request can reach.
+ *
+ * - The default policy allows each public host and refuses the other addresses: loopback,
+ *   private, link-local, shared, multicast and reserved (see `address.ts`).
+ * - `allow` names more hosts: a host name (`api.example.com`), a wildcard (`*.example.com`), an
+ *   IP address (`127.0.0.1`, `::1`) or a CIDR range (`10.0.0.0/8`). An entry can end with a port:
+ *   `localhost:8080`, `[::1]:8080`, `10.0.0.0/8:443`. Without a port, an entry allows each port.
+ * - `publicHosts: false` refuses the public hosts too: only the entries of `allow` stay.
+ *
+ * The check resolves the host name and examines each address. The connection uses only the
+ * addresses that the check allowed, so a second answer of the DNS cannot change the address
+ * (DNS rebinding). A redirect goes through the same check. A refusal is `FORBIDDEN` with the
+ * reason `host-not-allowed`.
+ */
+
+import { lookup } from "node:dns/promises";
+import { InvocationError, type ProcedurePath } from "@procedures/client";
+import { formatAddress, parseAddress, parseRange, rangeHas, specialClass, type AddressBytes, type AddressRange } from "./address.js";
+
+/** The reason of the `FORBIDDEN` error for a host that the policy does not allow. */
+export const HOST_NOT_ALLOWED = "host-not-allowed";
+
+/** One address of a host name. */
+export interface ResolvedAddress {
+  readonly address: string;
+  readonly family: 4 | 6;
+}
+
+/**
+ * A resolver: it gives the addresses of a host name. The default uses the resolver of the
+ * operating system (`dns.lookup`), so it reads the hosts file too. A test gives its own resolver.
+ */
+export type HostResolver = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+
+/** The options of the host policy: the options of `createHttpModule()`. */
+export interface HostPolicyOptions {
+  /**
+   * More hosts that the procedures can reach: host names, wildcards (`*.example.com`), IP
+   * addresses and CIDR ranges, each with an optional port. An entry that names a private or a
+   * loopback address allows it.
+   */
+  readonly allow?: readonly string[] | undefined;
+  /** False: only the hosts of `allow`. The default is true: each public host too. */
+  readonly publicHosts?: boolean | undefined;
+  /** The resolver of host names. The default is `dns.lookup` with all the addresses. */
+  readonly resolve?: HostResolver | undefined;
+}
+
+/** One entry of `allow`. */
+type AllowEntry =
+  | { readonly kind: "name"; readonly name: string; readonly port: number | undefined; readonly text: string }
+  | { readonly kind: "wildcard"; readonly suffix: string; readonly port: number | undefined; readonly text: string }
+  | { readonly kind: "range"; readonly range: AddressRange; readonly port: number | undefined; readonly text: string };
+
+/** A host policy: the parsed options. */
+export interface HostPolicy {
+  readonly entries: readonly AllowEntry[];
+  readonly publicHosts: boolean;
+  readonly resolve: HostResolver;
+}
+
+/** The resolver of the operating system: each address of the name, in the order of the system. */
+export const systemResolver: HostResolver = async (hostname) => {
+  const found = await lookup(hostname, { all: true, verbatim: true });
+  return found.map((entry) => ({ address: entry.address, family: entry.family === 6 ? 6 : 4 }));
+};
+
+/** A host name in the form of a comparison: lowercase, without a final dot. */
+function normalName(name: string): string {
+  return name.toLowerCase().replace(/\.$/, "");
+}
+
+const NAME = /^[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?(\.[a-z0-9_]([a-z0-9_-]*[a-z0-9_])?)*$/;
+
+/** This function parses one entry of `allow`. A bad entry throws, so a host finds it at the start. */
+function parseEntry(text: string): AllowEntry {
+  let head = text.trim();
+  let port: number | undefined;
+  // A port: "host:80", "[::1]:80", "10.0.0.0/8:80". A bare IPv6 address has no port.
+  const withPort = /^(.*[^:]):([0-9]{1,5})$/.exec(head);
+  if (withPort && (!withPort[1]!.includes(":") || withPort[1]!.endsWith("]"))) {
+    head = withPort[1]!;
+    port = Number(withPort[2]);
+    if (port < 1 || port > 65535) throw new Error(`The port of the allow entry "${text}" is not in 1 to 65535`);
+  }
+  const range = parseRange(head);
+  if (range) return { kind: "range", range, port, text };
+  const name = normalName(head);
+  if (name.startsWith("*.") && NAME.test(name.slice(2))) return { kind: "wildcard", suffix: name.slice(1), port, text };
+  if (NAME.test(name)) return { kind: "name", name, port, text };
+  throw new Error(`The allow entry "${text}" is not a host name, a wildcard, an IP address or a CIDR range`);
+}
+
+/** This function makes a host policy from the options. A bad entry of `allow` throws. */
+export function createHostPolicy(options: HostPolicyOptions = {}): HostPolicy {
+  return {
+    entries: (options.allow ?? []).map(parseEntry),
+    publicHosts: options.publicHosts ?? true,
+    resolve: options.resolve ?? systemResolver,
+  };
+}
+
+/** The default policy: each public host, and no other host. */
+export const DEFAULT_HOST_POLICY: HostPolicy = createHostPolicy();
+
+/** The host of a URL to connect to, after the check. */
+export interface AllowedTarget {
+  /** The host name of the URL, or the IP address without brackets. */
+  readonly hostname: string;
+  readonly port: number;
+  /** The addresses that the connection can use: each one passed the check. */
+  readonly addresses: readonly ResolvedAddress[];
+}
+
+/** The `FORBIDDEN` error for a host that the policy does not allow. */
+export function hostNotAllowed(procedure: ProcedurePath, message: string): InvocationError {
+  return new InvocationError("FORBIDDEN", `${procedure.join(".")}: ${message}`, procedure, HOST_NOT_ALLOWED);
+}
+
+/** True for the `FORBIDDEN` error of a host that the policy does not allow. */
+export function isHostNotAllowed(error: unknown): boolean {
+  return error instanceof InvocationError && error.code === "FORBIDDEN" && error.reason === HOST_NOT_ALLOWED;
+}
+
+function portMatches(entry: AllowEntry, port: number): boolean {
+  return entry.port === undefined || entry.port === port;
+}
+
+function nameAllowed(policy: HostPolicy, hostname: string, port: number): boolean {
+  const name = normalName(hostname);
+  return policy.entries.some(
+    (entry) =>
+      portMatches(entry, port) &&
+      ((entry.kind === "name" && entry.name === name) || (entry.kind === "wildcard" && name.endsWith(entry.suffix) && name.length > entry.suffix.length)),
+  );
+}
+
+/** Undefined when the policy allows the address, or the reason of the refusal. */
+function addressRefusal(policy: HostPolicy, address: AddressBytes, port: number): string | undefined {
+  if (policy.entries.some((entry) => entry.kind === "range" && portMatches(entry, port) && rangeHas(entry.range, address))) return undefined;
+  const special = specialClass(address);
+  if (special !== undefined) return `${formatAddress(address)} is a ${special} address`;
+  return policy.publicHosts ? undefined : `${formatAddress(address)} is not in the allowed hosts`;
+}
+
+/** The default port of a URL protocol. */
+export function portOf(url: URL): number {
+  if (url.port !== "") return Number(url.port);
+  return url.protocol === "https:" ? 443 : 80;
+}
+
+/**
+ * This function examines the host of a URL. It gives the addresses that the connection can use,
+ * or it throws `FORBIDDEN` with the reason `host-not-allowed`. A name that `allow` names keeps
+ * each address. For another name, each address must be public or in a range of `allow`. The
+ * connection uses only the addresses that pass, and the check fails when none passes.
+ */
+export async function checkHost(policy: HostPolicy, url: URL, procedure: ProcedurePath, what = "the URL"): Promise<AllowedTarget> {
+  const hostname = url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
+  const port = portOf(url);
+  const literal = parseAddress(hostname);
+  if (literal) {
+    const refusal = addressRefusal(policy, literal, port);
+    if (refusal !== undefined) throw hostNotAllowed(procedure, `the host of ${what} is not allowed: ${refusal}`);
+    return { hostname, port, addresses: [{ address: formatAddress(literal), family: literal.length === 4 ? 4 : 6 }] };
+  }
+  if (!policy.publicHosts && !nameAllowed(policy, hostname, port) && !policy.entries.some((entry) => entry.kind === "range")) {
+    throw hostNotAllowed(procedure, `the host ${hostname}:${port} of ${what} is not in the allowed hosts`);
+  }
+  let resolved: readonly ResolvedAddress[];
+  try {
+    resolved = await policy.resolve(hostname);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | undefined)?.code;
+    throw new Error(`${procedure.join(".")}: the host ${hostname} of ${what} has no address${code ? ` (${code})` : ""}`, { cause: error });
+  }
+  if (resolved.length === 0) throw new Error(`${procedure.join(".")}: the host ${hostname} of ${what} has no address`);
+  if (nameAllowed(policy, hostname, port)) return { hostname, port, addresses: resolved };
+  const allowed: ResolvedAddress[] = [];
+  const refusals: string[] = [];
+  for (const entry of resolved) {
+    const bytes = parseAddress(entry.address);
+    const refusal = bytes ? addressRefusal(policy, bytes, port) : `${entry.address} is not an IP address`;
+    if (refusal === undefined) allowed.push(entry);
+    else refusals.push(refusal);
+  }
+  if (allowed.length === 0) {
+    throw hostNotAllowed(procedure, `the host ${hostname} of ${what} is not allowed: ${refusals.join(", ")}`);
+  }
+  return { hostname, port, addresses: allowed };
+}

package/src/procedures/http/index.ts

@@ -0,0 +1,4 @@
+export { httpRequest } from "./request.js";
+export { httpJson } from "./json.js";
+export { httpNdjson } from "./ndjson.js";
+export { httpSse } from "./sse.js";

package/src/procedures/http/json.ts

@@ -0,0 +1,52 @@
+/**
+ * http.json procedure
+ *
+ * Send a GET or a POST of JSON and give the parsed JSON response. By default, a status outside
+ * 200 to 299 is an error (`HTTP_STATUS`) with the start of the body in its message.
+ */
+
+import { HttpError } from "../../errors.js";
+import { DEFAULT_SETTINGS, DEFAULT_TIMEOUT_MS, excerpt, exchange, isOk, prepare, readBody, responseHeaders, type HttpSettings } from "../../exchange.js";
+import { CallScope, type ScopeContext } from "../../scope.js";
+import type { HttpJsonInput, HttpJsonOutput } from "../../types.js";
+
+const PATH = ["http", "json"];
+
+/**
+ * Send a GET or a POST of JSON and give the parsed JSON response
+ */
+export async function httpJson(input: HttpJsonInput, ctx: ScopeContext = {}, settings: HttpSettings = DEFAULT_SETTINGS): Promise<HttpJsonOutput> {
+  const method = input.method ?? (input.json !== undefined ? "POST" : "GET");
+  if (method === "GET" && input.json !== undefined) throw new Error("http.json: a GET request has no body: use the method POST");
+  const body = input.json !== undefined ? Buffer.from(JSON.stringify(input.json), "utf8") : undefined;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (body !== undefined) headers["content-type"] = "application/json";
+  const prepared = prepare({ ...input, method }, PATH, settings, { headers, body });
+  const scope = new CallScope(PATH, ctx, { timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS });
+  try {
+    const opened = await exchange(prepared, settings.policy, scope);
+    const status = opened.response.statusCode ?? 0;
+    const limit = Math.min(input.maxResponseBytes ?? settings.maxResponseBytes, settings.maxResponseBytes);
+    const bytes = await readBody(opened.body, limit, scope, opened.response);
+    const text = bytes.toString("utf8");
+    if (!isOk(status) && (input.failOnStatus ?? true)) {
+      const reason = opened.response.statusMessage ? ` ${opened.response.statusMessage}` : "";
+      throw new HttpError("HTTP_STATUS", `http.json: the server answered ${status}${reason}${text ? `: ${excerpt(text)}` : ""}`, status);
+    }
+    let data: unknown = null;
+    if (text.trim() !== "") {
+      try {
+        data = JSON.parse(text) as unknown;
+      } catch {
+        // An error page is often HTML: with failOnStatus: false, the output keeps its text
+        if (!isOk(status)) data = text;
+        else throw new HttpError("BAD_JSON", `http.json: the body of the response is not JSON: ${excerpt(text)}`, status);
+      }
+    }
+    return { status, ok: isOk(status), url: opened.url, headers: responseHeaders(opened.response.headers), data };
+  } catch (error) {
+    throw scope.translate(error);
+  } finally {
+    scope.dispose();
+  }
+}

package/src/procedures/http/ndjson.ts

@@ -0,0 +1,64 @@
+/**
+ * http.ndjson procedure
+ *
+ * Read an NDJSON response as a stream of parsed lines. The procedure sends a GET. Each line that
+ * is not blank is one item: its JSON value. The stream can run without an end, so the procedure
+ * declares an unbounded stream (roadmap R15). When the reader stops, the connection closes.
+ *
+ * The call waits for the status of the response. A refused host, a failed connection and a status
+ * outside 200 to 299 fail the call itself, before the first item.
+ */
+
+import { HttpError } from "../../errors.js";
+import { DEFAULT_ITEM_BYTES, DEFAULT_SETTINGS, excerpt, exchange, isOk, prepare, statusError, touching, type Exchange, type HttpSettings } from "../../exchange.js";
+import { ndjsonLines } from "../../parsers.js";
+import { CallScope, type ScopeContext } from "../../scope.js";
+import type { HttpNdjsonInput, HttpNdjsonOutput } from "../../types.js";
+
+const PATH = ["http", "ndjson"];
+
+/** The items of an open response. The end of the generator closes the connection. */
+async function* items(opened: Exchange, scope: CallScope, maxLineBytes: number): AsyncGenerator<HttpNdjsonOutput, void, undefined> {
+  try {
+    scope.touch();
+    for await (const line of ndjsonLines(touching(opened.body, scope), maxLineBytes, "http.ndjson")) {
+      let value: unknown;
+      try {
+        value = JSON.parse(line.text) as unknown;
+      } catch {
+        throw new HttpError("BAD_JSON", `http.ndjson: line ${line.line} is not JSON: ${excerpt(line.text, 80)}`, opened.response.statusCode);
+      }
+      // The idle time does not run while the reader holds the item
+      scope.pause();
+      yield value;
+      scope.touch();
+    }
+  } catch (error) {
+    throw scope.translate(error);
+  } finally {
+    opened.body.destroy();
+    opened.close();
+    scope.dispose();
+  }
+}
+
+/**
+ * Read an NDJSON response as a stream of parsed lines
+ */
+export async function httpNdjson(input: HttpNdjsonInput, ctx: ScopeContext = {}, settings: HttpSettings = DEFAULT_SETTINGS): Promise<AsyncGenerator<HttpNdjsonOutput, void, undefined>> {
+  const headers = { accept: "application/x-ndjson, application/jsonl;q=0.9, application/json;q=0.8" };
+  const prepared = prepare({ ...input, method: "GET" }, PATH, settings, { headers });
+  const scope = new CallScope(PATH, ctx, { timeoutMs: input.timeoutMs, idleTimeoutMs: input.idleTimeoutMs });
+  let opened: Exchange | undefined;
+  try {
+    opened = await exchange(prepared, settings.policy, scope);
+    if (!isOk(opened.response.statusCode ?? 0)) throw await statusError(opened, scope);
+  } catch (error) {
+    opened?.close();
+    scope.dispose();
+    throw scope.translate(error);
+  }
+  // The idle time starts again when the reader asks for the first item
+  scope.pause();
+  return items(opened, scope, input.maxLineBytes ?? DEFAULT_ITEM_BYTES);
+}

package/src/procedures/http/request.ts

@@ -0,0 +1,72 @@
+/**
+ * http.request procedure
+ *
+ * Send an HTTP request and give the status, the headers and the body. The procedure gives each
+ * status: a status of 400 or more is not an error. The body of the response has a size limit.
+ */
+
+import { HttpError } from "../../errors.js";
+import { DEFAULT_SETTINGS, DEFAULT_TIMEOUT_MS, exchange, isOk, prepare, readBody, responseHeaders, type HttpSettings } from "../../exchange.js";
+import { CallScope, type ScopeContext } from "../../scope.js";
+import type { HttpRequestInput, HttpRequestOutput } from "../../types.js";
+
+const PATH = ["http", "request"];
+
+/** The body of an input and its content type, or undefined. */
+function bodyOf(input: HttpRequestInput): { body: Buffer; type: string } | undefined {
+  const given = [input.body, input.json, input.bodyBase64].filter((value) => value !== undefined).length;
+  if (given > 1) throw new Error("http.request: give only one of body, json and bodyBase64");
+  if (input.body !== undefined) return { body: Buffer.from(input.body, "utf8"), type: "text/plain; charset=utf-8" };
+  if (input.json !== undefined) return { body: Buffer.from(JSON.stringify(input.json), "utf8"), type: "application/json" };
+  if (input.bodyBase64 !== undefined) return { body: Buffer.from(input.bodyBase64, "base64"), type: "application/octet-stream" };
+  return undefined;
+}
+
+/** The body of the response in the form of `responseType`. */
+function decode(bytes: Buffer, responseType: HttpRequestInput["responseType"], status: number): unknown {
+  if (responseType === "bytes") return bytes.toString("base64");
+  const text = bytes.toString("utf8");
+  if (responseType !== "json") return text;
+  if (text.trim() === "") return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new HttpError("BAD_JSON", `http.request: the body of the response is not JSON: ${text.slice(0, 200)}`, status);
+  }
+}
+
+/**
+ * Send an HTTP request and give the status, the headers and the body
+ */
+export async function httpRequest(input: HttpRequestInput, ctx: ScopeContext = {}, settings: HttpSettings = DEFAULT_SETTINGS): Promise<HttpRequestOutput> {
+  const method = input.method ?? "GET";
+  const body = bodyOf(input);
+  if (body !== undefined && (method === "GET" || method === "HEAD")) {
+    throw new Error(`http.request: a ${method} request has no body`);
+  }
+  const headers: Record<string, string> = {};
+  if (body !== undefined) headers["content-type"] = body.type;
+  if (input.responseType === "json") headers["accept"] = "application/json";
+  const prepared = prepare({ ...input, method }, PATH, settings, { headers, body: body?.body });
+  const scope = new CallScope(PATH, ctx, { timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS });
+  try {
+    const opened = await exchange(prepared, settings.policy, scope);
+    const limit = Math.min(input.maxResponseBytes ?? settings.maxResponseBytes, settings.maxResponseBytes);
+    const bytes = await readBody(opened.body, limit, scope, opened.response);
+    const status = opened.response.statusCode ?? 0;
+    return {
+      status,
+      statusText: opened.response.statusMessage ?? "",
+      ok: isOk(status),
+      url: opened.url,
+      redirected: opened.redirects.length > 0,
+      headers: responseHeaders(opened.response.headers),
+      body: decode(bytes, input.responseType, status),
+      bytes: bytes.length,
+    };
+  } catch (error) {
+    throw scope.translate(error);
+  } finally {
+    scope.dispose();
+  }
+}

package/src/procedures/http/sse.ts

@@ -0,0 +1,65 @@
+/**
+ * http.sse procedure
+ *
+ * Read a stream of server-sent events. The procedure sends a GET with
+ * `accept: text/event-stream`, and each event is one item: its type, its data and the last event
+ * ID. The procedure does not connect again after the end of the stream. To continue, a caller
+ * sends the last ID in `lastEventId`. The stream can run without an end (roadmap R15).
+ *
+ * The call waits for the status of the response. A refused host, a failed connection, a status
+ * outside 200 to 299 and another content type fail the call itself, before the first item.
+ */
+
+import { HttpError } from "../../errors.js";
+import { DEFAULT_ITEM_BYTES, DEFAULT_SETTINGS, exchange, headerText, isOk, prepare, statusError, touching, type Exchange, type HttpSettings } from "../../exchange.js";
+import { sseEvents } from "../../parsers.js";
+import { CallScope, type ScopeContext } from "../../scope.js";
+import type { HttpSseInput, HttpSseOutput } from "../../types.js";
+
+const PATH = ["http", "sse"];
+
+/** The events of an open response. The end of the generator closes the connection. */
+async function* events(opened: Exchange, scope: CallScope, maxEventBytes: number): AsyncGenerator<HttpSseOutput, void, undefined> {
+  try {
+    scope.touch();
+    for await (const event of sseEvents(touching(opened.body, scope), maxEventBytes, "http.sse")) {
+      // The idle time does not run while the reader holds the item
+      scope.pause();
+      yield event;
+      scope.touch();
+    }
+  } catch (error) {
+    throw scope.translate(error);
+  } finally {
+    opened.body.destroy();
+    opened.close();
+    scope.dispose();
+  }
+}
+
+/**
+ * Read a stream of server-sent events
+ */
+export async function httpSse(input: HttpSseInput, ctx: ScopeContext = {}, settings: HttpSettings = DEFAULT_SETTINGS): Promise<AsyncGenerator<HttpSseOutput, void, undefined>> {
+  const headers: Record<string, string> = { accept: "text/event-stream", "cache-control": "no-cache" };
+  if (input.lastEventId !== undefined) headers["last-event-id"] = input.lastEventId;
+  const prepared = prepare({ ...input, method: "GET" }, PATH, settings, { headers });
+  const scope = new CallScope(PATH, ctx, { timeoutMs: input.timeoutMs, idleTimeoutMs: input.idleTimeoutMs });
+  let opened: Exchange | undefined;
+  try {
+    opened = await exchange(prepared, settings.policy, scope);
+    const status = opened.response.statusCode ?? 0;
+    if (!isOk(status)) throw await statusError(opened, scope);
+    const type = headerText(opened.response.headers["content-type"]) ?? "";
+    if (!type.toLowerCase().startsWith("text/event-stream")) {
+      throw new HttpError("BAD_CONTENT_TYPE", `http.sse: the content type of the response is ${JSON.stringify(type)}, not text/event-stream`, status);
+    }
+  } catch (error) {
+    opened?.close();
+    scope.dispose();
+    throw scope.translate(error);
+  }
+  // The idle time starts again when the reader asks for the first event
+  scope.pause();
+  return events(opened, scope, input.maxEventBytes ?? DEFAULT_ITEM_BYTES);
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/http in the global registry:
+ * `import "@procedures/http/register"`. The package root registers nothing.
+ */
+
+import { registerHttpProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerHttpProcedures();