blume 2.0.3 → 2.1.1

package/src/openapi/scalar.ts

@@ -6,6 +6,7 @@ import { scalarReferenceTemplate } from "../astro/templates.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { trimChar } from "../core/trim.ts";
 import { resolveAccent, resolveRadius } from "../theme/palette.ts";
+import { readOverlaidSpec } from "./parse.ts";
 import { resolveReferences } from "./references.ts";
 import type { ReferenceSource } from "./references.ts";
 
@@ -53,14 +54,44 @@ const themeConfiguration = (config: ResolvedConfig, override?: string) => {
   };
 };
 
+/** A source's Scalar spec config, or none when its overlays failed. */
+interface SpecConfiguration {
+  config?: { content: string } | { url: string };
+  warning?: string;
+}
+
+/**
+ * The spec with its overlays applied, inlined: Scalar can't apply overlays
+ * itself. A failed overlay skips the page rather than embed the spec without
+ * it, since an overlay is often what hides the internal operations.
+ */
+const overlaidConfiguration = async (
+  ref: ReferenceSource,
+  root: string
+): Promise<SpecConfiguration> => {
+  try {
+    const { text, warnings } = await readOverlaidSpec(ref.spec, root, {
+      overlays: ref.overlays,
+    });
+    return { config: { content: text }, warning: warnings[0] };
+  } catch (error) {
+    // SAFETY: reading, parsing, and overlaying throw Error instances.
+    const { message } = error as Error;
+    return {
+      warning: `API reference ${ref.route} was skipped: its overlays couldn't be applied to "${ref.spec}" (${message}).`,
+    };
+  }
+};
+
 /** Build the Scalar spec config for a source: inline `content` or remote `url`. */
 const specConfiguration = async (
-  spec: string,
+  ref: ReferenceSource,
   root: string
-): Promise<{
-  config: { content: string } | { url: string };
-  warning?: string;
-}> => {
+): Promise<SpecConfiguration> => {
+  const { spec } = ref;
+  if (ref.overlays?.length) {
+    return await overlaidConfiguration(ref, root);
+  }
   if (URL_SPEC.test(spec)) {
     return { config: { url: spec } };
   }
@@ -133,7 +164,7 @@ export const buildReferenceFiles = async (options: {
   const built = await Promise.all(
     accepted.map(async (ref) => ({
       ref,
-      spec: await specConfiguration(ref.spec, root),
+      spec: await specConfiguration(ref, root),
     }))
   );
 
@@ -142,6 +173,9 @@ export const buildReferenceFiles = async (options: {
     if (spec.warning) {
       warnings.push(spec.warning);
     }
+    if (!spec.config) {
+      continue;
+    }
     const pagePath = referencePagePath(ref.route);
     // `theme` is the one option Blume maps (a named theme replaces the
     // accent/radius layering); every other `scalar()` option is forwarded

package/src/openapi/source.ts

@@ -11,6 +11,8 @@ import type {
 import type { Diagnostic } from "../core/types.ts";
 import { extractAsyncApiOperations } from "./asyncapi.ts";
 import type { AsyncApiDocument } from "./asyncapi.ts";
+import { specIssues } from "./checks.ts";
+import type { SpecIssue } from "./checks.ts";
 import { extractGraphqlOperations } from "./graphql.ts";
 import type { GraphqlDocument } from "./graphql.ts";
 import { extractOperations } from "./model.ts";
@@ -173,24 +175,34 @@ const specEntries = (
 };
 
 /**
- * Label each tag's sidebar group with the spec's own tag name. The group label
- * is otherwise re-humanized from the tag's route slug (split on hyphens,
+ * Label each tag's sidebar group with the spec's own tag name, and order the
+ * groups as the overview does: the spec's declared tag order, then first use
+ * (see `operationCollector`), not alphabetically. The group label is
+ * otherwise re-humanized from the tag's route slug (split on hyphens,
  * title-cased), which mangles authored casing and symbols — `OAuth2` →
- * "Oauth2", `Größe` → "Größe" only by luck of the slug. Keys are the tag
- * directories under the reference route, the same group paths `meta.ts` files
- * use, so user-authored meta still overrides these.
+ * "Oauth2", `Größe` → "Größe" only by luck of the slug. A source that names
+ * its own `label` gets it on its route's group the same way (`GitHub (v2)`,
+ * not "Github V2"). Keys are the directories under the reference route, the
+ * same group paths `meta.ts` files use, so user-authored meta still
+ * overrides these.
  */
 const tagFolderMeta = (
   spec: ApiSpecData,
-  tags: { slug: string; name: string }[]
+  tags: { slug: string; name: string }[],
+  groupLabel: string | undefined
 ): Record<string, FolderMeta> => {
   const base = routeToRef(spec.route);
-  return Object.fromEntries(
-    tags.map((tag) => [
+  const meta: Record<string, FolderMeta> = Object.fromEntries(
+    tags.map((tag, order) => [
       base ? `${base}/${tag.slug}` : tag.slug,
-      { title: tag.name },
+      { order, title: tag.name },
     ])
   );
+  // A root-mounted reference has no group of its own to name.
+  if (groupLabel !== undefined && base) {
+    meta[base] = { title: groupLabel };
+  }
+  return meta;
 };
 
 interface LoadedSpec {
@@ -210,6 +222,8 @@ interface ParsedReference {
   operations: ApiOperationRef[];
   tags: ApiTagRef[];
   extractWarnings: string[];
+  /** Spec mistakes that would render silently wrong (OpenAPI only). */
+  issues?: SpecIssue[];
 }
 
 const parseReference = async (
@@ -247,15 +261,16 @@ const parseReference = async (
       warnings,
     };
   }
-  const { document, warnings } = await parseSpec(
+  const { document, issues, warnings } = await parseSpec(
     reference.spec,
     ctx.projectRoot,
-    options
+    { ...options, overlays: reference.overlays }
   );
   const extracted = extractOperations(document, reference.route);
   return {
     document,
     extractWarnings: extracted.warnings,
+    issues: [...issues, ...specIssues(document)],
     operations: extracted.operations,
     tags: extracted.tags,
     warnings,
@@ -276,7 +291,7 @@ export const openApiSource = (
     const kindLabel = KIND_LABELS[reference.kind];
     const codePrefix = CODE_PREFIXES[reference.kind];
     try {
-      const { document, warnings, operations, tags, extractWarnings } =
+      const { document, warnings, operations, tags, extractWarnings, issues } =
         await parseReference(reference, ctx);
       const info = document.info ?? { title: reference.label, version: "" };
       // The playground proxy resolves here, not client-side: `true` selects
@@ -318,11 +333,15 @@ export const openApiSource = (
         title: info.title ?? reference.label,
         version: info.version ?? "",
       };
-      // Only GraphQL references carry a live endpoint (a schema names no
-      // server); assigned separately so the key stays absent otherwise.
+      // Only GraphQL references carry a live endpoint and its auth (a schema
+      // names no server); assigned separately so the keys stay absent
+      // otherwise.
       if (reference.endpoint !== undefined) {
         spec.endpoint = reference.endpoint;
       }
+      if (reference.auth !== undefined) {
+        spec.auth = reference.auth;
+      }
       return {
         diagnostics: [
           ...warnings.map((message) => ({
@@ -335,6 +354,12 @@ export const openApiSource = (
             message: `In ${kindLabel} spec "${reference.spec}": ${message}`,
             severity: "warning" as const,
           })),
+          ...(issues ?? []).map((issue) => ({
+            code: issue.code,
+            message: `In ${kindLabel} spec "${reference.spec}": ${issue.message}`,
+            severity: "warning" as const,
+            suggestion: issue.suggestion,
+          })),
           // A document with no operations (say, a config file that happens to
           // parse as YAML) would otherwise build a nav tab onto an empty
           // reference with no hint why.
@@ -350,7 +375,7 @@ export const openApiSource = (
             : []),
         ],
         entries: specEntries(spec, operations, reference),
-        folderMeta: tagFolderMeta(spec, tags),
+        folderMeta: tagFolderMeta(spec, tags, reference.groupLabel),
         slug: reference.slug,
         spec,
       };

package/src/ratelimit/cloudflare.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** The Worker binding Blume declares for the rate limiter. */
+export const RATE_LIMIT_BINDING = "BLUME_RATE_LIMIT";
+
+/** Options for {@link cloudflare}. */
+export interface CloudflareRateLimitOptions {
+  /**
+   * The rate limiting namespace, a positive integer unique in your
+   * Cloudflare account. Defaults to one derived from the site.
+   */
+  namespaceId?: string;
+  /** Requests each reader may make per window, per route. Defaults to 10. */
+  requests?: number;
+  /** The window, in seconds: Cloudflare allows 10 or 60. Defaults to 60. */
+  window?: 10 | 60;
+}
+
+export const cloudflareRateLimitOptionsSchema = z.strictObject({
+  namespaceId: z
+    .string()
+    .regex(/^[1-9]\d*$/u, "namespaceId is a positive integer, as a string.")
+    .optional(),
+  requests: z.number().int().positive().optional(),
+  window: z.union([z.literal(10), z.literal(60)]).optional(),
+});
+
+export type CloudflareRateLimitAdapter = AdapterDescriptor<
+  "cloudflare",
+  CloudflareRateLimitOptions
+>;
+
+export const cloudflareRateLimitAdapterSchema = adapterDescriptorSchema(
+  "cloudflare",
+  cloudflareRateLimitOptionsSchema
+);
+
+/**
+ * Counts with Cloudflare's Workers rate limiting, for a site deployed with
+ * `deployment: cloudflare()`: Blume declares the binding in the Worker's
+ * config, so there is nothing to set up. Cloudflare counts per location and
+ * allows a window of 10 or 60 seconds.
+ */
+export const cloudflare = (
+  options: CloudflareRateLimitOptions = {}
+): CloudflareRateLimitAdapter => ({
+  kind: "cloudflare",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/ratelimit/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Rate limiters for `blume.config.ts`. The server routes a reader can call —
+ * the assistant, the API playground proxy, and server-side search — limit
+ * each reader (by IP address) to a number of requests per window, answering
+ * `429 Too Many Requests` past it:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { upstash } from "blume/ratelimit";
+ *
+ * export default defineConfig({
+ *   rateLimit: upstash({ requests: 30, window: 600 }),
+ * });
+ * ```
+ *
+ * `memory()` is on by default; `rateLimit: false` turns limiting off. Each
+ * factory returns a plain descriptor (see `core/adapter.ts`), and the
+ * generated routes count with `runtime.ts`.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { cloudflare } from "./cloudflare.ts";
+export type {
+  CloudflareRateLimitAdapter,
+  CloudflareRateLimitOptions,
+} from "./cloudflare.ts";
+export { memory } from "./memory.ts";
+export type { MemoryAdapter, RateLimitOptions } from "./memory.ts";
+export type { RateLimitAdapter } from "./schema.ts";
+export { upstash } from "./upstash.ts";
+export type { UpstashAdapter, UpstashOptions } from "./upstash.ts";

package/src/ratelimit/memory.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** How many requests a reader gets per window, unless set. */
+export const DEFAULT_REQUESTS = 30;
+
+/** The window those requests are counted over, in seconds, unless set. */
+export const DEFAULT_WINDOW = 600;
+
+/** The limit every rate limiter takes: a count of requests per window. */
+export interface RateLimitOptions {
+  /** Requests each reader may make per window, per route. */
+  requests?: number;
+  /** The window, in seconds. */
+  window?: number;
+}
+
+export const rateLimitOptionsSchema = z.strictObject({
+  requests: z.number().int().positive().optional(),
+  window: z.number().int().positive().optional(),
+});
+
+export type MemoryAdapter = AdapterDescriptor<"memory", RateLimitOptions>;
+
+export const memoryAdapterSchema = adapterDescriptorSchema(
+  "memory",
+  rateLimitOptionsSchema
+);
+
+/**
+ * Counts each reader's requests in the server's own memory, the default. On
+ * a server that runs as one process (`node()`) the count is exact; on a
+ * platform that runs many short-lived instances (Vercel, Netlify,
+ * Cloudflare) each instance keeps its own, so it stops a burst from one
+ * reader rather than enforcing the limit exactly. For that, share the count
+ * with `upstash()` or `cloudflare()`.
+ */
+export const memory = (options: RateLimitOptions = {}): MemoryAdapter => ({
+  kind: "memory",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [],
+});

package/src/ratelimit/runtime.ts

@@ -0,0 +1,247 @@
+/**
+ * The rate limit the generated server routes check before any work: the
+ * assistant (`/api/ask`), the API playground proxy (`/_api-proxy`), and
+ * server-side search. Each route builds one limiter at module scope from the
+ * configured adapter (`rateLimit` in `blume.config.ts`) and asks it about
+ * every request, keyed by the reader's IP address and the route, so each
+ * route has its own budget.
+ *
+ * A limiter never stands between a reader and the docs by accident: a
+ * request whose address the host can't tell is let through, and so is one
+ * the shared store fails to count (logged, not blocked). A shared store
+ * without its secrets or binding falls back to counting in memory.
+ */
+import { clientAddressOf } from "../core/client-address.ts";
+import type { ClientContext } from "../core/client-address.ts";
+import { RATE_LIMIT_BINDING } from "./cloudflare.ts";
+import { DEFAULT_REQUESTS, DEFAULT_WINDOW } from "./memory.ts";
+import type { RateLimitAdapter } from "./schema.ts";
+import { upstashSecrets } from "./upstash.ts";
+
+/** What a limiter says about one request. */
+export interface RateLimitResult {
+  allowed: boolean;
+  /** Seconds until the reader's window resets. */
+  retryAfter: number;
+}
+
+/** Count one request against `key`. */
+export type Limiter = (key: string) => Promise<RateLimitResult>;
+
+/** A Workers rate limiting binding (`ratelimits` in the Worker's config). */
+export interface RateLimitBinding {
+  limit: (options: { key: string }) => Promise<{ success: boolean }>;
+}
+
+/** What a generated route hands the limiter from its runtime. */
+export interface LimiterRuntime {
+  /** The Worker's rate limiting binding, under `cloudflare()`. */
+  binding?: RateLimitBinding;
+  /** For tests; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** For tests; defaults to `Date.now`. */
+  now?: () => number;
+  /** Reads a secret (`getSecret` from `astro:env/server`). */
+  secret?: (name: string) => string | undefined;
+}
+
+/** Past this many tracked readers, a memory limiter drops expired ones. */
+const MEMORY_SWEEP_AT = 10_000;
+
+/** One reader's count in the current window. */
+interface MemoryEntry {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * Count in this server's memory, in fixed windows: each reader's first
+ * request opens a window, and the count resets when it ends.
+ */
+export const memoryLimiter = (
+  requests: number,
+  window: number,
+  now: () => number = Date.now
+): Limiter => {
+  const entries = new Map<string, MemoryEntry>();
+  return (key) => {
+    const time = now();
+    if (entries.size >= MEMORY_SWEEP_AT) {
+      for (const [tracked, entry] of entries) {
+        if (entry.resetAt <= time) {
+          entries.delete(tracked);
+        }
+      }
+    }
+    let entry = entries.get(key);
+    if (!entry || entry.resetAt <= time) {
+      entry = { count: 0, resetAt: time + window * 1000 };
+      entries.set(key, entry);
+    }
+    entry.count += 1;
+    return Promise.resolve({
+      allowed: entry.count <= requests,
+      retryAfter: Math.ceil((entry.resetAt - time) / 1000),
+    });
+  };
+};
+
+/**
+ * Counts the request and reads what's left of the window, run by Redis as
+ * one step. A key without an expiry — the one `INCR` just created, or one a
+ * failed call left behind — gets the window as its expiry, so a count can't
+ * outlive its window and lock a reader out of the route for good. Separate
+ * commands, even pipelined, let the key expire between them, and the `INCR`
+ * after that created a key that never expired.
+ */
+export const UPSTASH_COUNT_SCRIPT = `local count = redis.call("INCR", KEYS[1])
+local ttl = redis.call("TTL", KEYS[1])
+if ttl < 0 then
+  redis.call("EXPIRE", KEYS[1], ARGV[1])
+  ttl = tonumber(ARGV[1])
+end
+return {count, ttl}`;
+
+/** Upstash's REST reply to one command. */
+interface UpstashReply {
+  error?: string;
+  result?: (number | null)[] | null;
+}
+
+/**
+ * Count in Upstash Redis over its REST API: one `EVAL` of
+ * {@link UPSTASH_COUNT_SCRIPT} counts the request, opens the window when it's
+ * the first, and reads what's left of it.
+ */
+export const upstashLimiter = (
+  requests: number,
+  window: number,
+  endpoint: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch
+): Limiter => {
+  const url = endpoint.replace(/\/+$/u, "");
+  return async (key) => {
+    const response = await fetchImpl(url, {
+      body: JSON.stringify([
+        "EVAL",
+        UPSTASH_COUNT_SCRIPT,
+        "1",
+        key,
+        String(window),
+      ]),
+      headers: {
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+      },
+      method: "POST",
+    });
+    if (!response.ok) {
+      throw new Error(`Upstash answered ${response.status}.`);
+    }
+    // SAFETY: Upstash's REST API answers a command with `{ result }`, here
+    // the script's `{count, ttl}`; a missing or failed reply reads as `NaN`
+    // below.
+    const reply = (await response.json()) as UpstashReply;
+    const count = Number(reply.result?.[0] ?? Number.NaN);
+    const ttl = Number(reply.result?.[1]);
+    if (Number.isNaN(count)) {
+      throw new TypeError("Upstash sent no count.");
+    }
+    return { allowed: count <= requests, retryAfter: ttl > 0 ? ttl : window };
+  };
+};
+
+/** Count with a Workers rate limiting binding. */
+export const bindingLimiter =
+  (binding: RateLimitBinding, window: number): Limiter =>
+  async (key) => {
+    const { success } = await binding.limit({ key });
+    return { allowed: success, retryAfter: window };
+  };
+
+/** The limit an adapter sets, with Cloudflare's own defaults for its binding. */
+const limitOf = (adapter: RateLimitAdapter) =>
+  adapter.kind === "cloudflare"
+    ? {
+        requests: adapter.options.requests ?? 10,
+        window: adapter.options.window ?? 60,
+      }
+    : {
+        requests: adapter.options.requests ?? DEFAULT_REQUESTS,
+        window: adapter.options.window ?? DEFAULT_WINDOW,
+      };
+
+/**
+ * The limiter for the configured adapter, or `null` when rate limiting is
+ * off. A shared store missing its secrets or binding counts in memory and
+ * says so once.
+ */
+export const createLimiter = (
+  adapter: RateLimitAdapter | null,
+  runtime: LimiterRuntime = {}
+): Limiter | null => {
+  if (!adapter) {
+    return null;
+  }
+  const { requests, window } = limitOf(adapter);
+  if (adapter.kind === "cloudflare") {
+    if (runtime.binding) {
+      return bindingLimiter(runtime.binding, window);
+    }
+    console.warn(
+      `Rate limiting counts in memory: the Worker has no ${RATE_LIMIT_BINDING} binding.`
+    );
+  }
+  if (adapter.kind === "upstash") {
+    const secrets = upstashSecrets(adapter.options);
+    const [endpoint, token] = secrets.map((name) => runtime.secret?.(name));
+    if (endpoint && token) {
+      return upstashLimiter(requests, window, endpoint, token, runtime.fetch);
+    }
+    console.warn(
+      `Rate limiting counts in memory: set ${secrets.join(" and ")} to share the count through Upstash.`
+    );
+  }
+  return memoryLimiter(requests, window, runtime.now);
+};
+
+/** The slice of Astro's `APIContext` the check reads. */
+export type RateLimitContext = ClientContext;
+
+/**
+ * Count this request against the reader's budget for `scope` (the route).
+ * `null` to go ahead, or the `429 Too Many Requests` to return.
+ */
+export const rateLimited = async (
+  limiter: Limiter | null,
+  context: RateLimitContext,
+  scope: string
+): Promise<Response | null> => {
+  const address = limiter ? clientAddressOf(context) : undefined;
+  if (!(limiter && address)) {
+    return null;
+  }
+  // The host keeps two sites on one shared store apart.
+  const key = `blume:${new URL(context.request.url).host}:${scope}:${address}`;
+  let result: RateLimitResult;
+  try {
+    result = await limiter(key);
+  } catch (error) {
+    console.error("Rate limiting failed; letting the request through:", error);
+    return null;
+  }
+  if (result.allowed) {
+    return null;
+  }
+  return new Response(
+    `Too many requests: try again in ${result.retryAfter} seconds.`,
+    {
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        "retry-after": String(result.retryAfter),
+      },
+      status: 429,
+    }
+  );
+};

package/src/ratelimit/schema.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+import { cloudflareRateLimitAdapterSchema } from "./cloudflare.ts";
+import { memory, memoryAdapterSchema } from "./memory.ts";
+import { upstashAdapterSchema } from "./upstash.ts";
+
+const ADAPTER_HINT =
+  'rateLimit takes one adapter — e.g. `rateLimit: upstash()` or `rateLimit: memory({ requests: 60 })`, imported from "blume/ratelimit" — or `false` to turn it off.';
+
+/** The configured rate limiter, as its factory returned it. */
+export const rateLimitAdapterSchema = z.discriminatedUnion("kind", [
+  cloudflareRateLimitAdapterSchema,
+  memoryAdapterSchema,
+  upstashAdapterSchema,
+]);
+
+export type RateLimitAdapter = z.output<typeof rateLimitAdapterSchema>;
+
+/**
+ * `blume.config.rateLimit`: how the server routes a reader can call (the
+ * assistant, the API playground proxy, server-side search) limit requests
+ * per reader. On by default with `memory()`; `false` turns it off (`null`
+ * once resolved).
+ */
+export const rateLimitConfigSchema = z
+  .union([z.literal(false), rateLimitAdapterSchema], { error: ADAPTER_HINT })
+  .optional()
+  .transform((adapter) => (adapter === false ? null : (adapter ?? memory())));

package/src/ratelimit/upstash.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import { rateLimitOptionsSchema } from "./memory.ts";
+import type { RateLimitOptions } from "./memory.ts";
+
+/** The env var holding the Upstash Redis REST endpoint, unless set. */
+const UPSTASH_URL_ENV = "UPSTASH_REDIS_REST_URL";
+
+/** The env var holding the endpoint's token, unless set. */
+const UPSTASH_TOKEN_ENV = "UPSTASH_REDIS_REST_TOKEN";
+
+/** Options for {@link upstash}. */
+export interface UpstashOptions extends RateLimitOptions {
+  /**
+   * Name of the env var holding the REST token. Defaults to
+   * `UPSTASH_REDIS_REST_TOKEN`; a database added from Vercel's Marketplace
+   * sets `KV_REST_API_TOKEN`.
+   */
+  tokenEnv?: string;
+  /**
+   * Name of the env var holding the REST endpoint. Defaults to
+   * `UPSTASH_REDIS_REST_URL`; a database added from Vercel's Marketplace
+   * sets `KV_REST_API_URL`.
+   */
+  urlEnv?: string;
+}
+
+export const upstashOptionsSchema = rateLimitOptionsSchema.extend({
+  tokenEnv: z.string().min(1).optional(),
+  urlEnv: z.string().min(1).optional(),
+});
+
+export type UpstashAdapter = AdapterDescriptor<"upstash", UpstashOptions>;
+
+export const upstashAdapterSchema = adapterDescriptorSchema(
+  "upstash",
+  upstashOptionsSchema
+);
+
+/** The env vars the endpoint and its token are read from, in that order. */
+export const upstashSecrets = (options: UpstashOptions): [string, string] => [
+  options.urlEnv ?? UPSTASH_URL_ENV,
+  options.tokenEnv ?? UPSTASH_TOKEN_ENV,
+];
+
+/**
+ * Keeps the count in Upstash Redis, which every instance on every host shares,
+ * so the limit holds exactly. It talks to Upstash's REST API, so there is
+ * nothing to install; the endpoint and token come from
+ * `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN`, or the env vars
+ * `urlEnv` and `tokenEnv` name.
+ */
+export const upstash = (options: UpstashOptions = {}): UpstashAdapter => ({
+  kind: "upstash",
+  options,
+  requiredSecrets: upstashSecrets(options),
+  runtimeDeps: [],
+});