@ontrails/http 0.2.0

package/src/index.ts

@@ -0,0 +1,28 @@
+// Build (framework-agnostic)
+export {
+  deriveHttpRoutes,
+  type DeriveHttpRoutesOptions,
+  type HttpExecutionContext,
+  type HttpHeaderSource,
+  type HttpLayerInputRendering,
+  type HttpRouteDefinition,
+  type ResolveHttpPermit,
+  type ResolveHttpPermitInput,
+} from './build.js';
+export {
+  deriveHttpInputSource,
+  deriveHttpMethod,
+  deriveHttpOperationMethod,
+  httpMethodByIntent,
+} from './method.js';
+export type { HttpMethod, HttpOperationMethod, InputSource } from './method.js';
+export {
+  createFetchHandler,
+  createRouteHandler,
+  type CreateFetchHandlerOptions,
+  type CreateRouteHandlerOptions,
+} from './fetch.js';
+
+// OpenAPI
+export { deriveOpenApiSpec } from './openapi.js';
+export type { OpenApiOptions, OpenApiSpec, OpenApiServer } from './openapi.js';

package/src/method.ts

@@ -0,0 +1,68 @@
+import type { Intent, WebhookMethod } from '@ontrails/core';
+
+export type HttpMethod = 'GET' | 'POST' | 'DELETE' | WebhookMethod;
+
+export type HttpOperationMethod = Lowercase<HttpMethod>;
+
+export type InputSource = 'query' | 'body' | 'webhook';
+
+/**
+ * Owner table for rendering trail intent onto HTTP methods.
+ *
+ * @example
+ * ```ts
+ * import { httpMethodByIntent } from '@ontrails/http';
+ *
+ * const readMethod = httpMethodByIntent.read;
+ * // readMethod === 'GET'
+ * ```
+ */
+export const httpMethodByIntent = {
+  destroy: 'DELETE',
+  read: 'GET',
+  write: 'POST',
+} as const satisfies Record<Intent, HttpMethod>;
+
+/**
+ * Derive the HTTP method used for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpMethod } from '@ontrails/http';
+ *
+ * const method = deriveHttpMethod('read');
+ * // method === 'GET'
+ * ```
+ */
+export const deriveHttpMethod = (intent: Intent): HttpMethod =>
+  (httpMethodByIntent as Partial<Record<string, HttpMethod>>)[intent] ?? 'POST';
+
+/**
+ * Derive the lowercase OpenAPI operation method for a trail intent.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpOperationMethod } from '@ontrails/http';
+ *
+ * const operationMethod = deriveHttpOperationMethod('destroy');
+ * // operationMethod === 'delete'
+ * ```
+ */
+export const deriveHttpOperationMethod = (
+  intent: Intent
+): HttpOperationMethod =>
+  deriveHttpMethod(intent).toLowerCase() as HttpOperationMethod;
+
+/**
+ * Derive where request input should be read from for an HTTP method.
+ *
+ * @example
+ * ```ts
+ * import { deriveHttpInputSource } from '@ontrails/http';
+ *
+ * const source = deriveHttpInputSource('GET');
+ * // source === 'query'
+ * ```
+ */
+export const deriveHttpInputSource = (method: HttpMethod): InputSource =>
+  method === 'GET' ? 'query' : 'body';

package/src/openapi.ts

@@ -0,0 +1,383 @@
+/**
+ * Derive an OpenAPI 3.1 specification from a Topo.
+ *
+ * Converts each trail into an HTTP operation, deriving paths, methods,
+ * parameters, and response schemas from the trail contract.
+ */
+
+import {
+  ValidationError,
+  filterSurfaceTrails,
+  renderErrorClassSurface,
+  validateSurfaceTopo,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import type {
+  SurfaceSelectionOptions,
+  SurfaceValidationOptions,
+  Topo,
+  Trail,
+} from '@ontrails/core';
+
+import { isBlobOutputSchema } from './blob-output.js';
+import { deriveHttpOperationMethod } from './method.js';
+
+type JsonSchema = Readonly<Record<string, unknown>>;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface OpenApiServer {
+  readonly url: string;
+  readonly description?: string | undefined;
+}
+
+export interface OpenApiOptions
+  extends SurfaceSelectionOptions, SurfaceValidationOptions {
+  /** Default: `graph.name` */
+  readonly title?: string | undefined;
+  /** Default: `'1.0.0'` */
+  readonly version?: string | undefined;
+  readonly description?: string | undefined;
+  readonly servers?: readonly OpenApiServer[] | undefined;
+  /** Prefix for all paths. Default: `''` */
+  readonly basePath?: string | undefined;
+}
+
+/** Minimal OpenAPI 3.1 spec shape — intentionally plain objects, no heavy library. */
+export interface OpenApiSpec {
+  readonly openapi: '3.1.0';
+  readonly info: {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string | undefined;
+  };
+  readonly servers?: readonly OpenApiServer[] | undefined;
+  readonly paths: Record<string, Record<string, unknown>>;
+  readonly components: { readonly schemas: Record<string, unknown> };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** `entity.show` → `/entity/show` */
+const trailIdToPath = (id: string, basePath: string): string =>
+  `${basePath}/${id.split('.').join('/')}`;
+
+/** First segment of a dotted ID, used as an OpenAPI tag. */
+const tagFromId = (id: string): string => id.split('.')[0] ?? id;
+
+/** Convert a Zod schema to JSON Schema via the core helper. */
+const toJsonSchema = (schema: unknown): JsonSchema =>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  zodToJsonSchema(schema as any) as JsonSchema;
+
+/** Build query parameters from a JSON Schema `properties` object. */
+const buildQueryParameters = (
+  jsonSchema: JsonSchema
+): Record<string, unknown>[] => {
+  const properties = jsonSchema['properties'] as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!properties) {
+    return [];
+  }
+
+  const required = new Set(
+    Array.isArray(jsonSchema['required'])
+      ? (jsonSchema['required'] as string[])
+      : []
+  );
+
+  return Object.entries(properties).map(([name, schema]) => ({
+    in: 'query',
+    name,
+    required: required.has(name),
+    schema,
+  }));
+};
+
+/** Map a single error example to a status code entry, or undefined if not mappable. */
+const errorExampleToEntry = (
+  errorName: string,
+  seen: Set<number>
+): [string, { description: string }] | undefined => {
+  const rendering = renderErrorClassSurface('http', errorName);
+  if (rendering === undefined) {
+    return undefined;
+  }
+
+  const { code } = rendering;
+  if (seen.has(code)) {
+    return undefined;
+  }
+  seen.add(code);
+  return [String(code), { description: errorName }];
+};
+
+/** Extract error status codes from trail examples that have an `error` field. */
+const errorResponsesFromExamples = (
+  examples: readonly { error?: string | undefined }[]
+): Record<string, { description: string }> => {
+  const responses: Record<string, { description: string }> = {};
+  const seen = new Set<number>();
+
+  for (const ex of examples) {
+    if (!ex.error) {
+      continue;
+    }
+    const entry = errorExampleToEntry(ex.error, seen);
+    if (entry) {
+      const [code, value] = entry;
+      responses[code] = value;
+    }
+  }
+
+  return responses;
+};
+
+// ---------------------------------------------------------------------------
+// Operation builder — split into focused helpers
+// ---------------------------------------------------------------------------
+
+/** True when the body is required — non-object schemas are always required,
+ *  object schemas are required only when they have at least one required property. */
+const isBodyRequired = (schema: JsonSchema): boolean => {
+  if (schema['type'] !== 'object') {
+    return true;
+  }
+  return (
+    Array.isArray(schema['required']) &&
+    (schema['required'] as unknown[]).length > 0
+  );
+};
+
+/** Build the input portion of an operation (parameters or requestBody). */
+const buildInputSpec = (
+  t: Trail<unknown, unknown, unknown>,
+  method: string
+): Record<string, unknown> => {
+  if (!t.input) {
+    return {};
+  }
+  const inputSchema = toJsonSchema(t.input);
+
+  if (method === 'get') {
+    const params = buildQueryParameters(inputSchema);
+    return params.length > 0 ? { parameters: params } : {};
+  }
+
+  const properties = inputSchema['properties'] as
+    | Record<string, unknown>
+    | undefined;
+  if (properties !== undefined && Object.keys(properties).length === 0) {
+    return {};
+  }
+
+  return {
+    requestBody: {
+      content: { 'application/json': { schema: inputSchema } },
+      required: isBodyRequired(inputSchema),
+    },
+  };
+};
+
+/** Wrap a raw output schema in the `{ data: ... }` envelope the HTTP adapter uses. */
+const wrapInDataEnvelope = (outputSchema: JsonSchema): JsonSchema => ({
+  properties: { data: outputSchema },
+  required: ['data'],
+  type: 'object',
+});
+
+/** Shared error response body schema: `{ error: { message, code, category } }`. */
+const errorResponseSchema: JsonSchema = {
+  properties: {
+    error: {
+      properties: {
+        category: { type: 'string' },
+        code: { type: 'string' },
+        message: { type: 'string' },
+      },
+      required: ['message', 'code', 'category'],
+      type: 'object',
+    },
+  },
+  required: ['error'],
+  type: 'object',
+};
+
+/** Build the 200 response entry. */
+const buildSuccessResponse = (
+  t: Trail<unknown, unknown, unknown>
+): Record<string, unknown> => {
+  if (!t.output) {
+    return { '200': { description: 'Success' } };
+  }
+  if (isBlobOutputSchema(t.output)) {
+    // BlobRef routes stream raw bytes at runtime (`fetch.ts` serves the
+    // blob's declared mimeType and Content-Length), so the spec documents
+    // a binary body instead of the JSON data envelope. The concrete
+    // Content-Type is per-blob runtime data, hence the `*/*` range.
+    return {
+      '200': {
+        content: {
+          '*/*': { schema: { format: 'binary', type: 'string' } },
+        },
+        description:
+          "Binary content: raw blob bytes served with the blob's declared mimeType",
+      },
+    };
+  }
+  const outputSchema = toJsonSchema(t.output);
+  return {
+    '200': {
+      content: {
+        'application/json': { schema: wrapInDataEnvelope(outputSchema) },
+      },
+      description: 'Success',
+    },
+  };
+};
+
+/** Build the default 400 validation error response. */
+const validationErrorResponse: Record<
+  string,
+  { content: Record<string, unknown>; description: string }
+> = {
+  '400': {
+    content: { 'application/json': { schema: errorResponseSchema } },
+    description: 'Validation error',
+  },
+};
+
+/** Build all responses (success + error) for a trail. */
+const buildResponses = (
+  t: Trail<unknown, unknown, unknown>
+): Record<string, unknown> => {
+  const examples = (t.examples ?? []) as readonly {
+    error?: string | undefined;
+  }[];
+  return {
+    ...buildSuccessResponse(t),
+    ...errorResponsesFromExamples(examples),
+    ...validationErrorResponse,
+  };
+};
+
+const operationIdFromTrailId = (trailId: string): string =>
+  trailId.replaceAll('.', '_');
+
+/** Build a complete OpenAPI operation for a trail. */
+const buildOperation = (
+  t: Trail<unknown, unknown, unknown>,
+  method: string
+): Record<string, unknown> => ({
+  operationId: operationIdFromTrailId(t.id),
+  responses: buildResponses(t),
+  tags: [tagFromId(t.id)],
+  ...(t.description ? { summary: t.description } : {}),
+  ...buildInputSpec(t, method),
+});
+
+// ---------------------------------------------------------------------------
+// Path collection
+// ---------------------------------------------------------------------------
+
+/** Collect all paths from public trails in the graph. */
+const collectPaths = (
+  graph: Topo,
+  basePath: string,
+  options?: OpenApiOptions
+): Record<string, Record<string, unknown>> => {
+  const paths: Record<string, Record<string, unknown>> = {};
+  const seenRoutes = new Map<string, string>();
+  const seenOperationIds = new Map<string, string>();
+
+  for (const t of filterSurfaceTrails(graph.list(), {
+    exclude: options?.exclude,
+    include: options?.include,
+    intent: options?.intent,
+  })) {
+    const method = deriveHttpOperationMethod(t.intent);
+    const path = trailIdToPath(t.id, basePath);
+    const routeKey = `${method.toUpperCase()} ${path}`;
+    const existingId = seenRoutes.get(routeKey);
+    if (existingId !== undefined) {
+      throw new ValidationError(
+        `HTTP route collision: trails "${existingId}" and "${t.id}" both derive ${routeKey}`
+      );
+    }
+    seenRoutes.set(routeKey, t.id);
+
+    const operationId = operationIdFromTrailId(t.id);
+    const existingOperationId = seenOperationIds.get(operationId);
+    if (existingOperationId !== undefined) {
+      throw new ValidationError(
+        `OpenAPI operationId collision: trails "${existingOperationId}" and "${t.id}" both derive operationId "${operationId}"`
+      );
+    }
+    seenOperationIds.set(operationId, t.id);
+
+    paths[path] ??= {};
+    paths[path][method] = buildOperation(t, method);
+  }
+
+  return paths;
+};
+
+/** Build the info object from options and graph name. */
+const buildInfo = (
+  graphName: string,
+  options?: OpenApiOptions
+): OpenApiSpec['info'] => ({
+  title: options?.title ?? graphName,
+  version: options?.version ?? '1.0.0',
+  ...(options?.description ? { description: options.description } : {}),
+});
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive an OpenAPI 3.1 specification from a Topo.
+ *
+ * Iterates all trails, skipping signals and internal trails, and produces
+ * paths, operations, parameters, and response schemas derived from
+ * the trail contract.
+ *
+ * @example
+ * ```ts
+ * import { deriveOpenApiSpec } from '@ontrails/http';
+ *
+ * const spec = deriveOpenApiSpec(graph, {
+ *   basePath: '/api',
+ *   title: 'Demo API',
+ * });
+ * ```
+ */
+export const deriveOpenApiSpec = (
+  graph: Topo,
+  options?: OpenApiOptions
+): OpenApiSpec => {
+  const validated = validateSurfaceTopo(graph, options);
+  if (validated.isErr()) {
+    throw validated.error;
+  }
+
+  return {
+    components: { schemas: {} },
+    info: buildInfo(graph.name, options),
+    openapi: '3.1.0',
+    paths: collectPaths(
+      graph,
+      (options?.basePath ?? '').replace(/\/+$/, ''),
+      options
+    ),
+    ...(options?.servers && options.servers.length > 0
+      ? { servers: options.servers }
+      : {}),
+  };
+};

package/src/query-coercion.ts

@@ -0,0 +1,150 @@
+interface QueryZodInternals {
+  readonly _zod: {
+    readonly def: Readonly<Record<string, unknown>>;
+  };
+}
+
+interface QueryLayerFieldMetadata {
+  readonly knownFields: ReadonlySet<string>;
+  readonly preserveRawFields: ReadonlySet<string>;
+}
+
+interface QueryLayerRendering {
+  readonly routing: ReadonlyMap<string, string>;
+}
+
+const queryLayerFieldMetadata = new WeakMap<
+  ReadonlyMap<string, string>,
+  QueryLayerFieldMetadata
+>();
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const queryZodDef = (
+  schema: unknown
+): Readonly<Record<string, unknown>> | undefined => {
+  if (!isRecord(schema)) {
+    return undefined;
+  }
+  const internals = (schema as Partial<QueryZodInternals>)._zod;
+  return internals !== undefined && isRecord(internals.def)
+    ? internals.def
+    : undefined;
+};
+
+const querySchemaContainsCoercion = (
+  schema: unknown,
+  seen = new Set<unknown>()
+): boolean => {
+  const def = queryZodDef(schema);
+  if (def === undefined) {
+    return false;
+  }
+  if (def['coerce'] === true) {
+    return true;
+  }
+  if (seen.has(schema)) {
+    return false;
+  }
+  seen.add(schema);
+
+  const { element, innerType, options, type } = def;
+  if (type === 'array') {
+    return querySchemaContainsCoercion(element, seen);
+  }
+  if (type === 'union') {
+    return (
+      Array.isArray(options) &&
+      options.some((option) => querySchemaContainsCoercion(option, seen))
+    );
+  }
+  if (
+    type === 'default' ||
+    type === 'nullable' ||
+    type === 'optional' ||
+    type === 'readonly'
+  ) {
+    return querySchemaContainsCoercion(innerType, seen);
+  }
+  return false;
+};
+
+export const coercingQueryFields = (schema: unknown): ReadonlySet<string> => {
+  const fields = new Set<string>();
+  const visit = (candidate: unknown, seen: Set<unknown>): void => {
+    const def = queryZodDef(candidate);
+    if (def === undefined || seen.has(candidate)) {
+      return;
+    }
+    seen.add(candidate);
+
+    const { innerType, options, shape, type } = def;
+    if (type === 'object') {
+      if (!isRecord(shape)) {
+        return;
+      }
+      for (const [name, fieldSchema] of Object.entries(shape)) {
+        if (querySchemaContainsCoercion(fieldSchema)) {
+          fields.add(name);
+        }
+      }
+      return;
+    }
+    if (type === 'union') {
+      if (!Array.isArray(options)) {
+        return;
+      }
+      for (const option of options) {
+        visit(option, seen);
+      }
+      return;
+    }
+    if (
+      type === 'default' ||
+      type === 'nullable' ||
+      type === 'optional' ||
+      type === 'readonly'
+    ) {
+      visit(innerType, seen);
+    }
+  };
+  visit(schema, new Set());
+  return fields;
+};
+
+export const recordQueryLayerCoercion = (
+  inputSchema: unknown,
+  routing: ReadonlyMap<string, string>
+): void => {
+  const coercingFields = coercingQueryFields(inputSchema);
+  const preserveRawFields = new Set<string>();
+  for (const [renderedName, originalName] of routing) {
+    if (coercingFields.has(originalName)) {
+      preserveRawFields.add(renderedName);
+    }
+  }
+  queryLayerFieldMetadata.set(routing, {
+    knownFields: new Set(routing.keys()),
+    preserveRawFields,
+  });
+};
+
+export const preservedLayerQueryFields = (
+  renderings: readonly QueryLayerRendering[]
+): ReadonlySet<string> => {
+  const preserveRawFields = new Set<string>();
+  for (const { routing } of renderings) {
+    const metadata = queryLayerFieldMetadata.get(routing);
+    for (const renderedName of routing.keys()) {
+      if (
+        metadata === undefined ||
+        !metadata.knownFields.has(renderedName) ||
+        metadata.preserveRawFields.has(renderedName)
+      ) {
+        preserveRawFields.add(renderedName);
+      }
+    }
+  }
+  return preserveRawFields;
+};