@tapcue/extension-sdk 0.1.0

package/src/testing/http-fake.ts

@@ -0,0 +1,240 @@
+/**
+ * The fake HTTP broker used by the deterministic test host.
+ *
+ * It enforces the same rules the Rust broker does — HTTPS only, exact-host
+ * allowlist, host re-check after every redirect, response-size and concurrency
+ * budgets, cooperative abort — so a test that passes here is testing the real
+ * policy, not a friendlier one.
+ */
+
+import type { HttpMethod, HttpRequestInit, HttpResponse } from "../capabilities.js";
+import { ExtensionError, cancelledError } from "../errors.js";
+import type { JsonValue } from "../json.js";
+
+export interface RecordedRequest {
+  url: string;
+  method: HttpMethod;
+  headers: Record<string, string>;
+  body?: string;
+  /** Redirect hop index; 0 is the request the extension made. */
+  hop: number;
+}
+
+export interface FakeHttpResponse {
+  status?: number;
+  headers?: Record<string, string>;
+  json?: JsonValue;
+  text?: string;
+  bytes?: Uint8Array;
+  /** Shorthand for a 302 to another URL. The host re-checks the new host. */
+  redirectTo?: string;
+}
+
+export interface HttpRoute {
+  /** String matches by prefix (so query strings stay flexible); RegExp by test. */
+  url: string | RegExp;
+  method?: HttpMethod;
+  response:
+    | FakeHttpResponse
+    | ((request: RecordedRequest) => FakeHttpResponse | Promise<FakeHttpResponse>);
+}
+
+export interface HttpBrokerLimits {
+  maxRedirects: number;
+  maxConcurrentRequests: number;
+  maxResponseBytes: number;
+}
+
+export interface HttpBrokerOptions {
+  allowedHosts: readonly string[];
+  routes: readonly HttpRoute[];
+  limits: HttpBrokerLimits;
+  record(request: RecordedRequest): void;
+}
+
+const encoder = new TextEncoder();
+
+export class FakeHttpBroker {
+  private inFlight = 0;
+
+  constructor(private readonly options: HttpBrokerOptions) {}
+
+  async fetch(
+    rawUrl: string,
+    init: HttpRequestInit | undefined,
+    invocationSignal: AbortSignal,
+    pinnedHeaders: Record<string, string>,
+  ): Promise<HttpResponse> {
+    const { limits } = this.options;
+    if (this.inFlight >= limits.maxConcurrentRequests) {
+      throw new ExtensionError({
+        code: "quota-exceeded",
+        message: `at most ${limits.maxConcurrentRequests} concurrent requests`,
+        retryable: true,
+      });
+    }
+    this.inFlight += 1;
+    try {
+      return await this.follow(rawUrl, init, invocationSignal, pinnedHeaders);
+    } finally {
+      this.inFlight -= 1;
+    }
+  }
+
+  private async follow(
+    rawUrl: string,
+    init: HttpRequestInit | undefined,
+    invocationSignal: AbortSignal,
+    pinnedHeaders: Record<string, string>,
+  ): Promise<HttpResponse> {
+    const { limits } = this.options;
+    let url = rawUrl;
+
+    for (let hop = 0; hop <= limits.maxRedirects; hop += 1) {
+      this.checkDestination(url);
+      throwIfAborted(init?.signal, invocationSignal);
+
+      const request: RecordedRequest = {
+        url,
+        method: init?.method ?? "GET",
+        headers: { ...pinnedHeaders, ...(init?.headers ?? {}) },
+        body: typeof init?.body === "string" ? init.body : undefined,
+        hop,
+      };
+      this.options.record(request);
+
+      const route = this.options.routes.find(
+        (candidate) =>
+          matches(candidate.url, url) && (candidate.method ?? "GET") === request.method,
+      );
+      if (!route) {
+        throw new ExtensionError({
+          code: "unavailable",
+          message: `no fake route for ${redact(url)}`,
+          retryable: false,
+        });
+      }
+
+      const fake = await race(
+        Promise.resolve(
+          typeof route.response === "function" ? route.response(request) : route.response,
+        ),
+        init?.signal,
+        invocationSignal,
+      );
+
+      if (fake.redirectTo) {
+        url = fake.redirectTo;
+        continue;
+      }
+
+      const body = encodeBody(fake);
+      const cap = Math.min(init?.maxResponseBytes ?? limits.maxResponseBytes, limits.maxResponseBytes);
+      if (body.byteLength > cap) {
+        throw new ExtensionError({
+          code: "quota-exceeded",
+          message: `response exceeds ${cap} bytes`,
+          retryable: false,
+        });
+      }
+      return makeResponse(url, fake.status ?? 200, fake.headers ?? {}, body);
+    }
+
+    throw new ExtensionError({
+      code: "network",
+      message: `too many redirects (limit ${limits.maxRedirects})`,
+      retryable: false,
+    });
+  }
+
+  /** HTTPS only, exact host, re-checked on every hop — including after a redirect. */
+  private checkDestination(rawUrl: string): void {
+    let parsed: URL;
+    try {
+      parsed = new URL(rawUrl);
+    } catch {
+      throw new ExtensionError({ code: "invalid-request", message: "malformed URL" });
+    }
+    if (parsed.protocol !== "https:") {
+      throw new ExtensionError({
+        code: "invalid-request",
+        message: `only https is allowed, got ${parsed.protocol.replace(":", "")}`,
+      });
+    }
+    if (!this.options.allowedHosts.includes(parsed.hostname)) {
+      throw new ExtensionError({
+        code: "permission-denied",
+        message: `host ${parsed.hostname} is not in the granted host list`,
+      });
+    }
+  }
+}
+
+function matches(pattern: string | RegExp, url: string): boolean {
+  return typeof pattern === "string" ? url.startsWith(pattern) : pattern.test(url);
+}
+
+function encodeBody(fake: FakeHttpResponse): Uint8Array {
+  if (fake.bytes) return fake.bytes;
+  if (fake.text !== undefined) return encoder.encode(fake.text);
+  if (fake.json !== undefined) return encoder.encode(JSON.stringify(fake.json));
+  return new Uint8Array();
+}
+
+function makeResponse(
+  url: string,
+  status: number,
+  headers: Record<string, string>,
+  body: Uint8Array,
+): HttpResponse {
+  const lowered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) lowered[key.toLowerCase()] = value;
+  const decoder = new TextDecoder();
+  return {
+    url,
+    status,
+    ok: status >= 200 && status < 300,
+    headers: Object.freeze(lowered),
+    async text() {
+      return decoder.decode(body);
+    },
+    async json<T>() {
+      return JSON.parse(decoder.decode(body)) as T;
+    },
+    async bytes() {
+      return body;
+    },
+  };
+}
+
+function throwIfAborted(...signals: (AbortSignal | undefined)[]): void {
+  for (const signal of signals) {
+    if (signal?.aborted) throw cancelledError();
+  }
+}
+
+/** Rejects as soon as any signal aborts, so a pending request cannot outlive it. */
+function race<T>(work: Promise<T>, ...signals: (AbortSignal | undefined)[]): Promise<T> {
+  const live = signals.filter((s): s is AbortSignal => s !== undefined);
+  if (live.length === 0) return work;
+  return Promise.race([
+    work,
+    ...live.map(
+      (signal) =>
+        new Promise<never>((_resolve, reject) => {
+          if (signal.aborted) reject(cancelledError());
+          signal.addEventListener("abort", () => reject(cancelledError()), { once: true });
+        }),
+    ),
+  ]);
+}
+
+/** Diagnostics never carry the query string: it can hold a secret or a location. */
+export function redact(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return "<malformed url>";
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+export * from "./test-host.js";
+export * from "./http-fake.js";