blume 1.5.2 → 1.6.0

package/src/openapi/graphql-build.ts

@@ -0,0 +1,293 @@
+import type {
+  GraphQLArgument,
+  GraphQLEnumType,
+  GraphQLField,
+  GraphQLInputField,
+  GraphQLInputObjectType,
+  GraphQLInterfaceType,
+  GraphQLNamedType,
+  GraphQLObjectType,
+  GraphQLScalarType,
+  GraphQLSchema,
+  GraphQLUnionType,
+} from "graphql";
+import {
+  buildClientSchema,
+  buildSchema,
+  getNamedType,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+  isSpecifiedScalarType,
+  isUnionType,
+  print,
+} from "graphql";
+
+import type {
+  GraphqlDocument,
+  GraphqlEnumValue,
+  GraphqlField as ModelField,
+  GraphqlInputValue,
+  GraphqlTypeDef,
+  GraphqlTypeRef,
+} from "./graphql.ts";
+
+/**
+ * Lower schema text — SDL or an introspection result — into the serializable
+ * {@link GraphqlDocument} the reference renders from. This is the only module
+ * that imports `graphql`-js, and it runs Node-side at parse time only (see
+ * `parseGraphqlSpec` in `parse.ts`), so the parser never reaches the generated
+ * runtime or the browser. Throws plain Errors for unreadable schemas; the
+ * caller wraps them as content problems.
+ */
+
+/** A type expression flattened to its display form and core named type. */
+const typeRef = (
+  type: GraphQLField<unknown, unknown>["type"] | GraphQLInputField["type"]
+): GraphqlTypeRef => ({
+  display: String(type),
+  name: getNamedType(type).name,
+});
+
+/**
+ * An argument's or input field's default, printed as a GraphQL literal. Both
+ * SDL- and introspection-built schemas carry the default as a const AST node
+ * (`default.literal`); a schema constructed programmatically with a coerced
+ * `value` instead never reaches this module (it only builds from text).
+ */
+const defaultLiteral = (
+  input: GraphQLArgument | GraphQLInputField
+): string | undefined => {
+  const literal = input.default?.literal;
+  return literal ? print(literal) : undefined;
+};
+
+const inputValue = (
+  input: GraphQLArgument | GraphQLInputField
+): GraphqlInputValue => {
+  const value: GraphqlInputValue = {
+    description: input.description ?? "",
+    name: input.name,
+    type: typeRef(input.type),
+  };
+  const printed = defaultLiteral(input);
+  if (printed !== undefined) {
+    value.default = printed;
+  }
+  // `deprecationReason` is null on non-deprecated members in some builds;
+  // absent means "not deprecated" downstream, so both collapse to absent.
+  if (
+    input.deprecationReason !== null &&
+    input.deprecationReason !== undefined
+  ) {
+    value.deprecationReason = input.deprecationReason;
+  }
+  return value;
+};
+
+const outputField = (field: GraphQLField<unknown, unknown>): ModelField => {
+  const value: ModelField = {
+    args: field.args.map(inputValue),
+    description: field.description ?? "",
+    name: field.name,
+    type: typeRef(field.type),
+  };
+  if (
+    field.deprecationReason !== null &&
+    field.deprecationReason !== undefined
+  ) {
+    value.deprecationReason = field.deprecationReason;
+  }
+  return value;
+};
+
+const enumValues = (type: GraphQLEnumType): GraphqlEnumValue[] =>
+  type.getValues().map((value) => {
+    const member: GraphqlEnumValue = {
+      description: value.description ?? "",
+      name: value.name,
+    };
+    if (
+      value.deprecationReason !== null &&
+      value.deprecationReason !== undefined
+    ) {
+      member.deprecationReason = value.deprecationReason;
+    }
+    return member;
+  });
+
+const objectDef = (
+  type: GraphQLObjectType | GraphQLInterfaceType,
+  kind: "object" | "interface"
+): GraphqlTypeDef => {
+  const interfaces = type.getInterfaces().map((iface) => iface.name);
+  const def: GraphqlTypeDef = {
+    description: type.description ?? "",
+    fields: Object.values(type.getFields()).map(outputField),
+    kind,
+    name: type.name,
+  };
+  if (interfaces.length > 0) {
+    def.interfaces = interfaces;
+  }
+  return def;
+};
+
+const inputDef = (type: GraphQLInputObjectType): GraphqlTypeDef => ({
+  description: type.description ?? "",
+  inputFields: Object.values(type.getFields()).map(inputValue),
+  kind: "input",
+  name: type.name,
+});
+
+const unionDef = (type: GraphQLUnionType): GraphqlTypeDef => ({
+  description: type.description ?? "",
+  kind: "union",
+  name: type.name,
+  possibleTypes: type.getTypes().map((member) => member.name),
+});
+
+const scalarDef = (type: GraphQLScalarType): GraphqlTypeDef => {
+  const def: GraphqlTypeDef = {
+    description: type.description ?? "",
+    kind: "scalar",
+    name: type.name,
+  };
+  if (type.specifiedByURL !== null && type.specifiedByURL !== undefined) {
+    def.specifiedByUrl = type.specifiedByURL;
+  }
+  if (isSpecifiedScalarType(type)) {
+    def.builtIn = true;
+  }
+  return def;
+};
+
+const typeDef = (
+  type: GraphQLNamedType,
+  schema: GraphQLSchema
+): GraphqlTypeDef => {
+  if (isObjectType(type)) {
+    return objectDef(type, "object");
+  }
+  if (isInterfaceType(type)) {
+    const def = objectDef(type, "interface");
+    // Implementations are indexed on the schema, not the type — captured here
+    // so the type page can list "implemented by" without a schema in hand.
+    const implementers = schema
+      .getImplementations(type)
+      .objects.map((object) => object.name);
+    if (implementers.length > 0) {
+      def.possibleTypes = implementers;
+    }
+    return def;
+  }
+  if (isInputObjectType(type)) {
+    return inputDef(type);
+  }
+  if (isEnumType(type)) {
+    return {
+      description: type.description ?? "",
+      enumValues: enumValues(type),
+      kind: "enum",
+      name: type.name,
+    };
+  }
+  if (isUnionType(type)) {
+    return unionDef(type);
+  }
+  // SAFETY: the named-type union is exhaustive — after the object, interface,
+  // input, enum, and union guards, only scalars remain.
+  return scalarDef(type as GraphQLScalarType);
+};
+
+/** Lower a built schema to the serializable document. */
+const documentOf = (schema: GraphQLSchema): GraphqlDocument => {
+  const types: Record<string, GraphqlTypeDef> = {};
+  for (const [name, type] of Object.entries(schema.getTypeMap())) {
+    // Introspection meta-types (`__Schema`, `__Type`, …) are machinery, not API.
+    if (name.startsWith("__")) {
+      continue;
+    }
+    types[name] = typeDef(type, schema);
+  }
+  const roots: GraphqlDocument["roots"] = {};
+  const query = schema.getQueryType();
+  const mutation = schema.getMutationType();
+  const subscription = schema.getSubscriptionType();
+  if (query) {
+    roots.query = query.name;
+  }
+  if (mutation) {
+    roots.mutation = mutation.name;
+  }
+  if (subscription) {
+    roots.subscription = subscription.name;
+  }
+  return {
+    info: { description: schema.description ?? "" },
+    roots,
+    types,
+  };
+};
+
+/**
+ * A parsed JSON value carrying an introspection result's `__schema` key —
+ * possibly under the standard `{ data: … }` GraphQL response envelope. The
+ * generic-guard shape mirrors the document checks in `parse.ts`; the real
+ * validation is `buildClientSchema`'s, which throws a descriptive error on
+ * anything malformed inside `__schema`.
+ */
+const hasSchemaKey = <Value>(
+  value: Value
+): value is Value & { __schema: object } =>
+  typeof value === "object" && value !== null && "__schema" in value;
+
+/** A parsed JSON value shaped like a GraphQL response envelope. */
+const hasDataEnvelope = <Value>(
+  value: Value
+): value is Value & { data: unknown } =>
+  typeof value === "object" && value !== null && "data" in value;
+
+/** The introspection result inside a parsed JSON value, if it carries one. */
+const introspectionOf = <Value>(parsed: Value): object | undefined => {
+  if (hasSchemaKey(parsed)) {
+    return parsed;
+  }
+  return hasDataEnvelope(parsed) && hasSchemaKey(parsed.data)
+    ? parsed.data
+    : undefined;
+};
+
+/**
+ * Build the document from schema text: an introspection JSON result (the raw
+ * `{ __schema }` shape or a `{ data: { __schema } }` response envelope) or
+ * SDL. Anything else throws — JSON that isn't an introspection result names
+ * that problem directly instead of earning SDL syntax errors for a `{`.
+ */
+export const buildGraphqlDocument = (text: string): GraphqlDocument => {
+  let parsed: unknown;
+  let isJson = true;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    isJson = false;
+  }
+  if (isJson) {
+    const introspection = introspectionOf(parsed);
+    if (!introspection) {
+      throw new Error(
+        "the JSON document is not a GraphQL introspection result (no `__schema` key)."
+      );
+    }
+    // SAFETY: the guard above only establishes the `__schema` key;
+    // `buildClientSchema` validates the full introspection shape itself and
+    // throws a descriptive error on anything malformed.
+    return documentOf(
+      buildClientSchema(
+        introspection as Parameters<typeof buildClientSchema>[0]
+      )
+    );
+  }
+  return documentOf(buildSchema(text));
+};

package/src/openapi/graphql.ts

@@ -0,0 +1,212 @@
+import type { ApiOperationRef, ExtractedOperations } from "./model.ts";
+import { operationCollector, operationKey } from "./model.ts";
+
+/**
+ * Blume's own GraphQL model — the third front-end of the API reference
+ * pipeline. Schemas are lowered to this JSON-serializable document at parse
+ * time (see `buildGraphqlDocument` in `graphql-build.ts`, kept separate so
+ * `graphql`-js stays out of this module's import graph), so the components
+ * render entirely from plain data, mirroring how `model.ts` keeps OpenAPI
+ * documents serializable. Browser-safe: no Node imports (the components
+ * import from here).
+ */
+
+/** The three GraphQL operation kinds, each a sidebar group of root fields. */
+export const GRAPHQL_OPERATION_KINDS = [
+  "query",
+  "mutation",
+  "subscription",
+] as const;
+
+export type GraphqlOperationKind = (typeof GRAPHQL_OPERATION_KINDS)[number];
+
+/** The named-type kinds that get reference pages, in sidebar-group order. */
+export const GRAPHQL_TYPE_KINDS = [
+  "object",
+  "input",
+  "enum",
+  "interface",
+  "union",
+  "scalar",
+] as const;
+
+export type GraphqlTypeKind = (typeof GRAPHQL_TYPE_KINDS)[number];
+
+/** Everything a GraphQL operation ref's `method` can carry. */
+export type GraphqlMember = GraphqlOperationKind | GraphqlTypeKind;
+
+/** Sidebar/overview group label for each member kind. */
+export const GRAPHQL_GROUP_LABELS = {
+  enum: "Enums",
+  input: "Input Objects",
+  interface: "Interfaces",
+  mutation: "Mutations",
+  object: "Objects",
+  query: "Queries",
+  scalar: "Scalars",
+  subscription: "Subscriptions",
+  union: "Unions",
+} satisfies Record<GraphqlMember, string>;
+
+/**
+ * A type expression as it appears in the schema: the rendered display form
+ * (`[String!]!`) plus the named type at its core (`String`), so components can
+ * print the exact wrapper shape and still link to the named type's page.
+ */
+export interface GraphqlTypeRef {
+  display: string;
+  name: string;
+}
+
+/** An argument or input-object field. */
+export interface GraphqlInputValue {
+  name: string;
+  description: string;
+  type: GraphqlTypeRef;
+  /** Default value printed as a GraphQL literal (`10`, `"asc"`, `[1, 2]`). */
+  default?: string;
+  deprecationReason?: string;
+}
+
+/** An output field of an object or interface type (root fields included). */
+export interface GraphqlField {
+  name: string;
+  description: string;
+  type: GraphqlTypeRef;
+  args: GraphqlInputValue[];
+  deprecationReason?: string;
+}
+
+/** One member of an enum type. */
+export interface GraphqlEnumValue {
+  name: string;
+  description: string;
+  deprecationReason?: string;
+}
+
+/** One named type of the schema, flattened to the fields the reference renders. */
+export interface GraphqlTypeDef {
+  name: string;
+  kind: GraphqlTypeKind;
+  description: string;
+  /** Output fields (object and interface types). */
+  fields?: GraphqlField[];
+  /** Input fields (input object types). */
+  inputFields?: GraphqlInputValue[];
+  /** Members (enum types). */
+  enumValues?: GraphqlEnumValue[];
+  /** Member type names (unions) or implementing object types (interfaces). */
+  possibleTypes?: string[];
+  /** Interfaces this object/interface type implements. */
+  interfaces?: string[];
+  /** `specifiedBy` URL (custom scalars). */
+  specifiedByUrl?: string;
+  /**
+   * A spec-defined scalar (`String`, `Int`, …): kept for type refs to resolve
+   * against, but never given a reference page of its own.
+   */
+  builtIn?: boolean;
+}
+
+/** A normalized GraphQL schema, lowered to serializable data at parse time. */
+export interface GraphqlDocument {
+  /** Mirrors the OpenAPI `info` block so `source.ts` reads one shape. */
+  info?: { title?: string; version?: string; description?: string };
+  /** Root operation type names (`Query`, `Mutation`, `Subscription`). */
+  roots: Partial<Record<GraphqlOperationKind, string>>;
+  /** Named types by name, spec-defined scalars included, introspection types excluded. */
+  types: Record<string, GraphqlTypeDef>;
+}
+
+/** Whether an operation ref's method is a root-field kind (vs a type page). */
+export const isGraphqlOperationKind = (
+  method: string
+): method is GraphqlOperationKind =>
+  GRAPHQL_OPERATION_KINDS.some((kind) => kind === method);
+
+// Deterministic name order for type pages, independent of schema declaration
+// order and of the platform's collation (localeCompare varies across ICU
+// builds; codepoint order does not).
+const byName = (a: GraphqlTypeDef, b: GraphqlTypeDef): number =>
+  a.name < b.name ? -1 : 1;
+
+/**
+ * Flatten a GraphQL document into a route-mapped page list and its ordered
+ * groups — the GraphQL counterpart of `extractOperations` in `model.ts`, built
+ * on the same `operationCollector`. Root fields become operation pages grouped
+ * as Queries/Mutations/Subscriptions; every other named type becomes a type
+ * page grouped by kind (Objects, Input Objects, …). Spec-defined scalars and
+ * the root types themselves get no page — the roots' fields ARE the operation
+ * pages, and `String`/`Int`/… document nothing.
+ */
+export const extractGraphqlOperations = (
+  document: GraphqlDocument,
+  baseRoute: string
+): ExtractedOperations => {
+  const collector = operationCollector(baseRoute, new Map());
+  const rootNames = new Set(Object.values(document.roots));
+
+  for (const kind of GRAPHQL_OPERATION_KINDS) {
+    const rootName = document.roots[kind];
+    const root = rootName === undefined ? undefined : document.types[rootName];
+    for (const field of root?.fields ?? []) {
+      collector.add({
+        deprecated: field.deprecationReason !== undefined,
+        description: field.description,
+        // `operationKey` slug rules keep GraphQL URLs consistent with the
+        // other spec kinds; its fallback covers a name that slugifies empty.
+        key: operationKey(kind, field.name, field.name),
+        method: kind,
+        operationId: field.name,
+        path: field.name,
+        summary: "",
+        tag: GRAPHQL_GROUP_LABELS[kind],
+      });
+    }
+  }
+
+  for (const kind of GRAPHQL_TYPE_KINDS) {
+    const members = Object.values(document.types)
+      .filter(
+        (type) =>
+          type.kind === kind && !(type.builtIn || rootNames.has(type.name))
+      )
+      .toSorted(byName);
+    for (const type of members) {
+      collector.add({
+        deprecated: false,
+        description: type.description,
+        key: operationKey(kind, type.name, type.name),
+        method: kind,
+        operationId: type.name,
+        path: type.name,
+        summary: "",
+        tag: GRAPHQL_GROUP_LABELS[kind],
+      });
+    }
+  }
+
+  return { ...collector.finish(), warnings: [] };
+};
+
+/** Resolve the root field behind an operation-kind ref, if it still exists. */
+export const graphqlRootField = (
+  document: GraphqlDocument,
+  ref: ApiOperationRef
+): GraphqlField | undefined => {
+  if (!isGraphqlOperationKind(ref.method)) {
+    return undefined;
+  }
+  const rootName = document.roots[ref.method];
+  const root = rootName === undefined ? undefined : document.types[rootName];
+  return root?.fields?.find((field) => field.name === ref.operationId);
+};
+
+/** Resolve the named type behind a type-page ref, if it still exists. */
+export const graphqlTypeDef = (
+  document: GraphqlDocument,
+  ref: ApiOperationRef
+): GraphqlTypeDef | undefined => {
+  const type = document.types[ref.operationId ?? ""];
+  return type && type.kind === ref.method ? type : undefined;
+};

package/src/openapi/model.ts

@@ -1,6 +1,9 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
 
 import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+// Type-only, so the import can't cycle at runtime (graphql.ts imports the
+// collector from here).
+import type { GraphqlDocument, GraphqlMember } from "./graphql.ts";
 import type { ReferenceKind } from "./references.ts";
 import { slugify } from "./references.ts";
 
@@ -39,13 +42,32 @@ export type HttpMethod = (typeof HTTP_METHODS)[number];
 /** Group used for operations that declare no tag. */
 const UNTAGGED = "Operations";
 
+/** A lower-case letter or digit followed by a capital: `addPet`, `v2List`. */
+const CASE_BOUNDARY = /(?<before>[\p{Ll}\p{N}])(?<capital>\p{Lu})/gu;
+/** The last capital of an acronym before a capitalized word: `HTTPResponse`. */
+const ACRONYM_BOUNDARY = /(?<acronym>\p{Lu})(?<word>\p{Lu}\p{Ll})/gu;
+
+/**
+ * Hyphenate an identifier's word boundaries before slugifying, so a camelCase
+ * `operationId` keeps its words in the URL (`getHTTPResponse` ->
+ * `get-http-response`) instead of collapsing once `slugify` lowercases it.
+ * OpenAPI generators reuse operation ids as SDK method names, so camelCase is
+ * the norm there; GraphQL field and type names and AsyncAPI operation ids go
+ * through the same rule so every spec kind derives routes alike. An id that
+ * is already kebab-case has no boundaries to split and passes through as is.
+ */
+const splitIdentifier = (identifier: string): string =>
+  identifier
+    .replace(CASE_BOUNDARY, "$<before>-$<capital>")
+    .replace(ACRONYM_BOUNDARY, "$<acronym>-$<word>");
+
 /** A stable, URL-safe key for an operation: its `operationId`, else method+path. */
 export const operationKey = (
   method: string,
   path: string,
   operationId?: string
 ): string => {
-  const fromId = operationId ? slugify(operationId) : "";
+  const fromId = operationId ? slugify(splitIdentifier(operationId)) : "";
   return fromId || slugify(`${method}-${path}`);
 };
 
@@ -53,9 +75,15 @@ export const operationKey = (
 export interface ApiOperationRef {
   /** Stable key, unique within a spec; matches the MDX `<Operation id>`. */
   key: string;
-  /** HTTP method (OpenAPI) or `send`/`receive` action (AsyncAPI). */
-  method: HttpMethod | AsyncApiAction;
-  /** Templated path, e.g. `/pets/{id}` — or the channel address (AsyncAPI). */
+  /**
+   * HTTP method (OpenAPI), `send`/`receive` action (AsyncAPI), or the member
+   * kind — a root-field operation kind or a named-type kind (GraphQL).
+   */
+  method: HttpMethod | AsyncApiAction | GraphqlMember;
+  /**
+   * Templated path, e.g. `/pets/{id}` — the channel address (AsyncAPI), or
+   * the root field / type name (GraphQL).
+   */
   path: string;
   /** Full site route for this operation's page, e.g. `/reference/pet/add-pet`. */
   route: string;
@@ -90,7 +118,12 @@ export interface ApiSpecData {
   title: string;
   version: string;
   description: string;
-  document: ApiDocument | AsyncApiDocument;
+  document: ApiDocument | AsyncApiDocument | GraphqlDocument;
+  /**
+   * URL of the live GraphQL endpoint the playground and code samples target
+   * (GraphQL only; OpenAPI documents carry their servers in the document).
+   */
+  endpoint?: string;
   /** Operations keyed by {@link ApiOperationRef.key}. */
   operations: Record<string, ApiOperationRef>;
   tags: ApiTagRef[];

package/src/openapi/parse.ts

@@ -10,6 +10,8 @@ import { isAbsolute, join } from "pathe";
 import { hashText } from "../core/sources/cache.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
 import { normalizeAsyncApiDocument } from "./asyncapi.ts";
+import { buildGraphqlDocument } from "./graphql-build.ts";
+import type { GraphqlDocument } from "./graphql.ts";
 import type { ApiDocument } from "./model.ts";
 
 /**
@@ -393,3 +395,35 @@ export const parseAsyncApiSpec = async (
   }
   return { document: normalizeAsyncApiDocument(document), warnings };
 };
+
+export interface ParsedGraphqlSpec {
+  document: GraphqlDocument;
+  warnings: string[];
+}
+
+/**
+ * Read and lower a GraphQL schema — SDL text or an introspection JSON result —
+ * to the serializable document the reference renders from; the GraphQL mirror
+ * of {@link parseSpec}. Error semantics match the other kinds: an unreadable
+ * spec throws the read/fetch error, while readable-but-invalid schema text
+ * (SDL syntax errors, validation failures, JSON that isn't an introspection
+ * result) throws {@link InvalidSpecError} so callers suggest fixing the file
+ * rather than checking reachability.
+ */
+export const parseGraphqlSpec = async (
+  spec: string,
+  root: string,
+  options: SpecFetchOptions = {}
+): Promise<ParsedGraphqlSpec> => {
+  const { text, warnings } = await readSpecText(spec, root, options);
+  try {
+    return { document: buildGraphqlDocument(text), warnings };
+  } catch (error) {
+    // SAFETY: `graphql`-js throws GraphQLError (an Error) for syntax and
+    // validation failures, and `buildGraphqlDocument` throws plain Errors for
+    // non-introspection JSON; only the message is surfaced.
+    throw new InvalidSpecError(
+      `${spec} is not a valid GraphQL schema (${(error as Error).message.trim()})`
+    );
+  }
+};

package/src/openapi/proxy.ts

@@ -51,6 +51,15 @@ const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
 /** Hops followed before giving up, matching fetch's own redirect limit. */
 const MAX_REDIRECTS = 20;
 
+/**
+ * Deadline for the whole upstream exchange, redirects included. The
+ * playground client aborts its own request after 30 s, but that never
+ * reaches the server-side fetch: without a deadline here, a documented API
+ * that accepts the connection and never answers would hold a server request
+ * slot until the platform killed it. Matches the client's limit.
+ */
+const UPSTREAM_TIMEOUT_MS = 30_000;
+
 /** A 400 the playground client can render verbatim. */
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
@@ -96,6 +105,8 @@ const followUpstream = async (args: {
   /** Hops already followed; the chain is bounded by {@link MAX_REDIRECTS}. */
   hop: number;
   method: string;
+  /** One deadline shared by every hop, so a redirect chain can't extend it. */
+  signal: AbortSignal;
   url: URL;
 }): Promise<Response> => {
   const response = await args.fetchImpl(args.url, {
@@ -103,6 +114,7 @@ const followUpstream = async (args: {
     headers: args.headers,
     method: args.method,
     redirect: "manual",
+    signal: args.signal,
   });
   const location = REDIRECT_STATUS.has(response.status)
     ? response.headers.get("location")
@@ -151,10 +163,15 @@ const followUpstream = async (args: {
  * Loopback and private addresses need no separate rule: they are reachable only
  * when a spec documents them, which is exactly the local-API case that must
  * keep working.
+ *
+ * `timeoutMs` bounds the upstream exchange (see {@link UPSTREAM_TIMEOUT_MS});
+ * an upstream that doesn't answer in time is the same 502 as an unreachable
+ * one. Injectable so tests don't wait out the real deadline.
  */
 export const createPlaygroundProxyHandler = (
   origins: readonly string[],
-  fetchImpl: typeof fetch = fetch
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs = UPSTREAM_TIMEOUT_MS
 ) => {
   const allowed = new Set(origins);
   return async (request: Request): Promise<Response> => {
@@ -192,14 +209,22 @@ export const createPlaygroundProxyHandler = (
         headers: filterHeaders(request.headers, REQUEST_DROP),
         hop: 0,
         method: request.method,
+        signal: AbortSignal.timeout(timeoutMs),
         url: parsed,
       });
     } catch (error) {
-      // SAFETY: followUpstream itself only throws `new Error(...)`, and a
-      // failed fetch rejects with a TypeError per spec — both are Errors
-      // carrying `.message`.
+      // SAFETY: followUpstream itself only throws `new Error(...)`, a failed
+      // fetch rejects with a TypeError per spec, and a timed-out one with a
+      // `TimeoutError` DOMException — all Errors carrying `.name` and
+      // `.message`.
+      const { name, message } = error as Error;
       return Response.json(
-        { error: (error as Error).message },
+        {
+          error:
+            name === "TimeoutError"
+              ? `Upstream ${parsed.href} did not respond within ${timeoutMs}ms.`
+              : message,
+        },
         { status: 502 }
       );
     }