blume 1.7.3 → 2.0.0

package/src/openapi/parse.ts

@@ -1,18 +1,24 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 
-import type { AsyncAPIDocument as ConverterDocument } from "@asyncapi/converter";
-import { convert } from "@asyncapi/converter";
+import type * as ConverterModule from "@asyncapi/converter";
 import { normalize, upgrade } from "@scalar/openapi-parser";
 import pRetry, { AbortError } from "p-retry";
 import { isAbsolute, join } from "pathe";
+import type * as UndiciModule from "undici";
 
+import {
+  commandsFor,
+  detectProjectPackageManager,
+} from "../cli/init/scaffold.ts";
+import { nodeRequire } from "../core/node-require.ts";
 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";
+import { SpecDependencyError } from "./spec-dependency-error.ts";
 
 /**
  * Spec loading and normalization. Blume reuses Scalar's parser
@@ -83,18 +89,21 @@ export interface SpecFetchOptions {
  * spec is fetched with one configured. Node's built-in `fetch` ignores `*_PROXY`
  * on its own; undici's env proxy agent, installed on the shared global-dispatcher
  * symbol, wires it in without replacing `fetch` (so tests can still stub it).
- * Best-effort and lazy: no proxy env means no undici import at all, and an
+ * Best-effort and lazy: no proxy env means undici never loads, and an
  * unavailable undici just leaves the direct connection in place.
  */
 let proxyInstalled = false;
-const ensureProxyDispatcher = async (): Promise<void> => {
+const ensureProxyDispatcher = (): void => {
   // Only memoize a successful install: with no proxy configured we cheaply
   // re-check each time, so a proxy set later in the process still takes effect.
   if (proxyInstalled || !PROXY_ENV_VARS.some((name) => process.env[name])) {
     return;
   }
   try {
-    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import("undici");
+    // `require`, not `import()`: an ejected app scans in `astro:build:done`
+    // (see `core/node-require.ts`).
+    const { EnvHttpProxyAgent, setGlobalDispatcher }: typeof UndiciModule =
+      nodeRequire("undici");
     setGlobalDispatcher(new EnvHttpProxyAgent());
     proxyInstalled = true;
   } catch {
@@ -177,7 +186,7 @@ const retryableFetchError = (
 
 /** Fetch a remote spec's text, retrying transient failures with backoff. */
 const fetchSpecText = async (spec: string): Promise<string> => {
-  await ensureProxyDispatcher();
+  ensureProxyDispatcher();
   return await pRetry(
     async () => {
       const attempt = await attemptFetch(spec);
@@ -323,15 +332,6 @@ export interface ParsedAsyncApiSpec {
   warnings: string[];
 }
 
-/**
- * Read and normalize a spec to an AsyncAPI 3.x document — the AsyncAPI mirror
- * of {@link parseSpec}. 1.x/2.x documents are lifted to 3.0 with the official
- * `@asyncapi/converter` (channels + operations with `send`/`receive` actions),
- * so the extractor and components only ever handle one shape; `$ref`s stay
- * intact, matching the OpenAPI path. Error semantics match `parseSpec`: an
- * unreadable spec throws, a readable non-AsyncAPI document throws
- * {@link InvalidSpecError}, and callers lower both into source diagnostics.
- */
 /**
  * An object carrying a non-empty `asyncapi` version string — the only input
  * the converter and extractor can key on. `normalize` yields undefined for
@@ -346,6 +346,53 @@ const isAsyncApiDocument = <Value>(
   typeof value.asyncapi === "string" &&
   value.asyncapi !== "";
 
+const CONVERTER = "@asyncapi/converter";
+
+/**
+ * Load `@asyncapi/converter`, an optional peer. Only a 1.x/2.x spec needs it,
+ * and it depends on `@asyncapi/parser` — which it never loads — and so on
+ * Spectral and Scarf's telemetry postinstall, an unapproved build script that
+ * pnpm 12 refuses to install past. Leaving it out of a default install keeps
+ * `pnpm dlx blume` working; a spec that needs it gets the install command
+ * instead, through {@link SpecDependencyError}.
+ */
+const loadConverter = async (
+  spec: string,
+  version: string,
+  root: string
+): Promise<typeof ConverterModule> => {
+  try {
+    // `require`, not `import()`: see `core/node-require.ts`.
+    const converter: typeof ConverterModule = nodeRequire(CONVERTER);
+    return converter;
+  } catch (error) {
+    // SAFETY: a failed `require` throws a Node error; `code` and `message`
+    // are the only fields read.
+    const { code, message } = error as NodeJS.ErrnoException;
+    // Only the converter itself missing is the project's to fix; anything
+    // else (a broken install of one of its own dependencies) surfaces as is.
+    if (code !== "MODULE_NOT_FOUND" || !message.includes(`'${CONVERTER}'`)) {
+      throw error;
+    }
+    const { add } = commandsFor(await detectProjectPackageManager(root));
+    throw new SpecDependencyError(
+      `${spec} is AsyncAPI ${version}, and converting it to AsyncAPI 3.0 needs "${CONVERTER}", which isn't installed`,
+      `Install it with \`${add} ${CONVERTER}\`, or convert the spec to AsyncAPI 3.0.`
+    );
+  }
+};
+
+/**
+ * Read and normalize a spec to an AsyncAPI 3.x document — the AsyncAPI mirror
+ * of {@link parseSpec}. 1.x/2.x documents are lifted to 3.0 with the official
+ * `@asyncapi/converter` (channels + operations with `send`/`receive` actions),
+ * so the extractor and components only ever handle one shape; `$ref`s stay
+ * intact, matching the OpenAPI path. Error semantics match `parseSpec`: an
+ * unreadable spec throws, a readable non-AsyncAPI document throws
+ * {@link InvalidSpecError}, a pre-3.0 document without the converter installed
+ * throws {@link SpecDependencyError}, and callers lower all three into source
+ * diagnostics.
+ */
 export const parseAsyncApiSpec = async (
   spec: string,
   root: string,
@@ -361,6 +408,7 @@ export const parseAsyncApiSpec = async (
   const version = normalized.asyncapi;
   let document: AsyncApiDocument = normalized;
   if (!version.startsWith("3.")) {
+    const { convert } = await loadConverter(spec, version, root);
     // The converter reports lossy conversions (e.g. a 2.x parameter schema
     // that 3.0 can't express) through console.warn — capture those as spec
     // warnings instead of letting them leak into CLI output.
@@ -374,7 +422,7 @@ export const parseAsyncApiSpec = async (
       // the 3.0 shape the extractor consumes; the two packages just declare
       // the document type differently.
       document = convert(
-        document as ConverterDocument,
+        document as Parameters<typeof convert>[0],
         "3.0.0"
       ) as AsyncApiDocument;
     } catch (error) {

package/src/openapi/proxy.ts

@@ -1,16 +1,19 @@
 /**
  * The playground's CORS proxy. Browsers block the "Try it" panel's `fetch`
  * whenever the documented API doesn't allow cross-origin requests from the
- * docs site, so `openapi.playground.proxy: true` mounts this handler at
+ * docs site, so `playground: { proxy: true }` on an `openapi()` reference
+ * mounts this handler at
  * `/_api-proxy` (server output only) and the client sends its real request
  * here as `?url=<encoded target>` instead. The handler replays the request
  * upstream and mirrors the response back, so the browser only ever talks
  * same-origin.
  *
- * Kept dependency-free and `fetch`-injectable so it unit-tests without a
+ * Kept dependency-light and `fetch`-injectable so it unit-tests without a
  * network and stays safe to bundle into the generated endpoint file.
  */
 
+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
@@ -60,6 +63,38 @@ const MAX_REDIRECTS = 20;
  */
 const UPSTREAM_TIMEOUT_MS = 30_000;
 
+/**
+ * Largest request body the proxy forwards: 4 MiB, under Vercel's 4.5 MB
+ * function limit, so a request that works on one host works on the others.
+ * The body is buffered before it's replayed, and a self-hosted Node server
+ * has no platform cap of its own, so without this one oversized POST could
+ * allocate its whole size in the server's memory.
+ */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+/**
+ * Headers every proxied response carries. The proxy serves another host's
+ * bytes from the docs origin, so an upstream HTML page — an error page that
+ * echoes its input, say — would otherwise run script as the docs site for
+ * anyone who opens a crafted `/_api-proxy?url=…` link. `sandbox` gives such a
+ * page an opaque origin with scripts off, `nosniff` stops a mistyped body
+ * being rendered as HTML, and `same-origin` keeps other sites from embedding
+ * the responses. None of them affect the playground's own `fetch`.
+ */
+const RESPONSE_SECURITY_HEADERS = {
+  "Content-Security-Policy": "sandbox; default-src 'none'",
+  "Cross-Origin-Resource-Policy": "same-origin",
+  "X-Content-Type-Options": "nosniff",
+} satisfies Record<string, string>;
+
+/**
+ * Media types a browser would render as a document when the proxy URL is
+ * opened directly. Their responses are also marked as downloads, so even a
+ * browser that ignores the sandbox saves the page instead of showing it.
+ */
+const DOCUMENT_TYPE =
+  /^\s*(?:text\/html|application\/xhtml\+xml|image\/svg\+xml)\b/iu;
+
 /** A 400 the playground client can render verbatim. */
 const badRequest = (error: string): Response =>
   Response.json({ error }, { status: 400 });
@@ -99,7 +134,7 @@ const forbidden = (origin: string): Response =>
  */
 const followUpstream = async (args: {
   allowed: ReadonlySet<string>;
-  body: ArrayBuffer | undefined;
+  body: Uint8Array<ArrayBuffer> | undefined;
   fetchImpl: typeof fetch;
   headers: Headers;
   /** Hops already followed; the chain is bounded by {@link MAX_REDIRECTS}. */
@@ -166,12 +201,15 @@ const followUpstream = async (args: {
  *
  * `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.
+ * one. Injectable so tests don't wait out the real deadline. A request body
+ * over `maxBodyBytes` (see {@link MAX_BODY_BYTES}) is a 413, and every
+ * mirrored response carries {@link RESPONSE_SECURITY_HEADERS}.
  */
 export const createPlaygroundProxyHandler = (
   origins: readonly string[],
   fetchImpl: typeof fetch = fetch,
-  timeoutMs = UPSTREAM_TIMEOUT_MS
+  timeoutMs = UPSTREAM_TIMEOUT_MS,
+  maxBodyBytes = MAX_BODY_BYTES
 ) => {
   const allowed = new Set(origins);
   return async (request: Request): Promise<Response> => {
@@ -194,11 +232,19 @@ export const createPlaygroundProxyHandler = (
 
     // Buffer the body instead of streaming it: GET/HEAD must not carry one
     // (fetch rejects it), and a buffered body avoids the `duplex` requirement
-    // streaming request bodies have in Node.
-    const body =
-      request.method === "GET" || request.method === "HEAD"
-        ? undefined
-        : await request.arrayBuffer();
+    // streaming request bodies have in Node. The buffer is capped.
+    const bodyless = request.method === "GET" || request.method === "HEAD";
+    const body = bodyless
+      ? undefined
+      : await readCappedBody(request, maxBodyBytes);
+    if (!bodyless && body === undefined) {
+      return Response.json(
+        {
+          error: `The request body is larger than the ${maxBodyBytes}-byte limit the docs proxy forwards.`,
+        },
+        { status: 413 }
+      );
+    }
 
     let upstream: Response;
     try {
@@ -233,6 +279,12 @@ export const createPlaygroundProxyHandler = (
     // Marks proxied responses so the client (and debugging humans) can tell
     // them apart from direct responses.
     headers.set("x-blume-proxy", "1");
+    for (const [name, value] of Object.entries(RESPONSE_SECURITY_HEADERS)) {
+      headers.set(name, value);
+    }
+    if (DOCUMENT_TYPE.test(headers.get("content-type") ?? "")) {
+      headers.set("Content-Disposition", "attachment");
+    }
     return new Response(upstream.body, {
       headers,
       status: upstream.status,