blume 2.0.2 → 2.1.0

package/src/components/openapi/playground-client.ts

@@ -16,8 +16,14 @@ import type {
   PlaygroundModel,
   RequestValues,
 } from "./request.ts";
-import { buildRequest, redactAuth } from "./request.ts";
-import { sampleLanguages } from "./snippets.ts";
+import {
+  bodyEncoding,
+  buildRequest,
+  PROXY_HEADERS_HEADER,
+  redactAuth,
+} from "./request.ts";
+import { fetchRefusesMethod, sampleLanguages } from "./snippets.ts";
+import type { RequestSample } from "./snippets.ts";
 import { validateJson } from "./validate-json.ts";
 
 /**
@@ -42,6 +48,16 @@ const COOKIE_MESSAGE =
   "send the cookie credential you entered. Copy the sample above and run it " +
   "from a terminal instead.";
 
+/**
+ * fetch refuses the TRACE method outright, proxied or not: the browser throws
+ * before anything is sent, which the send's catch would misdiagnose as the
+ * CORS wall or an unreachable host. The cURL and Python samples can send it.
+ */
+const TRACE_MESSAGE =
+  "Browsers don't allow a page to send a `TRACE` request, so this panel " +
+  "can't send it. Run the cURL or Python sample above from a terminal " +
+  "instead.";
+
 /**
  * A fetch that fails before any response when the API couldn't be reached at
  * all — a mistyped host, a refused connection, no network — rather than
@@ -185,6 +201,50 @@ const removeStored = (key: string): void => {
   }
 };
 
+/**
+ * The headers a live send carries. A `Cookie` header can still arrive via a
+ * spec-declared header parameter; the browser would silently drop the
+ * forbidden name anyway, so it is stripped rather than earn a console
+ * warning. Blume's own proxy — always a path on this site — forwards only the
+ * headers named in {@link PROXY_HEADERS_HEADER}, never ones the browser or
+ * the platform add on their own; a multipart body's Content-Type is fetch's,
+ * written with the boundary, so it is named without being set. An external
+ * proxy on another origin gets no such header: it would only be one more name
+ * for its preflight to allow.
+ */
+const sendHeaders = (sample: RequestSample, proxy: string) => {
+  const headers = { ...sample.headers };
+  delete headers.Cookie;
+  if (proxy.startsWith("/") && !proxy.startsWith("//")) {
+    const names = Object.keys(headers);
+    if (sample.formData) {
+      names.push("Content-Type");
+    }
+    headers[PROXY_HEADERS_HEADER] = names.join(", ");
+  }
+  return headers;
+};
+
+/**
+ * The body a live send carries: multipart parts as `FormData`, anything else
+ * as its text. fetch throws a synchronous TypeError for a GET/HEAD with a
+ * body — which the send's catch would mislabel as CORS — so a spec that
+ * declares a GET requestBody keeps its samples, but the live send drops it.
+ */
+const sendBody = (sample: RequestSample): string | FormData | undefined => {
+  if (sample.method === "GET" || sample.method === "HEAD") {
+    return undefined;
+  }
+  if (!sample.formData) {
+    return sample.body;
+  }
+  const form = new FormData();
+  for (const [name, value] of sample.formData) {
+    form.append(name, value);
+  }
+  return form;
+};
+
 /** A one-line text element for the response/error regions. */
 const line = (className: string, text: string): HTMLElement => {
   const el = document.createElement("div");
@@ -332,9 +392,11 @@ export const initPlayground = (root: HTMLElement): void => {
     }
     // An emptied editor means "no body" (see `bodyFor`), not invalid JSON —
     // reporting a syntax error there would block a send the request builder is
-    // perfectly happy to make.
+    // perfectly happy to make. A raw media type (`text/plain`, XML) isn't
+    // JSON at all, so it isn't checked as JSON either.
+    const raw = bodyEncoding(model.body?.contentType ?? "") === "raw";
     const errors =
-      bodyArea.value.trim() === ""
+      raw || bodyArea.value.trim() === ""
         ? []
         : validateJson(bodyArea.value, model.body?.schema);
     bodyErrors.textContent = "";
@@ -453,6 +515,11 @@ export const initPlayground = (root: HTMLElement): void => {
     if (!response || sending) {
       return;
     }
+    if (fetchRefusesMethod(model.method)) {
+      response.textContent = "";
+      response.append(line(ERROR_TEXT, TRACE_MESSAGE));
+      return;
+    }
     if (validateBody().length > 0) {
       return;
     }
@@ -494,11 +561,7 @@ export const initPlayground = (root: HTMLElement): void => {
           sample.url
         )}`
       : sample.url;
-    // A `Cookie` header can still arrive via a spec-declared header parameter;
-    // the browser would silently drop the forbidden name anyway, so strip it
-    // rather than earn a console warning.
-    const headers = { ...sample.headers };
-    delete headers.Cookie;
+    const headers = sendHeaders(sample, proxy);
     // fetch surfaces an invalid URL or header value as the same TypeError a
     // CORS rejection produces, and the catch below would misdiagnose it as the
     // CORS wall. Both are validated here, where the real error can be shown,
@@ -526,13 +589,7 @@ export const initPlayground = (root: HTMLElement): void => {
     const start = performance.now();
     try {
       const res = await fetch(url, {
-        // fetch throws a synchronous TypeError for a GET/HEAD with a body —
-        // which the catch below would mislabel as CORS. A spec that declares
-        // a GET requestBody keeps its samples, but the live send drops it.
-        body:
-          sample.method === "GET" || sample.method === "HEAD"
-            ? undefined
-            : sample.body,
+        body: sendBody(sample),
         headers,
         method: sample.method,
         // A `TimeoutError` DOMException is not a TypeError, so it reads as a

package/src/components/openapi/request.ts

@@ -1,3 +1,14 @@
+import {
+  defaultExplode,
+  defaultStyle,
+  isJsonObject,
+  memberText,
+  parseStyledValue,
+  queryPairs,
+  styledValue,
+  templateValue,
+} from "./param-style.ts";
+import type { JsonValue } from "./param-style.ts";
 import type { RequestSample } from "./snippets.ts";
 
 /**
@@ -10,7 +21,18 @@ import type { RequestSample } from "./snippets.ts";
  * byte-for-byte what gets sent.
  */
 
-export interface PlaygroundParam {
+/**
+ * How a parameter or form-body field serializes, as far as the spec says:
+ * the request builder applies the OpenAPI defaults for what it leaves out.
+ */
+export interface ParamSerialization {
+  /** The spec's `style`; else the location's default. */
+  style?: string;
+  /** The spec's `explode`; else the style's default. */
+  explode?: boolean;
+}
+
+export interface PlaygroundParam extends ParamSerialization {
   name: string;
   in: "path" | "query" | "header";
   required: boolean;
@@ -49,9 +71,14 @@ export interface PlaygroundBody {
   contentType: string;
   /** Present when the schema is a flat object of primitives -> typed fields UI. */
   fields?: PlaygroundBodyField[];
-  /** Pretty-printed example JSON prefill for the raw editor; "" when none. */
+  /**
+   * Prefill for the raw editor: pretty-printed example JSON, or a raw media
+   * type's (`text/plain`, XML) string example verbatim; "" when none.
+   */
   example: string;
   schema?: ValidationSchema;
+  /** A form-urlencoded body's per-field `encoding` (`style`/`explode`). */
+  encoding?: Record<string, ParamSerialization>;
 }
 
 export type AuthKind = "bearer" | "basic" | "apiKey" | "oauth2";
@@ -103,6 +130,38 @@ export interface RequestValues {
 export const paramKey = (p: { in: string; name: string }): string =>
   `${p.in}:${p.name}`;
 
+/**
+ * The request header a proxied send names the headers the playground set in,
+ * comma-separated. Blume's built-in proxy forwards those and nothing else, so
+ * credentials the browser attaches on its own — HTTP Basic auth for a docs
+ * site behind a password, platform headers added in front of the docs server
+ * — never reach the documented API.
+ */
+export const PROXY_HEADERS_HEADER = "X-Blume-Proxy-Headers";
+
+/**
+ * How a body's media type is put on the wire: JSON as the editor text,
+ * `application/x-www-form-urlencoded` as `name=value` pairs, and
+ * `multipart/form-data` as form parts — both from the editor's JSON object —
+ * and any other type (`text/plain`, XML) as the raw text.
+ */
+export type BodyEncoding = "json" | "form" | "multipart" | "raw";
+
+/** A `+json` suffix or a `json` subtype: `application/json`, `application/vnd.api+json`. */
+const JSON_MEDIA_TYPE = /[+/]json$/u;
+
+/** The {@link BodyEncoding} a body's media type (parameters ignored) takes. */
+export const bodyEncoding = (contentType: string): BodyEncoding => {
+  const type = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+  if (type === "application/x-www-form-urlencoded") {
+    return "form";
+  }
+  if (type === "multipart/form-data") {
+    return "multipart";
+  }
+  return JSON_MEDIA_TYPE.test(type) ? "json" : "raw";
+};
+
 /** Values pre-filled from the model's precomputed examples; auth entries empty. */
 export const defaultValues = (model: PlaygroundModel): RequestValues => ({
   auth: Object.fromEntries(
@@ -197,48 +256,119 @@ const applyAuth = (
   }
 };
 
-/** The raw editor text to send, with a parsed mirror when it is valid JSON. */
+/**
+ * A form-urlencoded body's `name=value` pairs: each field serialized like a
+ * query parameter, under the `encoding` the spec declares for it (`form`,
+ * exploded, by default — so a list repeats its name).
+ */
+const urlencodedBody = (
+  value: { [key: string]: JsonValue },
+  encoding: PlaygroundBody["encoding"]
+): string =>
+  Object.entries(value)
+    .flatMap(([name, member]) => {
+      const style = encoding?.[name]?.style ?? "form";
+      return queryPairs(
+        name,
+        styledValue(member),
+        style,
+        encoding?.[name]?.explode ?? defaultExplode(style)
+      );
+    })
+    .join("&");
+
+/** Multipart form parts in order: a list contributes one part per item. */
+const multipartParts = (value: {
+  [key: string]: JsonValue;
+}): [string, string][] =>
+  Object.entries(value).flatMap(([name, member]) =>
+    Array.isArray(member)
+      ? member.map((item): [string, string] => [name, memberText(item)])
+      : [[name, memberText(member)]]
+  );
+
+/**
+ * The editor text serialized for the body's media type, with a parsed mirror
+ * when it is valid JSON. A form body is built from the editor's JSON object;
+ * text that isn't one (mid-edit, or a raw media type) is sent as written.
+ */
 const bodyFor = (
+  body: PlaygroundBody,
   text: string | undefined
-): Pick<RequestSample, "body" | "bodyValue"> => {
+): Pick<RequestSample, "body" | "bodyValue" | "formData"> => {
   if (text === undefined || text === "") {
     return {};
   }
+  const encoding = bodyEncoding(body.contentType);
+  if (encoding === "raw") {
+    return { body: text };
+  }
+  let value: JsonValue;
   try {
-    return { body: text, bodyValue: JSON.parse(text) };
+    value = JSON.parse(text);
   } catch {
-    // Not valid JSON (mid-edit or intentionally raw): still send it — the
-    // structured mirror is only a nicety for consumers of `bodyValue`.
+    // Not valid JSON (mid-edit): still send it — the structured mirror is
+    // only a nicety for consumers of `bodyValue`.
     return { body: text };
   }
+  if (encoding === "json" || !isJsonObject(value)) {
+    return { body: text, bodyValue: value };
+  }
+  return encoding === "form"
+    ? { body: urlencodedBody(value, body.encoding), bodyValue: value }
+    : { bodyValue: value, formData: multipartParts(value) };
 };
 
-/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
-export const buildRequest = (
-  model: PlaygroundModel,
-  values: RequestValues
-): RequestSample => {
-  const base = values.server.replace(TRAILING_SLASH, "");
+/**
+ * A path or header parameter's value under its `style`: an array or object
+ * parameter's JSON text becomes `dog,cat` (simple), `.dog.cat` (label), or
+ * `;tags=dog;tags=cat` (matrix) rather than its JSON.
+ */
+const styledParam = (
+  param: PlaygroundParam,
+  value: string,
+  encode: (text: string) => string
+): string => {
+  const style = param.style ?? defaultStyle(param.in);
+  return templateValue(
+    param.name,
+    parseStyledValue(value, param.type),
+    style,
+    param.explode ?? defaultExplode(style),
+    encode
+  );
+};
 
-  // Path params: an empty value substitutes the raw param name, so a blank
-  // form still renders a readable templated URL instead of `//`.
-  let resolvedPath = model.path;
+/**
+ * The model's path with each `{param}` filled in. An empty value substitutes
+ * the raw param name, so a blank form still renders a readable templated URL
+ * instead of `//`.
+ */
+const resolvePath = (model: PlaygroundModel, values: RequestValues): string => {
+  let resolved = model.path;
   for (const param of model.params) {
     if (param.in !== "path") {
       continue;
     }
     const value = values.params[paramKey(param)] ?? "";
-    resolvedPath = resolvedPath.replace(
+    resolved = resolved.replace(
       `{${param.name}}`,
-      value === "" ? param.name : encodeURIComponent(value)
+      value === "" ? param.name : styledParam(param, value, encodeURIComponent)
     );
   }
+  return resolved;
+};
 
-  // Query params with a value contribute in model order; a query-borne auth
-  // credential appends after — unless the spec also declares that name as an
-  // explicit query parameter, whose (better) example wins.
+/**
+ * The query parameters' `name=value` pairs in model order, each name added to
+ * `seen` so a query-borne credential can defer to it.
+ */
+const queryParams = (
+  model: PlaygroundModel,
+  values: RequestValues,
+  seen: Set<string>
+): string[] => {
   const query: string[] = [];
-  const seen = new Set<string>();
   for (const param of model.params) {
     if (param.in !== "query") {
       continue;
@@ -251,10 +381,37 @@ export const buildRequest = (
       continue;
     }
     seen.add(param.name);
+    const style = param.style ?? defaultStyle(param.in);
     query.push(
-      `${encodeURIComponent(param.name)}=${encodeURIComponent(value)}`
+      ...queryPairs(
+        param.name,
+        parseStyledValue(value, param.type),
+        style,
+        param.explode ?? defaultExplode(style)
+      )
     );
   }
+  return query;
+};
+
+/** THE one request builder: samples, copy buttons, and fetch all consume its output. */
+export const buildRequest = (
+  model: PlaygroundModel,
+  values: RequestValues
+): RequestSample => {
+  // The server's trailing slash only goes when a path is joined onto it: a
+  // GraphQL endpoint (no path) is sent exactly as configured, and
+  // `https://host/graphql/` is not always the same route as `…/graphql`.
+  const base =
+    model.path === ""
+      ? values.server
+      : values.server.replace(TRAILING_SLASH, "");
+
+  // Query params with a value contribute in model order; a query-borne auth
+  // credential appends after — unless the spec also declares that name as an
+  // explicit query parameter, whose (better) example wins.
+  const seen = new Set<string>();
+  const query = queryParams(model, values, seen);
 
   // Auth first, so a spec that also declares the credential as an explicit
   // header parameter overrides it below with its own (better) example.
@@ -268,12 +425,18 @@ export const buildRequest = (
     // Required headers emit even when blank, mirroring the query rule above —
     // except a blank one never clobbers a credential auth already placed
     // under the same name.
-    if (value !== "" || (param.required && headers[param.name] === undefined)) {
+    if (value !== "") {
+      headers[param.name] = styledParam(param, value, (text) => text);
+    } else if (param.required && headers[param.name] === undefined) {
       headers[param.name] = value;
     }
   }
 
-  const { body, bodyValue } = model.body ? bodyFor(values.body) : {};
+  const { body, bodyValue, formData } = model.body
+    ? bodyFor(model.body, values.body)
+    : {};
+  // Multipart parts carry no Content-Type here: the client (curl, fetch,
+  // requests) writes it along with the boundary that separates the parts.
   if (body !== undefined && model.body) {
     headers["Content-Type"] = model.body.contentType;
   }
@@ -282,8 +445,9 @@ export const buildRequest = (
   return {
     body,
     bodyValue,
+    formData,
     headers,
     method: model.method.toUpperCase(),
-    url: `${base}${resolvedPath}${search}`,
+    url: `${base}${resolvePath(model, values)}${search}`,
   };
 };

package/src/components/openapi/schema-tree.ts

@@ -55,6 +55,11 @@ export type SchemaNode =
       kind: "branches";
       label: "One of" | "Any of";
       branches: { label: string; slot: SchemaSlot }[];
+      /**
+       * Properties the schema declares beside its `oneOf`/`anyOf`, which
+       * every variant shares; absent when it declares none.
+       */
+      rows?: SchemaRow[];
     }
   | { kind: "properties"; rows: SchemaRow[] }
   | { kind: "type"; label: string };
@@ -125,19 +130,6 @@ export const schemaTree = (
           : { itemsLabel: typeLabel({}), kind: "array" },
       };
     }
-    const branches = schema.oneOf ?? schema.anyOf;
-    if (branches) {
-      return {
-        node: {
-          branches: branches.map((branch, index) => ({
-            label: typeLabel(branch) || `Option ${index + 1}`,
-            slot: table(branch, ancestors),
-          })),
-          kind: "branches",
-          label: schema.oneOf ? "One of" : "Any of",
-        },
-      };
-    }
     // A row discloses nested structure — never a model inside itself.
     const rowChildren = (property: SchemaLike): SchemaSlot | undefined => {
       if (
@@ -155,18 +147,32 @@ export const schemaTree = (
         : undefined;
     };
     const { properties, required } = objectProperties(schema, schemas);
-    if (properties.length > 0) {
-      return {
-        node: {
-          kind: "properties",
-          rows: properties.map(([name, property]) => ({
-            children: rowChildren(property),
-            name,
-            required: required.has(name),
-            schema: property,
-          })),
-        },
+    const rows: SchemaRow[] = properties.map(([name, property]) => ({
+      children: rowChildren(property),
+      name,
+      required: required.has(name),
+      schema: property,
+    }));
+    // Shared properties beside a `oneOf`/`anyOf` (`amount` and `currency`
+    // next to `Card | BankAccount`) render above the variants, planned first
+    // as they read first.
+    const branches = schema.oneOf ?? schema.anyOf;
+    if (branches) {
+      const node: Extract<SchemaNode, { kind: "branches" }> = {
+        branches: branches.map((branch, index) => ({
+          label: typeLabel(branch) || `Option ${index + 1}`,
+          slot: table(branch, ancestors),
+        })),
+        kind: "branches",
+        label: schema.oneOf ? "One of" : "Any of",
       };
+      if (rows.length > 0) {
+        node.rows = rows;
+      }
+      return { node };
+    }
+    if (rows.length > 0) {
+      return { node: { kind: "properties", rows } };
     }
     return { node: { kind: "type", label: typeLabel(schema) } };
   };

package/src/components/openapi/security.ts

@@ -45,12 +45,15 @@ export interface OperationSecurity {
 /**
  * The requirement list an operation actually enforces: its own `security` when
  * declared — the OpenAPI override rule, where `[]` removes the default and
- * makes the operation public — else the document's root `security`.
+ * makes the operation public — else the document's root `security`. A webhook
+ * takes only its own: the API sends it, so the root requirements, which guard
+ * calls to the API, say nothing about what the receiving endpoint checks.
  */
 export const effectiveSecurity = (
   operation?: SecurityRequirementLike[],
-  document?: SecurityRequirementLike[]
-): SecurityRequirementLike[] => operation ?? document ?? [];
+  document?: SecurityRequirementLike[],
+  webhook = false
+): SecurityRequirementLike[] => operation ?? (webhook ? [] : document) ?? [];
 
 /**
  * Resolve requirement names against `components.securitySchemes`. A name with