blume 1.5.0 → 1.5.2

package/src/components/openapi/message-model.ts

@@ -0,0 +1,108 @@
+import type {
+  AsyncApiAction,
+  AsyncApiServerObject,
+} from "../../openapi/asyncapi.ts";
+import type { AsyncApiMessageLike, NamedMessage } from "./async.ts";
+import { payloadSchema } from "./async.ts";
+import { exampleValue, toJson } from "./helpers.ts";
+import type { ParameterLike, SchemaLike } from "./helpers.ts";
+import type {
+  MessageModel,
+  MessageParam,
+  MessagePayload,
+  MessageServerOption,
+} from "./message.ts";
+import { inputValue, validationSchema } from "./playground-schema.ts";
+
+/**
+ * Server-side derivation of the event composer's message model — the AsyncAPI
+ * counterpart of `operation-model.ts`. The spec document, the sampler, and the
+ * channel/server resolution meet here once at build time; the resulting
+ * {@link MessageModel} is embedded as JSON on the operation page so the lazy
+ * client chunk carries none of it.
+ */
+
+/** The protocols a docs page can actually open a live connection to. */
+const LIVE_PROTOCOLS = { ws: true } satisfies Record<string, true>;
+
+/**
+ * Channel parameters as composer inputs. `channelParameters` has already
+ * lowered AsyncAPI's string-only parameters (enum, default, examples) into the
+ * shared parameter shape, so all that is left is picking a prefill: the
+ * declared default, first example, or first enum member, else nothing. Never
+ * the sampler — its `{type:"string"}` output is the literal word `string`,
+ * which would replace every `{name}` template in the address samples with
+ * junk like `user/string/signedup`.
+ */
+const messageParams = (parameters: ParameterLike[]): MessageParam[] =>
+  parameters.map((parameter) => ({
+    description: parameter.description,
+    enum: parameter.schema?.enum?.map(String),
+    name: parameter.name ?? "",
+    value: inputValue(
+      parameter.schema?.default ??
+        parameter.example ??
+        parameter.schema?.enum?.[0]
+    ),
+  }));
+
+/**
+ * The payload editor's state for the operation's first message. Multi-message
+ * operations render every message's schema on the page, but the composer sends
+ * one payload — the first is the one the samples already show.
+ */
+const messagePayload = (
+  message: AsyncApiMessageLike | undefined,
+  schemas: Record<string, SchemaLike>
+): MessagePayload => {
+  if (!message) {
+    return { example: "" };
+  }
+  const schema = payloadSchema(message);
+  // `undefined` means the message declares no example, `null` means it declares
+  // an empty one — only the former falls back to a schema sample. The sampler's
+  // own `null` is its no-schema/failure sentinel, not a value a reader typed:
+  // it degrades to an empty editor (which samples and sends `{}`) rather than
+  // prefilling the literal `null`.
+  const declared = message.examples?.[0]?.payload;
+  const example =
+    declared === undefined ? exampleValue(schema, schemas) : declared;
+  return {
+    contentType: message.contentType,
+    example:
+      declared === undefined && example === null ? "" : (toJson(example) ?? ""),
+    schema: validationSchema(schema, schemas),
+  };
+};
+
+/**
+ * A server's base URL for the picker. Falls back to the bare host when the
+ * spec omits `protocol` — a label is a label, and the snippet builders read
+ * the server object itself rather than this string.
+ */
+const serverOption = (server: AsyncApiServerObject): MessageServerOption => {
+  const host = `${server.host ?? ""}${server.pathname ?? ""}`;
+  return {
+    label: server.protocol ? `${server.protocol}://${host}` : host,
+    server,
+  };
+};
+
+/** Derive the composer's message model for one event operation, at build time. */
+export const messageModel = (args: {
+  action: AsyncApiAction;
+  address: string;
+  messages: NamedMessage[];
+  parameters: ParameterLike[];
+  protocol?: string;
+  schemas: Record<string, SchemaLike>;
+  servers: AsyncApiServerObject[];
+}): MessageModel => ({
+  action: args.action,
+  address: args.address,
+  connectable: Object.hasOwn(LIVE_PROTOCOLS, args.protocol ?? ""),
+  params: messageParams(args.parameters),
+  payload: messagePayload(args.messages[0]?.message, args.schemas),
+  protocol: args.protocol,
+  servers: args.servers.map(serverOption),
+});

package/src/components/openapi/message.ts

@@ -0,0 +1,153 @@
+import type {
+  AsyncApiAction,
+  AsyncApiServerObject,
+} from "../../openapi/asyncapi.ts";
+import type { MessageSample } from "./async-snippets.ts";
+import type { ValidationSchema } from "./request.ts";
+
+/**
+ * Framework-free message model for the event ("Try it") composer — the
+ * AsyncAPI counterpart of `request.ts`. The composer form, the protocol-aware
+ * code samples, and the live WebSocket frame all derive from one
+ * {@link buildMessage} call, so a copied `wscat` command and a composed send
+ * carry the same address and the same payload bytes by construction.
+ *
+ * Ships to the browser inside the composer's lazy chunk: no spec parser, no
+ * sampler, no Astro imports.
+ */
+
+/** One channel parameter as a composer input. Channel params are always required. */
+export interface MessageParam {
+  description?: string;
+  /** Declared `enum` members, when the parameter constrains its values. */
+  enum?: string[];
+  name: string;
+  /** Prefill from the parameter's `default`/`examples`; "" when none. */
+  value: string;
+}
+
+/** The composer's payload editor state. */
+export interface MessagePayload {
+  /** The message's declared `contentType`, when it has one. */
+  contentType?: string;
+  /** Pretty-printed prefill: declared example, else a schema sample; "" when none. */
+  example: string;
+  /** Pruned payload schema the editor validates against, when derivable. */
+  schema?: ValidationSchema;
+}
+
+/** One server option in the picker: a display URL plus the spec object behind it. */
+export interface MessageServerOption {
+  /** `protocol://host+pathname` — what the reader picks between. */
+  label: string;
+  /** The spec server, verbatim; the snippet builders read host/pathname/protocol. */
+  server: AsyncApiServerObject;
+}
+
+export interface MessageModel {
+  action: AsyncApiAction;
+  /** Channel address with `{param}` templates intact, e.g. `user/{id}/signedup`. */
+  address: string;
+  /**
+   * Whether the panel offers a live connection. Only WebSocket bindings can be
+   * driven from a docs page — Kafka, MQTT and friends get the composer and the
+   * CLI samples rather than faked connectivity.
+   */
+  connectable: boolean;
+  params: MessageParam[];
+  payload: MessagePayload;
+  /** Normalized binding key (`ws`, `kafka`, `mqtt`, …) when the spec implies one. */
+  protocol?: string;
+  servers: MessageServerOption[];
+}
+
+export interface MessageValues {
+  /** Free-text server URL; overrides the picked server when non-empty. */
+  customUrl: string;
+  /** Key: parameter name. */
+  params: Record<string, string>;
+  /** Raw payload editor text. */
+  payload: string;
+  /** Index into `model.servers`; out of range falls back to the first. */
+  server: number;
+}
+
+/** Values pre-filled from the model's precomputed examples. */
+export const defaultMessageValues = (model: MessageModel): MessageValues => ({
+  customUrl: "",
+  params: Object.fromEntries(
+    model.params.map((param) => [param.name, param.value])
+  ),
+  payload: model.payload.example,
+  server: 0,
+});
+
+const PARAM_TEMPLATE = /\{(?<name>[^{}]+)\}/gu;
+
+/**
+ * A free-text base URL lowered onto the server shape the snippet builders and
+ * the connect URL read. A full URL contributes its scheme, host, and path.
+ * Anything without an authority — a bare `host:port`, which is how broker
+ * tooling is usually addressed, and which `new URL` happily reads as a scheme
+ * plus path — is kept whole as the host, leaving the protocol to the spec.
+ */
+const customServer = (url: string): AsyncApiServerObject => {
+  let parsed: URL | undefined;
+  try {
+    parsed = new URL(url);
+  } catch {
+    parsed = undefined;
+  }
+  if (!parsed || parsed.host === "") {
+    return { host: url };
+  }
+  return {
+    host: parsed.host,
+    pathname: parsed.pathname === "/" ? "" : parsed.pathname,
+    protocol: parsed.protocol.replace(":", ""),
+  };
+};
+
+/**
+ * THE one message builder: the composer's samples, its copy buttons, and the
+ * live WebSocket frame all consume its output. Parameter values are
+ * URL-encoded into the address; a parameter left blank keeps its `{name}`
+ * template so the sample still reads as a template rather than a broken
+ * address. Payload text that doesn't parse yields no payload — the editor is
+ * showing the reader a validation error at that moment, and neither a sample
+ * nor a send should invent a value.
+ */
+export const buildMessage = (
+  model: MessageModel,
+  values: MessageValues
+): MessageSample => {
+  const custom = values.customUrl.trim();
+  const picked = model.servers[values.server] ?? model.servers[0];
+  let payload: unknown;
+  try {
+    // SAFETY: JSON.parse returns `any`; widening it to `unknown` claims
+    // nothing about the shape and forces consumers to narrow.
+    payload = JSON.parse(values.payload) as unknown;
+  } catch {
+    payload = undefined;
+  }
+  return {
+    action: model.action,
+    address: model.address.replaceAll(PARAM_TEMPLATE, (template, name) => {
+      const value = values.params[String(name)] ?? "";
+      return value === "" ? template : encodeURIComponent(value);
+    }),
+    payload,
+    server: custom === "" ? picked?.server : customServer(custom),
+  };
+};
+
+/**
+ * The exact bytes a live send transmits. Identical to the payload the `wscat`
+ * and browser-`WebSocket` samples embed, which is the whole point: what a
+ * reader copies is what Send puts on the wire. Only an absent payload
+ * (unparseable editor text) degrades to `{}` — a `null` payload is a value the
+ * reader typed, so it goes out as `null`.
+ */
+export const messageFrame = (sample: MessageSample): string =>
+  JSON.stringify(sample.payload === undefined ? {} : sample.payload);

package/src/components/openapi/operation-model.ts

@@ -0,0 +1,260 @@
+import {
+  exampleValue,
+  objectProperties,
+  resolveSchema,
+  toJson,
+} from "./helpers.ts";
+import type { ParameterLike, SchemaLike, SpecValue } from "./helpers.ts";
+import {
+  declaredTypes,
+  inputValue,
+  scalarType,
+  validationSchema,
+} from "./playground-schema.ts";
+import type {
+  PlaygroundAuthInput,
+  PlaygroundBody,
+  PlaygroundBodyField,
+  PlaygroundModel,
+  PlaygroundParam,
+} from "./request.ts";
+import { schemeLabel } from "./security.ts";
+import type { OperationSecurity, ResolvedScheme } from "./security.ts";
+
+/**
+ * Server-side derivation of the playground's request model. This is where the
+ * spec document, openapi-sampler, and the security resolution meet — once, at
+ * build time. The resulting `PlaygroundModel` is embedded as JSON on the page,
+ * so the client (`request.ts`) never needs any of those dependencies.
+ */
+
+interface MediaTypeLike {
+  schema?: SchemaLike;
+  example?: unknown;
+}
+
+/** Primitive types the flat-body fields UI can edit directly. */
+const PRIMITIVE_TYPES = {
+  boolean: true,
+  integer: true,
+  number: true,
+  string: true,
+} as const;
+
+/** Whether a spec example is a plain object usable for per-field defaults. */
+const isExampleObject = (
+  value: SpecValue
+): value is Record<string, SpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Playground inputs for the operation's parameters. Cookie params are skipped
+ * (not supported in v1 — browsers won't let a page set arbitrary cookies).
+ * Path params are always required per spec, even when a lax document omits the
+ * flag. Only REQUIRED params get a precomputed example; optional ones default
+ * to "" so the default samples carry required params only — parity with the
+ * old static samples.
+ */
+const modelParams = (
+  parameters: ParameterLike[],
+  schemas: Record<string, SchemaLike>
+): PlaygroundParam[] => {
+  const params: PlaygroundParam[] = [];
+  for (const param of parameters) {
+    const where = param.in;
+    if (
+      !param.name ||
+      (where !== "path" && where !== "query" && where !== "header")
+    ) {
+      continue;
+    }
+    const required = where === "path" ? true : param.required === true;
+    const schema = resolveSchema(schemas, param.schema);
+    params.push({
+      description: param.description,
+      enum: schema.enum?.map(String),
+      in: where,
+      name: param.name,
+      required,
+      type: scalarType(param.schema, schemas),
+      value: required
+        ? inputValue(param.example ?? exampleValue(param.schema, schemas))
+        : "",
+    });
+  }
+  return params;
+};
+
+/** The JSON-ish media entry: first whose type mentions json, else the first. */
+const jsonContentType = (
+  content: Record<string, MediaTypeLike> | undefined
+): [string, MediaTypeLike] | undefined => {
+  const entries = Object.entries(content ?? {});
+  return entries.find(([type]) => type.includes("json")) ?? entries[0];
+};
+
+/**
+ * Typed field inputs when the body schema is a flat object of primitives —
+ * anything nested (object/array properties) falls back to the raw JSON editor,
+ * where structure is easier to edit than in exploded form fields.
+ */
+const bodyFields = (
+  schema: SchemaLike | undefined,
+  schemas: Record<string, SchemaLike>,
+  example: SpecValue
+): PlaygroundBodyField[] | undefined => {
+  const resolved = resolveSchema(schemas, schema);
+  if (declaredTypes(resolved.type).some((type) => type !== "object")) {
+    return undefined;
+  }
+  const { properties, required } = objectProperties(resolved, schemas);
+  if (properties.length === 0) {
+    return undefined;
+  }
+  const defaults = isExampleObject(example) ? example : undefined;
+  const fields: PlaygroundBodyField[] = [];
+  for (const [name, property] of properties) {
+    const propertySchema = resolveSchema(schemas, property);
+    const type = scalarType(property, schemas);
+    if (
+      !(type in PRIMITIVE_TYPES) ||
+      propertySchema.properties ||
+      propertySchema.items
+    ) {
+      return undefined;
+    }
+    fields.push({
+      description: propertySchema.description,
+      enum: propertySchema.enum?.map(String),
+      name,
+      required: required.has(name),
+      type,
+      value: inputValue(defaults?.[name]),
+    });
+  }
+  return fields;
+};
+
+/** The playground's body editor state, when the operation takes a request body. */
+const modelBody = (
+  requestBody: { content?: Record<string, MediaTypeLike> } | undefined,
+  schemas: Record<string, SchemaLike>
+): PlaygroundBody | undefined => {
+  const media = jsonContentType(requestBody?.content);
+  if (!media) {
+    return undefined;
+  }
+  const [contentType, mediaType] = media;
+  // SAFETY: `example` comes from the parsed spec document (YAML/JSON), whose
+  // values are exactly the JSON-shaped tree `SpecValue` models.
+  const exampleData =
+    (mediaType.example as SpecValue) ?? exampleValue(mediaType.schema, schemas);
+  return {
+    contentType,
+    example: toJson(exampleData) ?? "",
+    fields: bodyFields(mediaType.schema, schemas, exampleData),
+    schema: validationSchema(mediaType.schema, schemas),
+  };
+};
+
+const AUTHORIZATION_HEADER = { in: "header", name: "Authorization" } as const;
+
+/**
+ * One resolved security scheme -> the playground input that collects its
+ * credential. Mutual TLS travels outside the request and an unknown ref can't
+ * be guessed — both contribute nothing.
+ */
+const authInput = (
+  resolved: ResolvedScheme
+): PlaygroundAuthInput | undefined => {
+  const { scheme } = resolved;
+  const label = schemeLabel(resolved);
+  switch (scheme?.type) {
+    case "http": {
+      const kind = (scheme.scheme ?? "bearer").toLowerCase();
+      if (kind === "basic") {
+        return {
+          carrier: AUTHORIZATION_HEADER,
+          id: resolved.key,
+          kind: "basic",
+          label,
+          placeholder: "YOUR_CREDENTIALS",
+          prefix: "Basic ",
+        };
+      }
+      if (kind === "bearer") {
+        return {
+          carrier: AUTHORIZATION_HEADER,
+          id: resolved.key,
+          kind: "bearer",
+          label,
+          placeholder: "YOUR_TOKEN",
+          prefix: "Bearer ",
+        };
+      }
+      // Digest and friends: a paste field like bearer, scheme-name prefix.
+      return {
+        carrier: AUTHORIZATION_HEADER,
+        id: resolved.key,
+        kind: "bearer",
+        label,
+        placeholder: "YOUR_CREDENTIALS",
+        prefix: `${kind.charAt(0).toUpperCase() + kind.slice(1)} `,
+      };
+    }
+    case "oauth2":
+    case "openIdConnect": {
+      // Token paste, no flow — the playground doesn't run OAuth dances.
+      return {
+        carrier: AUTHORIZATION_HEADER,
+        id: resolved.key,
+        kind: "oauth2",
+        label,
+        placeholder: "YOUR_ACCESS_TOKEN",
+        prefix: "Bearer ",
+      };
+    }
+    case "apiKey": {
+      const where = scheme.in;
+      return {
+        carrier: {
+          in: where === "query" || where === "cookie" ? where : "header",
+          name: scheme.name ?? resolved.key,
+        },
+        id: resolved.key,
+        kind: "apiKey",
+        label,
+        placeholder: "YOUR_API_KEY",
+        prefix: "",
+      };
+    }
+    default: {
+      return undefined;
+    }
+  }
+};
+
+/** Derive the playground request model for one operation, at build time. */
+export const operationModel = (args: {
+  method: string;
+  path: string;
+  /** Pre-merged/resolved (`mergeParameters` output). */
+  parameters: ParameterLike[];
+  requestBody?: { content?: Record<string, MediaTypeLike> };
+  servers: { url?: string }[];
+  schemas: Record<string, SchemaLike>;
+  security: OperationSecurity;
+}): PlaygroundModel => ({
+  // First alternative only — the spec's preferred way to authorize, matching
+  // what the static samples always showed.
+  auth: (args.security.alternatives[0] ?? []).flatMap((resolved) => {
+    const input = authInput(resolved);
+    return input ? [input] : [];
+  }),
+  authOptional: args.security.optional,
+  body: modelBody(args.requestBody, args.schemas),
+  method: args.method.toUpperCase(),
+  params: modelParams(args.parameters, args.schemas),
+  path: args.path,
+  servers: args.servers.map((server) => server.url ?? ""),
+});