blume 2.0.1 → 2.0.3

package/src/openapi/model.ts

@@ -1,6 +1,10 @@
 import type { Document, OperationObject } from "@scalar/openapi-types/3.1";
 
-import type { AsyncApiAction, AsyncApiDocument } from "./asyncapi.ts";
+import type {
+  AsyncApiAction,
+  AsyncApiDocument,
+  AsyncApiSpecValue,
+} 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";
@@ -99,7 +103,10 @@ export interface ApiOperationRef {
   channelId?: string;
 }
 
-/** A tag/section, in first-seen order. */
+/**
+ * A tag/section: the spec's declared tags in their declared order, then any
+ * undeclared tag an operation uses, in first-seen order.
+ */
 export interface ApiTagRef {
   slug: string;
   name: string;
@@ -212,6 +219,40 @@ export const specAddresses = (spec: ApiSpecData): SpecAddresses => {
   return { addresses, label: "Base URL" };
 };
 
+const SERVER_VARIABLE = /\{(?<name>[^{}]+)\}/gu;
+
+const isDocumentObject = (
+  value: AsyncApiSpecValue
+): value is Record<string, AsyncApiSpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+// YAML reads an unquoted `default: 8443` as a number; it is still the port.
+const isVariableDefault = (
+  value: AsyncApiSpecValue
+): value is string | number =>
+  typeof value === "string" || typeof value === "number";
+
+/**
+ * A server URL template — an OpenAPI `servers[].url`, an AsyncAPI server's
+ * `host` or `pathname` — with each `{variable}` replaced by the `default` its
+ * `variables` map declares. Code samples, the playground's Send, and the
+ * proxy allowlist all need a real address, and
+ * `https://{region}.api.example.com` is not one. A variable the map doesn't
+ * define with a default (invalid per both specs) stays templated.
+ */
+export const withServerDefaults = (
+  template: string,
+  variables: AsyncApiSpecValue
+): string =>
+  template.replaceAll(SERVER_VARIABLE, (match, name: string) => {
+    const variable =
+      isDocumentObject(variables) && Object.hasOwn(variables, name)
+        ? variables[name]
+        : undefined;
+    const value = isDocumentObject(variable) ? variable.default : undefined;
+    return isVariableDefault(value) ? String(value) : match;
+  });
+
 // The runtime object check stands guard because the document was parsed from
 // arbitrary YAML/JSON: a spec can put a scalar where the type promises an
 // operation object.
@@ -219,9 +260,18 @@ const isOperation = (
   value: OperationObject | undefined
 ): value is OperationObject => typeof value === "object" && value !== null;
 
-/** A declared tag whose `name` really is a string at runtime, type aside. */
-const hasTagName = (tag: SpecTag): tag is SpecTag =>
-  typeof tag.name === "string";
+/** Whether a spec value is text YAML may have read as a number. */
+const isText = <Value>(value: Value): value is Value & (string | number) =>
+  typeof value === "string" || typeof value === "number";
+
+/**
+ * A spec field that names something, as a string. YAML reads an unquoted
+ * `operationId: 404` or `tags: [2024]` as a number, which still names the
+ * operation or tag; anything else a hand-written spec puts there counts as
+ * absent.
+ */
+const specText = <Value>(value: Value): string | undefined =>
+  isText(value) ? String(value) : undefined;
 
 /**
  * Assign each distinct tag name a unique slug. `slugify` can collapse
@@ -254,9 +304,6 @@ export const tagSlugger = (): ((name: string) => string) => {
 /** An operation before the collector assigns its unique key and route. */
 type CollectedOperation = Omit<ApiOperationRef, "route" | "tagSlug">;
 
-/** A document's declared tag entry (`tags[n]`). */
-type SpecTag = NonNullable<ApiDocument["tags"]>[number];
-
 /** The flattened output both extractors produce. */
 export interface CollectedOperations {
   operations: ApiOperationRef[];
@@ -276,9 +323,10 @@ export interface ExtractedOperations extends CollectedOperations {
 
 /**
  * The collector behind both extractors (OpenAPI here, AsyncAPI in
- * `asyncapi.ts`): first-seen tag ordering, key de-duplication (a repeated key
- * gains its method/action as a suffix), and the shared route template — so
- * URL shape and slug rules can never drift between the two spec kinds.
+ * `asyncapi.ts`): declared-then-first-seen tag ordering, key de-duplication
+ * (a repeated key gains its method/action as a suffix), and the shared route
+ * template — so URL shape and slug rules can never drift between the two spec
+ * kinds.
  */
 export const operationCollector = (
   baseRoute: string,
@@ -310,15 +358,27 @@ export const operationCollector = (
     });
   };
 
+  // Declared tags in the order the spec's `tags` list gives them, then any
+  // tag an operation uses without declaring it, in first-use order. The
+  // declared order is the author's section order, not an accident of which
+  // path happens to come first.
+  const declared = [...tagMeta.keys()];
+  const rank = (name: string): number => {
+    const index = declared.indexOf(name);
+    return index === -1 ? declared.length : index;
+  };
+
   const finish = (): CollectedOperations => ({
     operations,
-    tags: tagOrder.map((name) => ({
-      description: tagMeta.get(name) ?? "",
-      name,
-      // The same slugger instance, so every tag resolves to the slug its
-      // operations were routed under.
-      slug: slugForTag(name),
-    })),
+    tags: tagOrder
+      .toSorted((a, b) => rank(a) - rank(b))
+      .map((name) => ({
+        description: tagMeta.get(name) ?? "",
+        name,
+        // The same slugger instance, so every tag resolves to the slug its
+        // operations were routed under.
+        slug: slugForTag(name),
+      })),
   });
 
   return { add, finish };
@@ -328,7 +388,8 @@ export const operationCollector = (
  * Flatten a 3.1 document into a route-mapped operation list and its ordered
  * tags. Operations inherit the first tag they declare; keys are de-duplicated so
  * a repeated `operationId` still yields distinct routes. `warnings` reports
- * anything skipped (a `$ref` path item), so missing operations aren't silent.
+ * anything skipped (a `$ref` path item, webhooks), so missing operations
+ * aren't silent.
  */
 export const extractOperations = (
   document: ApiDocument,
@@ -336,9 +397,10 @@ export const extractOperations = (
 ): ExtractedOperations => {
   const warnings: string[] = [];
   const tagMeta = new Map(
-    (document.tags ?? [])
-      .filter(hasTagName)
-      .map((tag) => [tag.name, tag.description ?? ""])
+    (document.tags ?? []).flatMap((tag): [string, string][] => {
+      const name = specText(tag.name);
+      return name === undefined ? [] : [[name, tag.description ?? ""]];
+    })
   );
   const collector = operationCollector(baseRoute, tagMeta);
 
@@ -358,19 +420,29 @@ export const extractOperations = (
       if (!isOperation(operation)) {
         continue;
       }
+      const operationId = specText(operation.operationId);
       collector.add({
         deprecated: operation.deprecated ?? false,
-        description: operation.description ?? "",
-        key: operationKey(method, path, operation.operationId),
+        description: specText(operation.description) ?? "",
+        key: operationKey(method, path, operationId),
         method,
-        operationId: operation.operationId,
+        operationId,
         path,
-        summary: operation.summary ?? "",
-        tag: operation.tags?.[0] ?? UNTAGGED,
+        summary: specText(operation.summary) ?? "",
+        tag: specText(operation.tags?.[0]) ?? UNTAGGED,
       });
     }
   }
 
+  // OpenAPI 3.1 webhooks (requests the API sends, not ones it serves) have no
+  // page renderer; say so rather than dropping them silently.
+  const webhooks = Object.keys(document.webhooks ?? {});
+  if (webhooks.length > 0) {
+    warnings.push(
+      `The spec declares ${webhooks.length === 1 ? "a webhook" : `${webhooks.length} webhooks`} under "webhooks" (${webhooks.join(", ")}); webhooks aren't rendered, so they are missing from the reference.`
+    );
+  }
+
   return { ...collector.finish(), warnings };
 };
 

package/src/openapi/proxy.ts

@@ -12,25 +12,52 @@
  * network and stays safe to bundle into the generated endpoint file.
  */
 
+import { PROXY_HEADERS_HEADER } from "../components/openapi/request.ts";
 import { readCappedBody } from "../core/request-body.ts";
 
 /**
- * Request headers never forwarded upstream: hop-by-hop headers describe this
- * connection (not the upstream one), `host`/`origin`/`referer` would leak or
- * misattribute the docs site, and `cookie` would forward reader credentials
- * to an arbitrary target. `accept-encoding`/`content-length` are recomputed
- * by the runtime's own fetch.
+ * Request headers never forwarded upstream, even when the playground names
+ * them: hop-by-hop headers describe this connection (not the upstream one),
+ * `host`/`origin`/`referer` would leak or misattribute the docs site, `cookie`
+ * would forward reader credentials to an arbitrary target, and the rest are
+ * set or rewritten by the platform in front of the docs server — the
+ * reader's address, the edge's own identity — whatever the browser sent.
+ * `accept-encoding`/`content-length` are recomputed by the runtime's own
+ * fetch.
  */
 const REQUEST_DROP = {
   "accept-encoding": true,
+  "cdn-loop": true,
   connection: true,
   "content-length": true,
   cookie: true,
+  forwarded: true,
   host: true,
+  "keep-alive": true,
   origin: true,
+  "proxy-authorization": true,
   referer: true,
+  te: true,
+  trailer: true,
+  "transfer-encoding": true,
+  "true-client-ip": true,
+  upgrade: true,
+  via: true,
+  "x-client-ip": true,
+  "x-real-ip": true,
 } satisfies Record<string, true>;
 
+/**
+ * Platform header families, dropped like {@link REQUEST_DROP}: Cloudflare's
+ * (`cf-connecting-ip`, the Access `cf-access-jwt-assertion`), the
+ * `x-forwarded-*` set, Vercel's (`x-vercel-oidc-token`), Netlify's, Fly's,
+ * and AWS load balancers' (`x-amzn-oidc-data`).
+ */
+const PLATFORM_HEADER = /^(?:cf-|x-forwarded-|x-vercel-|x-nf-|fly-|x-amzn-)/u;
+
+/** The {@link PROXY_HEADERS_HEADER} name as `Headers` iterates it. */
+const DECLARED = PROXY_HEADERS_HEADER.toLowerCase();
+
 /**
  * Upstream response headers never returned to the browser: the runtime's
  * fetch already decoded the body (so `content-encoding`/`content-length` no
@@ -99,20 +126,45 @@ const DOCUMENT_TYPE =
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
 
-/** Copy headers, skipping the given denylist (names are already lowercase). */
+/**
+ * Copy headers, skipping the given denylist and any name `keep` rejects
+ * (names are already lowercase).
+ */
 const filterHeaders = (
   source: Headers,
-  drop: Record<string, true>
+  drop: Record<string, true>,
+  keep: (name: string) => boolean = () => true
 ): Headers => {
   const headers = new Headers();
   for (const [name, value] of source) {
-    if (!drop[name]) {
+    if (!drop[name] && keep(name)) {
       headers.set(name, value);
     }
   }
   return headers;
 };
 
+/**
+ * The headers to send upstream: only those the playground set itself, which
+ * it names in {@link PROXY_HEADERS_HEADER}. Forwarding everything else minus
+ * a denylist would hand the documented API whatever the browser and the
+ * platform attach on their own — the HTTP Basic credentials of a docs site
+ * behind a password (a same-origin fetch with no `Authorization` of its own
+ * carries them), a Cloudflare Access assertion, a Vercel OIDC token.
+ */
+const forwardedHeaders = (source: Headers): Headers => {
+  const named = new Set(
+    (source.get(DECLARED) ?? "")
+      .split(",")
+      .map((name) => name.trim().toLowerCase())
+  );
+  return filterHeaders(
+    source,
+    REQUEST_DROP,
+    (name) => named.has(name) && !PLATFORM_HEADER.test(name)
+  );
+};
+
 /** A 403 for a target no configured spec declares as one of its servers. */
 const forbidden = (origin: string): Response =>
   Response.json(
@@ -186,7 +238,8 @@ const followUpstream = async (args: {
 /**
  * Build the `/_api-proxy` fetch handler. The client sends its REAL method,
  * headers, and body to `?url=<encodeURIComponent(target)>`; the handler
- * forwards them (minus {@link REQUEST_DROP}) and mirrors the upstream response
+ * forwards the method, the body, and the headers the client names (see
+ * {@link forwardedHeaders}), and mirrors the upstream response
  * (minus {@link RESPONSE_DROP}) with an `x-blume-proxy` marker. An unreachable
  * upstream is a 502 with a JSON `error`.
  *
@@ -252,7 +305,7 @@ export const createPlaygroundProxyHandler = (
         allowed,
         body,
         fetchImpl,
-        headers: filterHeaders(request.headers, REQUEST_DROP),
+        headers: forwardedHeaders(request.headers),
         hop: 0,
         method: request.method,
         signal: AbortSignal.timeout(timeoutMs),

package/src/openapi/render-mdx.ts

@@ -90,6 +90,9 @@ const codeSpans = (text: string, tree: Root): [number, number][] => {
   return spans;
 };
 
+/** Stands in for `<` when locating code spans (see `mdxSafe`). */
+const HTML_MASK = "";
+
 /**
  * Escape MDX-special syntax in prose while leaving code verbatim. A spec is
  * someone else's content, so a link whose destination isn't a web, mail, or
@@ -101,8 +104,14 @@ const mdxSafe = (text: string): string => {
   const unsafe = unsafeLinkSpans(tree);
   const insideUnsafe = (offset: number): boolean =>
     unsafe.some((span) => offset >= span.start && offset < span.end);
+  // Code spans come from a parse with every `<` masked. The emitted MDX
+  // escapes each `<` outside code to `&lt;`, so no line of it is an HTML
+  // block — but CommonMark reads `<div>` as one and never looks for the code
+  // spans inside it, which would leave their braces to be escaped and shown
+  // as a literal `&#123;`. The mask is one code unit, so offsets line up.
+  const masked = text.replaceAll("<", HTML_MASK);
   const segments = [
-    ...codeSpans(text, tree)
+    ...codeSpans(masked, fromMarkdown(masked))
       .filter(([start]) => !insideUnsafe(start))
       .map(([start, end]) => ({ end, start, text: text.slice(start, end) })),
     ...unsafe,
@@ -117,6 +126,45 @@ const mdxSafe = (text: string): string => {
   return out + escapeProse(text.slice(cursor));
 };
 
+// A fence opener: up to three columns of indentation, then a run of three or
+// more backticks or tildes.
+const FENCE_OPEN = /^ {0,3}(?<fence>`{3,}|~{3,})/u;
+
+/**
+ * Close a fenced code block the text leaves open. An unclosed fence runs to
+ * the end of the document, so the component appended after a description
+ * would render as code, and the page would lose its parameters, responses,
+ * and playground. Only the last top-level block can run that far — a fence in
+ * a quote or list closes with its container — and it's read from the same
+ * `<`-masked parse as `mdxSafe`, since the emitted MDX has no HTML blocks to
+ * hide a fence in.
+ */
+const closeOpenFence = (text: string): string => {
+  const last = fromMarkdown(text.replaceAll("<", HTML_MASK)).children.at(-1);
+  if (last?.type !== "code") {
+    return text;
+  }
+  // fromMarkdown always stamps positions; 0 is an unreachable guard.
+  const block = text.slice(last.position?.start.offset ?? 0);
+  const fence = FENCE_OPEN.exec(block)?.groups?.fence;
+  // No fence: indented code, which MDX reads as a paragraph.
+  if (!fence) {
+    return text;
+  }
+  const lines = block.split("\n");
+  const closer = new RegExp(
+    `^ {0,3}${fence[0]}{${fence.length},}[ \\t\\r]*$`,
+    "u"
+  );
+  return lines.length > 1 && closer.test(lines.at(-1) ?? "")
+    ? text
+    : `${text}\n${fence}`;
+};
+
+/** Spec prose as MDX that is safe to follow with a component. */
+const descriptionMdx = (text: string): string =>
+  mdxSafe(closeOpenFence(text.trim()));
+
 /**
  * Frontmatter emitted for one operation or overview page. Boolean flags are
  * assigned only when set, so absent keys stay absent in the staged MDX.
@@ -240,7 +288,7 @@ const operationDescription = (
 /** Prepend a markdown description (if any) above a component invocation. */
 const withDescription = (description: string, component: string): string =>
   description.trim()
-    ? `${mdxSafe(description.trim())}\n\n${component}`
+    ? `${descriptionMdx(description)}\n\n${component}`
     : component;
 
 export const operationMdx = (
@@ -356,7 +404,7 @@ export const overviewMdx = (
       continue;
     }
     const description = tag.description.trim()
-      ? [mdxSafe(tag.description.trim())]
+      ? [descriptionMdx(tag.description)]
       : [];
     tagSections.push(
       [