@opengroundplan/core 0.1.1

package/templates/layers/api-versioning/files/src/apiversion/contract/node/snapshot.ts

@@ -0,0 +1,76 @@
+/**
+ * Reading and writing committed contract snapshots. Split from the differ because this is
+ * the only part that touches the filesystem.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { apiVersionSettings, ENV_PREFIX } from '../../settings.js';
+import { breakingChanges, diffContracts, formatChanges } from '../diff.js';
+import { stableStringify } from '../shape.js';
+import type { ApiVersionSettings } from '../../settings.js';
+import type { ContractChange } from '../diff.js';
+import type { ContractSnapshot } from '../shape.js';
+
+export function snapshotPath(version: string, settings: ApiVersionSettings = apiVersionSettings()): string {
+  return path.join(settings.contractDir, `${version}.json`);
+}
+
+export function loadSnapshot(
+  version: string,
+  settings: ApiVersionSettings = apiVersionSettings(),
+): ContractSnapshot | undefined {
+  const file = snapshotPath(version, settings);
+  if (!existsSync(file)) return undefined;
+  return JSON.parse(readFileSync(file, 'utf8')) as ContractSnapshot;
+}
+
+export function saveSnapshot(
+  snapshot: ContractSnapshot,
+  settings: ApiVersionSettings = apiVersionSettings(),
+): string {
+  const file = snapshotPath(snapshot.version, settings);
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, stableStringify(snapshot), 'utf8');
+  return file;
+}
+
+/** Set to `1` to accept the current shape as the new baseline. Never set it in CI. */
+export const UPDATE_ENV_KEY = `${ENV_PREFIX}_UPDATE_CONTRACTS`;
+
+export class ContractBrokenError extends Error {
+  constructor(readonly changes: readonly ContractChange[]) {
+    super(`Contract broken for shipped clients:\n${formatChanges(changes)}`);
+    this.name = 'ContractBrokenError';
+  }
+}
+
+export interface VerifyResult {
+  changes: readonly ContractChange[];
+  /** True when no baseline existed and one was written. */
+  created: boolean;
+}
+
+/**
+ * Compares the live contract with what is committed. Throws on a breaking change; additive
+ * changes are returned so a test can report them and the author can refresh the baseline
+ * in the same commit that introduced them.
+ */
+export function verifyContract(
+  current: ContractSnapshot,
+  options: { update?: boolean; settings?: ApiVersionSettings } = {},
+): VerifyResult {
+  const settings = options.settings ?? apiVersionSettings();
+  const update = options.update ?? process.env[UPDATE_ENV_KEY] === '1';
+  const baseline = loadSnapshot(current.version, settings);
+
+  if (!baseline) {
+    saveSnapshot(current, settings);
+    return { changes: [], created: true };
+  }
+
+  const changes = diffContracts(baseline, current);
+  const breaking = breakingChanges(changes);
+  if (breaking.length > 0 && !update) throw new ContractBrokenError(breaking);
+  if (update) saveSnapshot(current, settings);
+  return { changes, created: false };
+}

package/templates/layers/api-versioning/files/src/apiversion/contract/shape.ts

@@ -0,0 +1,94 @@
+/**
+ * A payload's shape, reduced to what a client can actually depend on: which fields exist,
+ * whether they are always present, and what type they hold. Values are deliberately
+ * discarded — a contract is not a fixture, and snapshotting values makes every data change
+ * look like a contract change.
+ *
+ * Pure functions over plain objects: no fs, no process, so this module is importable from
+ * a test, a CI script, or a browser bundle.
+ */
+
+export type ScalarKind = 'string' | 'number' | 'boolean' | 'null' | 'unknown';
+
+export type Shape =
+  | { kind: 'object'; fields: Record<string, Field> }
+  | { kind: 'array'; items: Shape }
+  | { kind: ScalarKind };
+
+export interface Field {
+  required: boolean;
+  shape: Shape;
+}
+
+export interface OperationContract {
+  request?: Shape;
+  response?: Shape;
+}
+
+export interface ContractSnapshot {
+  version: string;
+  /** Keyed by operation, conventionally "GET /orders/{id}". */
+  operations: Record<string, OperationContract>;
+}
+
+export function describe(value: unknown): Shape {
+  if (value === null) return { kind: 'null' };
+  if (Array.isArray(value)) {
+    // An empty array promises nothing about its items, so it stays unknown rather than
+    // inventing a shape that the next sample would contradict.
+    return { kind: 'array', items: value.length === 0 ? { kind: 'unknown' } : describeAll(value) };
+  }
+  if (typeof value === 'object') {
+    const fields: Record<string, Field> = {};
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      fields[key] = { required: true, shape: describe(item) };
+    }
+    return { kind: 'object', fields };
+  }
+  if (typeof value === 'string') return { kind: 'string' };
+  if (typeof value === 'number') return { kind: 'number' };
+  if (typeof value === 'boolean') return { kind: 'boolean' };
+  return { kind: 'unknown' };
+}
+
+/** Several samples of the same payload. A field absent from any sample is optional. */
+export function describeAll(samples: readonly unknown[]): Shape {
+  if (samples.length === 0) return { kind: 'unknown' };
+  return samples.map(describe).reduce(mergeShapes);
+}
+
+export function mergeShapes(a: Shape, b: Shape): Shape {
+  if (a.kind === 'unknown') return b;
+  if (b.kind === 'unknown') return a;
+  if (a.kind !== b.kind) return { kind: 'unknown' };
+
+  if (a.kind === 'array' && b.kind === 'array') {
+    return { kind: 'array', items: mergeShapes(a.items, b.items) };
+  }
+  if (a.kind === 'object' && b.kind === 'object') {
+    const fields: Record<string, Field> = {};
+    for (const key of new Set([...Object.keys(a.fields), ...Object.keys(b.fields)])) {
+      const left = a.fields[key];
+      const right = b.fields[key];
+      if (left && right) {
+        fields[key] = { required: left.required && right.required, shape: mergeShapes(left.shape, right.shape) };
+      } else {
+        // Present in one sample only — the client cannot rely on it.
+        fields[key] = { required: false, shape: (left ?? right)!.shape };
+      }
+    }
+    return { kind: 'object', fields };
+  }
+  return a;
+}
+
+/** Stable key order so a snapshot diff shows contract changes, not serialization noise. */
+export function stableStringify(snapshot: ContractSnapshot): string {
+  return `${JSON.stringify(snapshot, sortKeys, 2)}\n`;
+}
+
+function sortKeys(_key: string, value: unknown): unknown {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+  return Object.fromEntries(entries);
+}

package/templates/layers/api-versioning/files/src/apiversion/errors.ts

@@ -0,0 +1,36 @@
+/** RFC 9457 problem details for a version a client asked for but this deployment cannot serve. */
+
+export const PROBLEM_MEDIA_TYPE = 'application/problem+json';
+
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail: string;
+  supported: readonly string[];
+  requested?: string;
+}
+
+export class UnsupportedApiVersionError extends Error {
+  readonly status = 400;
+
+  constructor(
+    readonly requested: string,
+    readonly supported: readonly string[],
+  ) {
+    super(`Unsupported API version "${requested}"; supported: ${supported.join(', ')}`);
+    this.name = 'UnsupportedApiVersionError';
+  }
+
+  /** `about:blank` is the RFC-correct type when the status code already says everything. */
+  toProblem(): ProblemDetails {
+    return {
+      type: 'about:blank',
+      title: 'Unsupported API version',
+      status: this.status,
+      detail: this.message,
+      supported: this.supported,
+      requested: this.requested,
+    };
+  }
+}

package/templates/layers/api-versioning/files/src/apiversion/headers.ts

@@ -0,0 +1,52 @@
+/**
+ * Response headers that tell a client what it got and how long it has left.
+ * Formats are fixed by RFC 9745 (Deprecation), RFC 8594 (Sunset) and RFC 8288 (Link) —
+ * they are protocol literals, not tunables.
+ */
+import { epochSeconds } from './settings.js';
+import { versionPolicy } from './versions.js';
+import type { VersionResolution } from './negotiate.js';
+import type { VersionPolicy } from './versions.js';
+
+/** IMF-fixdate, the only form RFC 8594 allows: Sat, 01 Aug 2026 00:00:00 GMT. */
+export function httpDate(isoDate: string): string {
+  return new Date(`${isoDate}T00:00:00Z`).toUTCString();
+}
+
+/**
+ * Caches key on the URL, so only strategies that hide the version outside the URL need a
+ * Vary. Getting this wrong serves one client's version to another from a shared cache.
+ */
+function varyHeader(policy: VersionPolicy): string | undefined {
+  switch (policy.settings.strategy) {
+    case 'header':
+      return policy.settings.headerName;
+    case 'accept':
+      return 'Accept';
+    default:
+      return undefined;
+  }
+}
+
+export function versionResponseHeaders(
+  resolution: VersionResolution,
+  policy: VersionPolicy = versionPolicy(),
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+  const { settings } = policy;
+
+  if (settings.emitResponseHeader) headers[settings.headerName] = resolution.version;
+
+  const vary = varyHeader(policy);
+  if (vary) headers['Vary'] = vary;
+
+  const deprecation = policy.deprecationFor(resolution.version);
+  if (!deprecation) return headers;
+
+  headers['Deprecation'] = `@${epochSeconds(deprecation.announced)}`;
+  headers['Sunset'] = httpDate(deprecation.sunset);
+  if (settings.policyUrl) {
+    headers['Link'] = `<${settings.policyUrl}>; rel="deprecation", <${settings.policyUrl}>; rel="sunset"`;
+  }
+  return headers;
+}

package/templates/layers/api-versioning/files/src/apiversion/index.ts

@@ -0,0 +1,23 @@
+/** Public surface of the versioning layer. Import from here, not from the modules. */
+export {
+  ApiVersionConfigError,
+  apiVersionSettings,
+  epochSeconds,
+  loadApiVersionSettings,
+  resetApiVersionSettings,
+} from './settings.js';
+export type { ApiVersionSettings, Deprecation, VersionStrategy } from './settings.js';
+
+export { createVersionPolicy, resetVersionPolicy, UnknownVersionError, versionPolicy } from './versions.js';
+export type { VersionPolicy } from './versions.js';
+
+export { headerValue, resolveVersion, versionFromAccept, versionFromPath } from './negotiate.js';
+export type { HeaderSource, VersionRequest, VersionResolution, VersionSource } from './negotiate.js';
+
+export { httpDate, versionResponseHeaders } from './headers.js';
+
+export { PROBLEM_MEDIA_TYPE, UnsupportedApiVersionError } from './errors.js';
+export type { ProblemDetails } from './errors.js';
+
+export { applyVersionHeaders, unsupportedVersionResponse, withApiVersion } from './middleware.js';
+export type { VersionedHandler } from './middleware.js';

package/templates/layers/api-versioning/files/src/apiversion/middleware.ts

@@ -0,0 +1,59 @@
+/**
+ * Fetch-standard wrapper. Hono, Next.js route handlers, Bun, Deno and Workers all speak
+ * Request/Response, so one adapter covers them; node:http gets its own under `node/`.
+ */
+import { PROBLEM_MEDIA_TYPE, UnsupportedApiVersionError } from './errors.js';
+import { versionResponseHeaders } from './headers.js';
+import { resolveVersion } from './negotiate.js';
+import { versionPolicy } from './versions.js';
+import type { VersionResolution } from './negotiate.js';
+import type { VersionPolicy } from './versions.js';
+
+export type VersionedHandler = (
+  request: Request,
+  resolution: VersionResolution,
+) => Response | Promise<Response>;
+
+/** Rebuilt rather than mutated: a Response from `fetch` has immutable headers. */
+export function applyVersionHeaders(
+  response: Response,
+  resolution: VersionResolution,
+  policy: VersionPolicy = versionPolicy(),
+): Response {
+  const headers = new Headers(response.headers);
+  for (const [name, value] of Object.entries(versionResponseHeaders(resolution, policy))) {
+    headers.set(name, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+export function unsupportedVersionResponse(error: UnsupportedApiVersionError): Response {
+  return new Response(JSON.stringify(error.toProblem()), {
+    status: error.status,
+    headers: { 'Content-Type': PROBLEM_MEDIA_TYPE },
+  });
+}
+
+export function withApiVersion(
+  handler: VersionedHandler,
+  policy: VersionPolicy = versionPolicy(),
+): (request: Request) => Promise<Response> {
+  return async (request) => {
+    const url = new URL(request.url);
+    let resolution: VersionResolution;
+    try {
+      resolution = resolveVersion(
+        { path: url.pathname, search: url.search, headers: request.headers },
+        policy,
+      );
+    } catch (error) {
+      if (error instanceof UnsupportedApiVersionError) return unsupportedVersionResponse(error);
+      throw error;
+    }
+    return applyVersionHeaders(await handler(request, resolution), resolution, policy);
+  };
+}

package/templates/layers/api-versioning/files/src/apiversion/negotiate.ts

@@ -0,0 +1,113 @@
+/**
+ * Version negotiation: a pure function of the request, so it is testable without a server
+ * and reusable from any framework. Nothing here reads the environment.
+ */
+import { UnsupportedApiVersionError } from './errors.js';
+import { versionPolicy } from './versions.js';
+import type { VersionPolicy } from './versions.js';
+
+export type VersionSource = 'path' | 'header' | 'query' | 'accept' | 'default';
+
+export interface VersionResolution {
+  version: string;
+  source: VersionSource;
+  /** What the client actually asked for. Undefined when it asked for nothing. */
+  requested?: string;
+}
+
+export type HeaderSource =
+  | Headers
+  | Record<string, string | string[] | undefined>
+  | ((name: string) => string | undefined);
+
+export interface VersionRequest {
+  /** Path only, no query string. */
+  path: string;
+  headers: HeaderSource;
+  /** Raw query string, with or without the leading `?`. */
+  search?: string;
+}
+
+/**
+ * Shapes a path segment must have to count as a version attempt. Without this,
+ * `/api/orders` under the path strategy would be read as a request for version "orders"
+ * and rejected. Matching a shape here means an unknown-but-version-shaped segment is
+ * refused loudly instead of silently falling through to the default.
+ */
+const VERSION_SHAPED = /^(v\d+(?:\.\d+)?|\d{4}-\d{2}-\d{2})$/i;
+
+export function headerValue(source: HeaderSource, name: string): string | undefined {
+  if (typeof source === 'function') return source(name) ?? undefined;
+  if (typeof (source as Headers).get === 'function') {
+    return (source as Headers).get(name) ?? undefined;
+  }
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(source as Record<string, string | string[] | undefined>)) {
+    if (key.toLowerCase() !== wanted) continue;
+    const first = Array.isArray(value) ? value[0] : value;
+    return first === undefined || first.trim() === '' ? undefined : first.trim();
+  }
+  return undefined;
+}
+
+/** Pulls `version=<value>` out of any media range in an Accept header. */
+export function versionFromAccept(accept: string | undefined): string | undefined {
+  if (!accept) return undefined;
+  for (const range of accept.split(',')) {
+    for (const parameter of range.split(';').slice(1)) {
+      const [name, ...rest] = parameter.split('=');
+      if (name?.trim().toLowerCase() !== 'version') continue;
+      const value = rest.join('=').trim().replace(/^"|"$/g, '');
+      if (value) return value;
+    }
+  }
+  return undefined;
+}
+
+/** The version segment the path strategy would read, or undefined if none was stated. */
+export function versionFromPath(
+  path: string,
+  pathPrefix: string,
+  policy: VersionPolicy,
+): string | undefined {
+  const prefix = pathPrefix.replace(/\/+$/, '');
+  const rest = prefix && path.startsWith(prefix) ? path.slice(prefix.length) : path;
+  const segment = rest.split('/').find(Boolean);
+  if (!segment) return undefined;
+  return policy.has(segment) || VERSION_SHAPED.test(segment) ? segment : undefined;
+}
+
+function requestedVersion(request: VersionRequest, policy: VersionPolicy): string | undefined {
+  const { strategy, headerName, queryParam, pathPrefix } = policy.settings;
+  switch (strategy) {
+    case 'path':
+      return versionFromPath(request.path, pathPrefix, policy);
+    case 'header':
+      return headerValue(request.headers, headerName);
+    case 'query':
+      return new URLSearchParams(request.search ?? '').get(queryParam)?.trim() || undefined;
+    case 'accept':
+      return versionFromAccept(headerValue(request.headers, 'accept'));
+  }
+}
+
+/**
+ * Resolves the version to serve. Throws UnsupportedApiVersionError when the client named a
+ * version this deployment does not have and strict mode is on.
+ */
+export function resolveVersion(
+  request: VersionRequest,
+  policy: VersionPolicy = versionPolicy(),
+): VersionResolution {
+  const { enabled, strategy, strict, defaultVersion } = policy.settings;
+  if (!enabled) return { version: defaultVersion, source: 'default' };
+
+  const requested = requestedVersion(request, policy);
+  if (requested === undefined) return { version: defaultVersion, source: 'default' };
+
+  if (!policy.has(requested)) {
+    if (strict) throw new UnsupportedApiVersionError(requested, policy.supported);
+    return { version: defaultVersion, source: 'default', requested };
+  }
+  return { version: requested, source: strategy, requested };
+}

package/templates/layers/api-versioning/files/src/apiversion/node/http.ts

@@ -0,0 +1,50 @@
+/**
+ * node:http adapter. Kept out of the core so an edge or Workers build never pulls a
+ * node: import into its bundle.
+ */
+import { PROBLEM_MEDIA_TYPE, UnsupportedApiVersionError } from '../errors.js';
+import { versionResponseHeaders } from '../headers.js';
+import { resolveVersion } from '../negotiate.js';
+import { versionPolicy } from '../versions.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { VersionResolution } from '../negotiate.js';
+import type { VersionPolicy } from '../versions.js';
+
+/** Absolute base only so `new URL` can parse; the authority is discarded. */
+const PARSE_BASE = 'http://localhost';
+
+export interface VersionedRequest extends IncomingMessage {
+  apiVersion?: VersionResolution;
+}
+
+/**
+ * Connect-style middleware. Sets `request.apiVersion`, stamps the response headers, and
+ * ends the exchange itself when the version is unknown — nothing downstream should run
+ * for a contract this deployment cannot honour.
+ */
+export function apiVersionMiddleware(policy: VersionPolicy = versionPolicy()) {
+  return (request: VersionedRequest, response: ServerResponse, next: (error?: unknown) => void): void => {
+    const url = new URL(request.url ?? '/', PARSE_BASE);
+    let resolution: VersionResolution;
+    try {
+      resolution = resolveVersion(
+        { path: url.pathname, search: url.search, headers: request.headers },
+        policy,
+      );
+    } catch (error) {
+      if (!(error instanceof UnsupportedApiVersionError)) {
+        next(error);
+        return;
+      }
+      response.writeHead(error.status, { 'Content-Type': PROBLEM_MEDIA_TYPE });
+      response.end(JSON.stringify(error.toProblem()));
+      return;
+    }
+
+    request.apiVersion = resolution;
+    for (const [name, value] of Object.entries(versionResponseHeaders(resolution, policy))) {
+      response.setHeader(name, value);
+    }
+    next();
+  };
+}