@procedures/http 0.0.0-stage → 0.3.0

package/src/scope.ts

@@ -0,0 +1,129 @@
+/**
+ * The time limits and the stop of one call (roadmap R38).
+ *
+ * A call stops at the first of these events:
+ * - the signal of the call aborts (`ctx.signal`): the caller went away, or the server stops;
+ * - the deadline of the call passes (`ctx.capability.deadline`);
+ * - the time of the input passes (`timeoutMs`);
+ * - a stream gets no data for the idle time of the input (`idleTimeoutMs`).
+ *
+ * The earliest event wins. The stop aborts the request, and the call fails with `TIMEOUT` or
+ * `ABORTED`.
+ */
+
+import { InvocationError, type ProcedurePath } from "@procedures/client";
+
+/** The cause of a stop. */
+export type StopReason = "timeout" | "idle" | "deadline" | "aborted";
+
+/** The longest delay of `setTimeout`. A later time gets no timer: the call cannot last so long. */
+const MAX_TIMER_MS = 2_147_483_647;
+
+/** The parts of the context of a handler that a scope reads. */
+export interface ScopeContext {
+  readonly signal?: AbortSignal | undefined;
+  readonly capability?: { readonly deadline?: number | undefined } | undefined;
+}
+
+/** The time limits of a scope, in milliseconds. */
+export interface ScopeLimits {
+  /** The time of the whole call. */
+  readonly timeoutMs?: number | undefined;
+  /** The longest time without data. */
+  readonly idleTimeoutMs?: number | undefined;
+}
+
+/** The stop of one call: one abort signal for the request, and the error of the stop. */
+export class CallScope {
+  readonly #controller = new AbortController();
+  readonly #timers: ReturnType<typeof setTimeout>[] = [];
+  readonly #parent: AbortSignal | undefined;
+  readonly #onAbort = (): void => this.stop("aborted");
+  #idle: ReturnType<typeof setTimeout> | undefined;
+  #reason: StopReason | undefined;
+
+  constructor(
+    readonly path: ProcedurePath,
+    context: ScopeContext,
+    readonly limits: ScopeLimits = {},
+  ) {
+    this.#parent = context.signal;
+    if (this.#parent?.aborted) {
+      this.stop("aborted");
+      return;
+    }
+    this.#parent?.addEventListener("abort", this.#onAbort, { once: true });
+    if (limits.timeoutMs !== undefined) this.#later(limits.timeoutMs, () => this.stop("timeout"));
+    const deadline = context.capability?.deadline;
+    if (deadline !== undefined) this.#later(Math.max(0, deadline - Date.now()), () => this.stop("deadline"));
+    this.touch();
+  }
+
+  #later(ms: number, stop: () => void): void {
+    if (ms <= MAX_TIMER_MS) this.#timers.push(setTimeout(stop, ms));
+  }
+
+  /** The signal that aborts the request at the stop. */
+  get signal(): AbortSignal {
+    return this.#controller.signal;
+  }
+
+  /** The cause of the stop, or undefined while the call runs. */
+  get reason(): StopReason | undefined {
+    return this.#reason;
+  }
+
+  /** This function stops the call. The first cause wins. */
+  stop(reason: StopReason): void {
+    if (this.#reason !== undefined) return;
+    this.#reason = reason;
+    this.#clearIdle();
+    this.#controller.abort(this.error());
+  }
+
+  /** This function starts the idle time again: data arrived. */
+  touch(): void {
+    const idle = this.limits.idleTimeoutMs;
+    if (idle === undefined || this.#reason !== undefined) return;
+    this.#clearIdle();
+    if (idle <= MAX_TIMER_MS) this.#idle = setTimeout(() => this.stop("idle"), idle);
+  }
+
+  /** This function holds the idle time while the reader of a stream has an item and reads no data. */
+  pause(): void {
+    this.#clearIdle();
+  }
+
+  #clearIdle(): void {
+    if (this.#idle !== undefined) clearTimeout(this.#idle);
+    this.#idle = undefined;
+  }
+
+  /** The error of the stop. Before a stop, an `ABORTED` error. */
+  error(): InvocationError {
+    const key = this.path.join(".");
+    switch (this.#reason) {
+      case "timeout":
+        return new InvocationError("TIMEOUT", `${key}: the call took more than ${this.limits.timeoutMs} ms (timeoutMs)`, this.path);
+      case "idle":
+        return new InvocationError("TIMEOUT", `${key}: no data arrived in ${this.limits.idleTimeoutMs} ms (idleTimeoutMs)`, this.path);
+      case "deadline":
+        return new InvocationError("TIMEOUT", `${key}: the deadline of the call passed`, this.path);
+      default:
+        return new InvocationError("ABORTED", `${key}: the caller aborted the call`, this.path);
+    }
+  }
+
+  /** The error to throw for a failure: the error of the stop after a stop, or the failure. */
+  translate(error: unknown): unknown {
+    return this.#reason !== undefined ? this.error() : error;
+  }
+
+  /** This function removes the timers and the listener. */
+  dispose(): void {
+    for (const timer of this.#timers) clearTimeout(timer);
+    this.#timers.length = 0;
+    this.#clearIdle();
+    this.#parent?.removeEventListener("abort", this.#onAbort);
+  }
+}

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+/** A JSON value. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
+
+/** The methods of `http.request`. */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
+
+/** The fields of a request that each procedure has. */
+export interface HttpTarget {
+  /** The URL: `http:` or `https:`. */
+  url: string;
+  /** The headers of the request. */
+  headers?: Record<string, string> | undefined;
+  /** More parameters for the query of the URL. A list gives the parameter more than one time. */
+  query?: Record<string, string | number | boolean | Array<string | number | boolean>> | undefined;
+}
+
+// =============================================================================
+// http.request Types - Send an HTTP request and give the status, the headers and the body
+// =============================================================================
+
+export interface HttpRequestInput extends HttpTarget {
+  method?: HttpMethod | undefined;
+  /** A body of text. */
+  body?: string | undefined;
+  /** A body of JSON: the procedure sets `content-type: application/json`. */
+  json?: unknown;
+  /** A body of bytes in base64. */
+  bodyBase64?: string | undefined;
+  /** The form of the body of the response: text (the default), parsed JSON, or bytes in base64. */
+  responseType?: "text" | "json" | "bytes" | undefined;
+  /** The time of the whole call, in milliseconds. The default is 30000. */
+  timeoutMs?: number | undefined;
+  /** The largest body of the response, in bytes. The limit of the module is the maximum. */
+  maxResponseBytes?: number | undefined;
+  /** What to do with a redirect: follow it (the default), give it (`manual`), or fail (`error`). */
+  redirect?: "follow" | "manual" | "error" | undefined;
+  /** The most redirects that the call follows. The default is 5. */
+  maxRedirects?: number | undefined;
+}
+
+export interface HttpRequestOutput {
+  status: number;
+  statusText: string;
+  /** True for a status in 200 to 299. */
+  ok: boolean;
+  /** The URL of the response: the last URL after the redirects. */
+  url: string;
+  /** True when the call followed one or more redirects. */
+  redirected: boolean;
+  /** The headers of the response, with names in lowercase. `set-cookie` is a list. */
+  headers: Record<string, string | string[]>;
+  /** The body: text, parsed JSON (null for an empty body), or bytes in base64. */
+  body: unknown;
+  /** The size of the body in bytes, after the content encoding. */
+  bytes: number;
+}
+
+// =============================================================================
+// http.json Types - Send a GET or a POST of JSON and give the parsed JSON response
+// =============================================================================
+
+export interface HttpJsonInput extends HttpTarget {
+  /** GET, or POST. The default is POST with `json`, and GET without it. */
+  method?: "GET" | "POST" | undefined;
+  /** The JSON body of a POST. */
+  json?: unknown;
+  /** The time of the whole call, in milliseconds. The default is 30000. */
+  timeoutMs?: number | undefined;
+  /** The largest body of the response, in bytes. The limit of the module is the maximum. */
+  maxResponseBytes?: number | undefined;
+  /** True (the default): a status outside 200 to 299 is an error. False: the output has it. */
+  failOnStatus?: boolean | undefined;
+}
+
+export interface HttpJsonOutput {
+  status: number;
+  ok: boolean;
+  url: string;
+  headers: Record<string, string | string[]>;
+  /** The parsed body. An empty body gives null. An error status with a body that is not JSON gives its text. */
+  data: unknown;
+}
+
+// =============================================================================
+// http.ndjson Types - Read an NDJSON response as a stream of parsed lines
+// =============================================================================
+
+export interface HttpStreamInput extends HttpTarget {
+  /** The time of the whole stream, in milliseconds. The default is no limit. */
+  timeoutMs?: number | undefined;
+  /** The longest time without data, in milliseconds. The default is no limit. */
+  idleTimeoutMs?: number | undefined;
+}
+
+export interface HttpNdjsonInput extends HttpStreamInput {
+  /** The largest line, in bytes. The default is 1 MiB. */
+  maxLineBytes?: number | undefined;
+}
+
+/** One item of `http.ndjson`: the JSON value of one line. */
+export type HttpNdjsonOutput = unknown;
+
+// =============================================================================
+// http.sse Types - Read a stream of server-sent events
+// =============================================================================
+
+export interface HttpSseInput extends HttpStreamInput {
+  /** The `Last-Event-ID` header: the server continues after this event. */
+  lastEventId?: string | undefined;
+  /** The largest event, in bytes. The default is 1 MiB. */
+  maxEventBytes?: number | undefined;
+}
+
+/** One item of `http.sse`: one event. */
+export interface HttpSseOutput {
+  event: string;
+  data: string;
+  id?: string | undefined;
+  retry?: number | undefined;
+}