blume 2.0.3 → 2.1.1

package/src/components/openapi/ParametersTable.astro

@@ -2,6 +2,7 @@
 import Description from "./Description.astro";
 import {
   constraints,
+  parameterDescription,
   resolveSchema,
   type SchemaLike,
   typeLabel,
@@ -19,9 +20,11 @@ interface ParamLike {
 interface Props {
   parameters: ParamLike[];
   schemas: Record<string, SchemaLike>;
+  /** The headings' level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { parameters, schemas } = Astro.props;
+const { parameters, schemas, level = 2 } = Astro.props;
 
 const SECTIONS: { in: string; title: string }[] = [
   { in: "path", title: "Path parameters" },
@@ -42,7 +45,7 @@ const groups = SECTIONS.map((section) => ({
   groups.map((group) => (
     <section class="mt-6">
       <div
-        aria-level="2"
+        aria-level={level}
         class="mb-2 font-semibold text-foreground text-sm"
         role="heading"
       >
@@ -54,6 +57,7 @@ const groups = SECTIONS.map((section) => ({
           const type = param.schema ? typeLabel(param.schema) : "string";
           const limits = constraints(resolved);
           const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
+          const description = parameterDescription(param, schemas);
           return (
             <div class="border-border border-t py-4 first:border-t-0">
               <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
@@ -70,8 +74,8 @@ const groups = SECTIONS.map((section) => ({
                   </span>
                 )}
               </div>
-              {param.description && (
-                <Description class="mt-2 text-muted-foreground text-sm" text={param.description} />
+              {description && (
+                <Description class="mt-2 text-muted-foreground text-sm" text={description} />
               )}
               {limits.length > 0 && (
                 <div class="mt-2 text-muted-foreground text-xs">

package/src/components/openapi/Playground.astro

@@ -17,12 +17,17 @@ interface Props {
   model: PlaygroundModel;
   /** Proxy route for the send, or false to fetch the API directly. */
   proxy: string | false;
+  /**
+   * Where this panel's proxy is configured, which the CORS message names:
+   * an `openapi()` or `graphql()` reference, or `api` for hand-written pages.
+   */
+  proxyConfig: "api" | "graphql" | "openapi";
   /** Spec slug + operation key form the per-operation localStorage key. */
   slug: string;
   operation: string;
 }
 
-const { model, proxy, slug, operation } = Astro.props;
+const { model, proxy, proxyConfig, slug, operation } = Astro.props;
 
 // The built-in proxy route carries the site `basePath` but, like every
 // internal URL in the spec data, not `deployment.base`; `withMountedBase`
@@ -53,6 +58,7 @@ const CHECKBOX_ROW =
 <blume-playground
   class="mb-6 block"
   data-proxy={proxyUrl}
+  data-proxy-config={proxyConfig}
   data-storage-key={`blume-playground:${slug}:${operation}`}
 >
   <script

package/src/components/openapi/RequestBody.astro

@@ -1,6 +1,7 @@
 ---
 import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
+import type { SchemaDirection } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
 interface MediaTypeLike {
@@ -17,9 +18,22 @@ interface Props {
   requestBody: RequestBodyLike;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
+  /**
+   * `request` (the default) leaves out `readOnly` fields; a webhook or
+   * callback, which the API sends, reads like a response instead.
+   */
+  direction?: SchemaDirection;
 }
 
-const { requestBody, schemas, expandAll = false } = Astro.props;
+const {
+  requestBody,
+  schemas,
+  expandAll = false,
+  level = 2,
+  direction = "request",
+} = Astro.props;
 
 const entries = Object.entries(requestBody.content ?? {});
 const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
@@ -27,11 +41,11 @@ const contentType = chosen?.[0] ?? "application/json";
 const schema = chosen?.[1]?.schema ?? {};
 ---
 
-<section class="mt-8">
+<section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
   <div class="mb-2 flex flex-wrap items-center gap-2">
     <div
-      aria-level="2"
-      class="font-semibold text-foreground text-lg"
+      aria-level={level}
+      class:list={["font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
       role="heading"
     >
       Request body
@@ -51,6 +65,11 @@ const schema = chosen?.[1]?.schema ?? {};
     )
   }
   <div class="mt-3">
-    <SchemaTable expandAll={expandAll} schema={schema} schemas={schemas} />
+    <SchemaTable
+      direction={direction}
+      expandAll={expandAll}
+      schema={schema}
+      schemas={schemas}
+    />
   </div>
 </section>

package/src/components/openapi/RequestPanel.astro

@@ -9,6 +9,7 @@ import {
   type SpecValue,
   toJson,
 } from "./helpers.ts";
+import type { CustomCodeSample } from "./code-samples.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import PanelTabs from "./PanelTabs.astro";
 import type { RequestSample, SampleLanguage } from "./snippets.ts";
@@ -27,19 +28,69 @@ interface ResponseLike {
 interface Props {
   /** The document's `components`, which `$ref`'d examples resolve against. */
   components?: ComponentsLike;
-  sample: RequestSample;
-  languages: SampleLanguage[];
+  /** The spec's hand-written `x-codeSamples`, shown first and never re-rendered live. */
+  customSamples?: CustomCodeSample[];
+  /**
+   * A webhook's body: the rail shows it as a "Payload" example per media
+   * type in place of client code, since the API sends the request.
+   */
+  payload?: Record<string, MediaTypeLike>;
+  sample?: RequestSample;
+  languages?: SampleLanguage[];
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
 }
 
-const { components, sample, languages, responses, schemas } = Astro.props;
-
-const requestPanels = await languageSamplePanels(
-  languages,
+const {
+  components,
+  customSamples = [],
+  payload,
   sample,
-  data.config.codeThemes
+  languages = [],
+  responses,
+  schemas,
+} = Astro.props;
+
+/** A media type's example, highlighted, or null when it has none. */
+const highlightExample = async (media: MediaTypeLike, type: string) => {
+  const example = responseExample(media, schemas, components);
+  if (example === undefined || example === null) {
+    return null;
+  }
+  const json = type.includes("json");
+  return highlightCode(
+    json || typeof example !== "string" ? toJson(example) : example,
+    json ? "json" : "text",
+    { icons: false, themes: data.config.codeThemes }
+  );
+};
+
+// Hand-written samples carry no `lang` key, so the playground leaves them
+// as written when it re-renders the generated ones from the form.
+const customPanels = await Promise.all(
+  customSamples.map(async (custom) => ({
+    html: await highlightCode(custom.source, custom.lang, {
+      icons: false,
+      themes: data.config.codeThemes,
+    }),
+    key: custom.key,
+    label: custom.label,
+  }))
+);
+const payloadPanels = await Promise.all(
+  Object.entries(payload ?? {}).map(async ([type, media]) => ({
+    html: await highlightExample(media, type),
+    key: type,
+    label: type,
+    text: "No example payload.",
+  }))
 );
+const requestPanels = [
+  ...customPanels,
+  ...(sample
+    ? await languageSamplePanels(languages, sample, data.config.codeThemes)
+    : []),
+];
 
 const responsePanels = await Promise.all(
   Object.entries(responses).map(async ([status, response]) => {
@@ -66,6 +117,7 @@ const responsePanels = await Promise.all(
 ---
 
 <div class="not-prose flex flex-col gap-6">
+  <PanelTabs copy heading="Payload" mono panels={payloadPanels} />
   <PanelTabs copy heading="Request" panels={requestPanels} />
   <PanelTabs heading="Response" mono panels={responsePanels} />
 </div>

package/src/components/openapi/Responses.astro

@@ -17,19 +17,21 @@ interface Props {
   responses: Record<string, ResponseLike>;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** The heading's level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { responses, schemas, expandAll = false } = Astro.props;
+const { responses, schemas, expandAll = false, level = 2 } = Astro.props;
 
 const items = Object.entries(responses);
 ---
 
 {
   items.length > 0 && (
-    <section class="mt-8">
+    <section class:list={[level > 2 ? "mt-5" : "mt-8"]}>
       <div
-        aria-level="2"
-        class="mb-3 font-semibold text-foreground text-lg"
+        aria-level={level}
+        class:list={["mb-3 font-semibold text-foreground", level > 2 ? "text-sm" : "text-lg"]}
         role="heading"
       >
         Responses
@@ -62,6 +64,7 @@ const items = Object.entries(responses);
               {schema && (
                 <div class="mt-3">
                   <SchemaTable
+                    direction="response"
                     expandAll={expandAll}
                     schema={schema}
                     schemas={schemas}

package/src/components/openapi/SchemaTable.astro

@@ -1,6 +1,10 @@
 ---
 import type { SchemaLike } from "./helpers.ts";
-import { type SchemaNode, schemaTree } from "./schema-tree.ts";
+import {
+  type SchemaDirection,
+  type SchemaNode,
+  schemaTree,
+} from "./schema-tree.ts";
 import SchemaProperty from "./SchemaProperty.astro";
 
 interface Props {
@@ -10,13 +14,21 @@ interface Props {
   node?: SchemaNode;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** Which way the data travels, which decides the fields left out. */
+  direction?: SchemaDirection;
 }
 
-const { schema = {}, node: planned, schemas, expandAll = false } = Astro.props;
+const {
+  schema = {},
+  node: planned,
+  schemas,
+  expandAll = false,
+  direction,
+} = Astro.props;
 
 // The whole tree is planned once, at the top-level table, so that which named
 // schemas expand is decided for the tree as a whole (see `schema-tree.ts`).
-const node = planned ?? schemaTree(schema, schemas);
+const node = planned ?? schemaTree(schema, schemas, direction);
 ---
 
 {

package/src/components/openapi/async-snippets.ts

@@ -25,7 +25,12 @@ export interface MessageSample {
   address: string;
   /** Example payload value (undefined when none could be derived). */
   payload?: unknown;
-  /** First server the channel is available on, if any. */
+  /** Example Kafka message key, when the message's binding declares one. */
+  key?: string;
+  /**
+   * First server the channel is available on, if any, its `security` entries
+   * resolved to scheme objects.
+   */
   server?: AsyncApiServerObject;
 }
 
@@ -98,12 +103,63 @@ const webSocketSnippet = (sample: MessageSample): string => {
   ].join("\n");
 };
 
+/** librdkafka's `sasl.mechanisms` value for each AsyncAPI SASL scheme type. */
+const SASL_MECHANISMS = new Map([
+  ["gssapi", "GSSAPI"],
+  ["plain", "PLAIN"],
+  ["scramSha256", "SCRAM-SHA-256"],
+  ["scramSha512", "SCRAM-SHA-512"],
+]);
+
+/**
+ * The `-X` properties kcat hands librdkafka to reach the server: TLS for
+ * `kafka-secure`, and the first SASL scheme the server declares, with its
+ * credentials read from the environment (Kerberos brings its own).
+ */
+const kafkaSecurityFlags = (server?: AsyncApiServerObject): string[] => {
+  const tls = server?.protocol?.toLowerCase() === "kafka-secure";
+  const mechanism = (server?.security ?? [])
+    .map((entry) => SASL_MECHANISMS.get(String(entry?.type)))
+    .find((value) => value !== undefined);
+  if (mechanism === undefined) {
+    return tls ? ["-X security.protocol=SSL"] : [];
+  }
+  const flags = [
+    `-X security.protocol=${tls ? "SASL_SSL" : "SASL_PLAINTEXT"}`,
+    `-X sasl.mechanisms=${mechanism}`,
+  ];
+  if (mechanism !== "GSSAPI") {
+    flags.push(
+      '-X sasl.username="$KAFKA_USERNAME"',
+      '-X sasl.password="$KAFKA_PASSWORD"'
+    );
+  }
+  return flags;
+};
+
+/**
+ * The separator between key and value: kcat splits each produced line at its
+ * first `|`, and prints consumed keys before one.
+ */
+const KEY_DELIMITER = "|";
+
 const kcatSnippet = (sample: MessageSample): string => {
   const broker = sample.server?.host ?? "localhost:9092";
-  const base = `kcat -b ${shellQuote(broker)} -t ${shellQuote(sample.address)}`;
-  return sample.action === "receive"
-    ? `echo ${shellQuote(payloadInline(sample))} | ${base} -P`
-    : `${base} -C`;
+  const mode = sample.action === "receive" ? "-P" : "-C";
+  const keyed =
+    sample.key === undefined ? "" : ` -K ${shellQuote(KEY_DELIMITER)}`;
+  const command = [
+    `kcat -b ${shellQuote(broker)} -t ${shellQuote(sample.address)} ${mode}${keyed}`,
+    ...kafkaSecurityFlags(sample.server),
+  ].join(" \\\n  ");
+  if (sample.action !== "receive") {
+    return command;
+  }
+  const line =
+    sample.key === undefined
+      ? payloadInline(sample)
+      : `${sample.key}${KEY_DELIMITER}${payloadInline(sample)}`;
+  return `echo ${shellQuote(line)} | ${command}`;
 };
 
 const mosquittoSnippet = (sample: MessageSample): string => {
@@ -157,15 +213,15 @@ const ALIASES = new Map<string, ToolId>([
 /**
  * The sample tools to render for an operation. The protocol picks the
  * candidate set; a non-empty `codeSamples` config filters and orders it
- * (unknown ids are dropped, aliases accepted). No protocol, an unsupported
- * one, or a filter that matches nothing yields no samples.
+ * (unknown ids are dropped, aliases accepted). `false`, no protocol, an
+ * unsupported one, or a filter that matches nothing yields no samples.
  */
 export const asyncSampleLanguages = (
-  ids: string[],
+  ids: string[] | false,
   protocol?: string
 ): AsyncSampleLanguage[] => {
   const candidates = PROTOCOL_TOOLS.get(protocol ?? "") ?? [];
-  if (candidates.length === 0) {
+  if (ids === false || candidates.length === 0) {
     return [];
   }
   if (ids.length === 0) {

package/src/components/openapi/async.ts

@@ -8,6 +8,8 @@ import type {
 } from "../../openapi/asyncapi.ts";
 import type { ParameterLike, SchemaLike } from "./helpers.ts";
 import { resolveComponentRef } from "./helpers.ts";
+import type { OperationSecurity, SecuritySchemeLike } from "./security.ts";
+import { resolveAsyncApiSecurity } from "./security.ts";
 
 /**
  * Runtime helpers for the AsyncAPI components — the async counterpart of
@@ -239,32 +241,61 @@ export const channelParameters = (
 
 const SERVER_REF = /^#\/servers\/(?<name>[^/]+)$/u;
 
+/** A server paired with its key under the document's `servers`. */
+export interface NamedServer {
+  name: string;
+  server: AsyncApiServerObject;
+}
+
 /**
- * The servers a channel is available on: its `servers` refs when declared,
- * else every server the document declares (the spec's default).
+ * The servers a channel is available on, by name: its `servers` refs when
+ * declared, else every server the document declares (the spec's default).
  */
-export const channelServers = (
+export const namedChannelServers = (
   channel: AsyncApiChannelObject | undefined,
   document: AsyncApiDocument
-): AsyncApiServerObject[] => {
+): NamedServer[] => {
   const all = document.servers ?? {};
   const refs = channel?.servers;
   if (!Array.isArray(refs) || refs.length === 0) {
-    return Object.values(all).filter(isObject);
+    return Object.entries(all).flatMap(([name, server]) =>
+      isObject(server) ? [{ name, server }] : []
+    );
   }
-  const servers: AsyncApiServerObject[] = [];
+  const servers: NamedServer[] = [];
   for (const ref of refs) {
-    const name = SERVER_REF.exec(
+    const pointer = SERVER_REF.exec(
       isObject(ref) && isString(ref.$ref) ? ref.$ref : ""
     )?.groups?.name;
-    const server = name === undefined ? undefined : all[unescapePointer(name)];
-    if (isObject(server)) {
-      servers.push(server);
+    const name = pointer === undefined ? undefined : unescapePointer(pointer);
+    const server = name === undefined ? undefined : all[name];
+    if (name !== undefined && isObject(server)) {
+      servers.push({ name, server });
     }
   }
   return servers;
 };
 
+/**
+ * A server's `security` entries with their `$ref`s into
+ * `components.securitySchemes` resolved (non-objects dropped), for the
+ * samples, which read the scheme off the server they're built from.
+ */
+export const resolvedServerSecurity = (
+  server: AsyncApiServerObject,
+  components?: Components
+): AsyncApiRefLike[] =>
+  (Array.isArray(server.security) ? server.security : [])
+    .filter(isObject)
+    .map((entry) => resolveComponentRef(entry, components, "securitySchemes"));
+
+/** The servers a channel is available on; see {@link namedChannelServers}. */
+export const channelServers = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): AsyncApiServerObject[] =>
+  namedChannelServers(channel, document).map(({ server }) => server);
+
 /** A protocol-keyed `bindings` map, whatever object it sits on. */
 type BindingMap = Record<string, AsyncApiSpecValue>;
 
@@ -291,6 +322,34 @@ export const resolveBindings = (
   return isObject(target) ? target : undefined;
 };
 
+/** The `kafka` object of a bindings map, a `$ref`'d map resolved. */
+const kafkaBinding = (
+  bindings: BindingMap | undefined,
+  components?: Components
+): Record<string, AsyncApiSpecValue> | undefined => {
+  const kafka = resolveBindings(bindings, components)?.kafka;
+  return isObject(kafka) ? kafka : undefined;
+};
+
+/**
+ * A Kafka channel binding's `topic`, which names the topic when it differs
+ * from the channel address. The samples produce to and consume from it.
+ */
+export const kafkaTopic = (
+  channel: AsyncApiChannelObject | undefined,
+  components?: Components
+): string | undefined => {
+  const topic = kafkaBinding(channel?.bindings, components)?.topic;
+  return isString(topic) && topic !== "" ? topic : undefined;
+};
+
+/** The schema of a message's Kafka key (its `kafka` binding's `key`). */
+export const kafkaKeySchema = (
+  message: AsyncApiMessageLike | undefined,
+  components?: Components
+): SchemaLike | undefined =>
+  schemaOf(kafkaBinding(message?.bindings, components)?.key);
+
 /** Normalize protocol spellings onto the binding key they document. */
 const PROTOCOL_ALIASES = {
   "kafka-secure": "kafka",
@@ -326,35 +385,70 @@ export const protocolOf = (
 };
 
 /**
- * The security list an operation actually enforces: its own `security` when
- * declared, else the union of its servers' — connecting already requires the
- * server's schemes. Server entries dedupe by `$ref`, so two servers sharing a
- * scheme render it once.
+ * The security an operation renders: its own `security` when declared, else
+ * the union of its servers' — connecting already requires the server's
+ * schemes. Server entries dedupe by `$ref`, so two servers sharing a scheme
+ * render it once. Each server's list stands alone, though: when the servers
+ * disagree (a production cluster behind SASL beside a local broker with no
+ * security), a scheme only some servers declare names them, and
+ * `unauthenticatedServers` lists the ones that declare none, rather than one
+ * server's scheme reading as required on all of them.
  */
-export const asyncApiSecurityEntries = (
+export const asyncApiSecurity = (
   operation: AsyncApiOperationObject | undefined,
-  servers: AsyncApiServerObject[]
-): AsyncApiRefLike[] => {
+  servers: NamedServer[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
   if (Array.isArray(operation?.security)) {
-    return operation.security;
+    return resolveAsyncApiSecurity(operation.security, schemes);
   }
-  const entries: AsyncApiRefLike[] = [];
-  const seen = new Set<string>();
-  for (const server of servers) {
-    for (const entry of server.security ?? []) {
-      if (!isObject(entry)) {
+  const entries: { entry: AsyncApiRefLike; servers: string[] }[] = [];
+  const byRef = new Map<string, string[]>();
+  const unauthenticated: string[] = [];
+  for (const { name, server } of servers) {
+    const declared = Array.isArray(server.security)
+      ? server.security.filter(isObject)
+      : [];
+    if (declared.length === 0) {
+      unauthenticated.push(name);
+    }
+    for (const entry of declared) {
+      const shared = isString(entry.$ref) ? byRef.get(entry.$ref) : undefined;
+      if (shared) {
+        shared.push(name);
         continue;
       }
+      const names = [name];
       if (isString(entry.$ref)) {
-        if (seen.has(entry.$ref)) {
-          continue;
-        }
-        seen.add(entry.$ref);
+        byRef.set(entry.$ref, names);
       }
-      entries.push(entry);
+      entries.push({ entry, servers: names });
     }
   }
-  return entries;
+  const agree =
+    entries.length === 0 ||
+    (unauthenticated.length === 0 &&
+      entries.every((item) => item.servers.length === servers.length));
+  if (agree) {
+    return resolveAsyncApiSecurity(
+      entries.map(({ entry }) => entry),
+      schemes
+    );
+  }
+  return {
+    // A scheme every server declares needs no server list of its own.
+    alternatives: entries.map(({ entry, servers: names }) =>
+      resolveAsyncApiSecurity([entry], schemes)
+        .alternatives.flat()
+        .map((resolved) =>
+          names.length === servers.length
+            ? resolved
+            : { ...resolved, servers: names }
+        )
+    ),
+    optional: false,
+    unauthenticatedServers: unauthenticated,
+  };
 };
 
 /** One protocol's binding fields, ready for a key/value table. */