@ontrails/http 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/hono/trailhead.js

@@ -0,0 +1,232 @@
+/**
+ * Hono connector for Trails HTTP routes.
+ *
+ * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
+ * Hono application, handling request parsing, response mapping, and errors.
+ *
+ * ```ts
+ * const app = topo("myapp", entity);
+ * await trailhead(app, { port: 3000 });
+ * ```
+ */
+import { isTrailsError, statusCodeMap, validateTopo } from '@ontrails/core';
+import { Hono } from 'hono';
+import { buildHttpRoutes } from '../build.js';
+/** Unwrap optional/default wrappers to reach the underlying Zod type name. */
+const unwrapZodType = (node) => {
+    let current = node;
+    while (current._zod.def['type'] === 'optional' ||
+        current._zod.def['type'] === 'default') {
+        current = current._zod.def['innerType'];
+    }
+    return current._zod.def['type'];
+};
+/** Extract the object shape from a Zod schema, or undefined if not an object. */
+const extractShape = (schema) => {
+    const s = schema;
+    if (s._zod.def['type'] !== 'object') {
+        return undefined;
+    }
+    return s._zod.def['shape'];
+};
+/** Collect top-level field names whose underlying type is array. */
+const collectArrayKeys = (inputSchema) => {
+    const shape = inputSchema ? extractShape(inputSchema) : undefined;
+    if (!shape) {
+        return new Set();
+    }
+    const keys = new Set();
+    for (const [key, value] of Object.entries(shape)) {
+        if (unwrapZodType(value) === 'array') {
+            keys.add(key);
+        }
+    }
+    return keys;
+};
+/** Parse query params into a plain object, preserving raw strings for Zod. */
+const parseQueryParams = (c, inputSchema) => {
+    const result = {};
+    const url = new URL(c.req.url);
+    const arrayKeys = collectArrayKeys(inputSchema);
+    for (const key of url.searchParams.keys()) {
+        // Already collected via getAll
+        if (key in result) {
+            continue;
+        }
+        const all = url.searchParams.getAll(key);
+        result[key] = all.length > 1 || arrayKeys.has(key) ? all : all[0];
+    }
+    return result;
+};
+/** Sentinel indicating a JSON parse failure. */
+const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
+/** Return true when the request has no body content. */
+const isEmptyBody = (c) => {
+    const contentLength = c.req.header('Content-Length');
+    if (contentLength !== undefined) {
+        return Number.parseInt(contentLength, 10) === 0;
+    }
+    // No Content-Length header — treat as empty when Content-Type is also absent.
+    return c.req.header('Content-Type') === undefined;
+};
+/** Read input from request based on input source. */
+const readInput = async (c, inputSource, inputSchema) => {
+    if (inputSource === 'query') {
+        return parseQueryParams(c, inputSchema);
+    }
+    if (isEmptyBody(c)) {
+        return {};
+    }
+    try {
+        return await c.req.json();
+    }
+    catch {
+        return JSON_PARSE_ERROR;
+    }
+};
+// ---------------------------------------------------------------------------
+// Response mapping
+// ---------------------------------------------------------------------------
+/** Map a TrailsError or generic Error to an HTTP error response. */
+const mapErrorResponse = (error) => {
+    if (isTrailsError(error)) {
+        return {
+            body: {
+                error: {
+                    category: error.category,
+                    code: error.name,
+                    message: error.message,
+                },
+            },
+            status: statusCodeMap[error.category],
+        };
+    }
+    return {
+        body: {
+            error: {
+                category: 'internal',
+                code: 'InternalError',
+                message: error.message,
+            },
+        },
+        status: 500,
+    };
+};
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+/** Map a Result to an HTTP response via Hono context. */
+const mapResultToResponse = (result, c) => {
+    if (result.isOk()) {
+        return c.json({ data: result.value }, 200);
+    }
+    const { body, status } = mapErrorResponse(result.error ?? new Error('Unknown error'));
+    return c.json(body, status);
+};
+/** Convert a caught unknown value to an error response. */
+const handleCaughtError = (error, c) => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const { body, status } = mapErrorResponse(err);
+    return c.json(body, status);
+};
+/** Create a Hono handler from a route definition. */
+const createHonoHandler = (route) => async (c) => {
+    const rawInput = await readInput(c, route.inputSource, route.trail.input);
+    if (rawInput === JSON_PARSE_ERROR) {
+        return c.json({
+            error: {
+                category: 'validation',
+                code: 'ValidationError',
+                message: 'Invalid JSON in request body',
+            },
+        }, 400);
+    }
+    const requestId = c.req.header('X-Request-ID') ?? undefined;
+    const { signal: abortSignal } = c.req.raw;
+    try {
+        const result = await route.execute(rawInput, requestId, abortSignal);
+        return mapResultToResponse(result, c);
+    }
+    catch (error) {
+        return handleCaughtError(error, c);
+    }
+};
+/** Route registration keyed by HTTP method. */
+const routeRegistrars = {
+    DELETE: (hono, path, handler) => {
+        hono.delete(path, handler);
+    },
+    GET: (hono, path, handler) => {
+        hono.get(path, handler);
+    },
+    POST: (hono, path, handler) => {
+        hono.post(path, handler);
+    },
+};
+const registerRoutes = (hono, routes) => {
+    for (const route of routes) {
+        const handler = createHonoHandler(route);
+        routeRegistrars[route.method](hono, route.path, handler);
+    }
+};
+// ---------------------------------------------------------------------------
+// Global error handler
+// ---------------------------------------------------------------------------
+const registerErrorHandler = (hono) => {
+    // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
+    hono.onError((err, c) => c.json({
+        error: {
+            category: 'internal',
+            code: 'InternalError',
+            message: err.message,
+        },
+    }, 500));
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Throw a ValidationError if the topo has structural issues.
+ * Pass `skip: true` to bypass validation (e.g. when `validate: false` is set).
+ */
+const assertValidTopo = (app, skip = false) => {
+    if (skip) {
+        return;
+    }
+    const validated = validateTopo(app);
+    if (validated.isErr()) {
+        throw validated.error;
+    }
+};
+// ---------------------------------------------------------------------------
+// trailhead
+// ---------------------------------------------------------------------------
+/**
+ * Build HTTP routes from a topo, create a Hono app, and optionally start serving.
+ */
+// oxlint-disable-next-line require-await -- async for consistency with other trailhead() entrypoints
+export const trailhead = async (app, options = {}) => {
+    assertValidTopo(app, options.validate === false);
+    const hono = new Hono();
+    registerErrorHandler(hono);
+    const routesResult = buildHttpRoutes(app, {
+        basePath: options.basePath,
+        configValues: options.configValues,
+        createContext: options.createContext,
+        gates: options.gates,
+        provisions: options.provisions,
+    });
+    if (routesResult.isErr()) {
+        throw routesResult.error;
+    }
+    registerRoutes(hono, routesResult.value);
+    if (options.serve !== false) {
+        Bun.serve({
+            fetch: hono.fetch,
+            hostname: options.hostname ?? '0.0.0.0',
+            port: options.port ?? 3000,
+        });
+    }
+    return hono;
+};
+//# sourceMappingURL=trailhead.js.map

package/dist/hono/trailhead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailhead.js","sourceRoot":"","sources":["../../src/hono/trailhead.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/__tests__/build.test.ts

@@ -4,13 +4,13 @@ import {
   InternalError,
   NotFoundError,
   Result,
-  SURFACE_KEY,
-  service,
+  TRAILHEAD_KEY,
+  provision,
   ValidationError,
   trail,
   topo,
 } from '@ontrails/core';
-import type { Layer } from '@ontrails/core';
+import type { Gate } from '@ontrails/core';
 import { z } from 'zod';
 
 import { buildHttpRoutes } from '../build.js';
@@ -20,48 +20,48 @@ import { buildHttpRoutes } from '../build.js';
 // ---------------------------------------------------------------------------
 
 const echoTrail = trail('echo', {
+  blaze: (input) => Result.ok({ reply: input.message }),
   description: 'Echo a message back',
   input: z.object({ message: z.string() }),
   intent: 'read',
   output: z.object({ reply: z.string() }),
-  run: (input) => Result.ok({ reply: input.message }),
 });
 
 const createTrail = trail('item.create', {
+  blaze: (input) => Result.ok({ id: '123', name: input.name }),
   description: 'Create an item',
   input: z.object({ name: z.string() }),
   output: z.object({ id: z.string(), name: z.string() }),
-  run: (input) => Result.ok({ id: '123', name: input.name }),
 });
 
 const deleteTrail = trail('item.delete', {
+  blaze: (_input) => Result.ok({ deleted: true }),
   description: 'Delete an item',
   input: z.object({ id: z.string() }),
   intent: 'destroy',
-  run: (_input) => Result.ok({ deleted: true }),
 });
 
 const notFoundTrail = trail('item.get', {
+  blaze: (_input) => Result.err(new NotFoundError('Item not found')),
   description: 'Get an item that does not exist',
   input: z.object({ id: z.string() }),
   intent: 'read',
-  run: (_input) => Result.err(new NotFoundError('Item not found')),
 });
 
 const internalTrail = trail('crash', {
+  blaze: () => Result.err(new InternalError('Something broke')),
   description: 'Always fails with internal error',
   input: z.object({}),
-  run: () => Result.err(new InternalError('Something broke')),
 });
 
 const internalMetaTrail = trail('secret', {
+  blaze: () => Result.ok({ ok: true }),
   description: 'Internal trail that should be skipped',
   input: z.object({}),
-  metadata: { internal: true },
-  run: () => Result.ok({ ok: true }),
+  meta: { internal: true },
 });
 
-const dbService = service('db.main', {
+const dbProvision = provision('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
@@ -245,10 +245,10 @@ describe('buildHttpRoutes', () => {
 
     test('returns err Result when run function throws', async () => {
       const throwingTrail = trail('throwing', {
-        input: z.object({}),
-        run: () => {
+        blaze: () => {
           throw new Error('unexpected throw');
         },
+        input: z.object({}),
       });
       const app = topo('testapp', { throwingTrail });
       const buildResult = buildHttpRoutes(app);
@@ -283,12 +283,12 @@ describe('buildHttpRoutes', () => {
       let capturedRequestId: string | undefined;
 
       const ctxTrail = trail('ctx.check', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedRequestId = ctx.requestId;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
@@ -305,12 +305,12 @@ describe('buildHttpRoutes', () => {
       let capturedRequestId: string | undefined;
 
       const ctxTrail = trail('ctx.default', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           capturedRequestId = ctx.requestId;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
@@ -324,18 +324,18 @@ describe('buildHttpRoutes', () => {
       expect(capturedRequestId).not.toBe('');
     });
 
-    test('forwards service overrides into executeTrail', async () => {
-      const serviceTrail = trail('service.check', {
+    test('forwards provision overrides into executeTrail', async () => {
+      const provisionTrail = trail('provision.check', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: dbProvision.from(ctx).source as string }),
         input: z.object({}),
         output: z.object({ source: z.string() }),
-        run: (_input, ctx) =>
-          Result.ok({ source: dbService.from(ctx).source as string }),
-        services: [dbService],
+        provisions: [dbProvision],
       });
 
-      const app = topo('testapp', { serviceTrail });
+      const app = topo('testapp', { provisionTrail });
       const buildResult = buildHttpRoutes(app, {
-        services: { 'db.main': { source: 'override' } },
+        provisions: { 'db.main': { source: 'override' } },
       });
 
       expect(buildResult.isOk()).toBe(true);
@@ -347,12 +347,12 @@ describe('buildHttpRoutes', () => {
     });
   });
 
-  describe('layers', () => {
-    test('layers compose around trail execution', async () => {
+  describe('gates', () => {
+    test('gates compose around trail execution', async () => {
       const calls: string[] = [];
 
-      const testLayer: Layer = {
-        name: 'test-layer',
+      const testGate: Gate = {
+        name: 'test-gate',
         wrap(_trail, impl) {
           return async (input, ctx) => {
             calls.push('before');
@@ -364,7 +364,7 @@ describe('buildHttpRoutes', () => {
       };
 
       const app = topo('testapp', { echoTrail });
-      const buildResult = buildHttpRoutes(app, { layers: [testLayer] });
+      const buildResult = buildHttpRoutes(app, { gates: [testGate] });
 
       expect(buildResult.isOk()).toBe(true);
       const [route] = buildResult.value;
@@ -377,24 +377,25 @@ describe('buildHttpRoutes', () => {
 
   describe('custom createContext', () => {
     test('custom createContext is used when provided', async () => {
-      const contextState = { custom: false, surface: false };
+      const contextState = { custom: false, trailheadMarker: false };
 
       const ctxTrail = trail('ctx.custom', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           contextState.custom = ctx.extensions?.['custom'] === true;
-          contextState.surface = ctx.extensions?.[SURFACE_KEY] === 'http';
+          contextState.trailheadMarker =
+            ctx.extensions?.[TRAILHEAD_KEY] === 'http';
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
       const buildResult = buildHttpRoutes(app, {
         createContext: () => ({
+          abortSignal: new AbortController().signal,
           extensions: { custom: true },
           requestId: 'test-id',
-          signal: new AbortController().signal,
         }),
       });
 
@@ -404,7 +405,7 @@ describe('buildHttpRoutes', () => {
       const result = await route?.execute({});
       expect(result?.isOk()).toBe(true);
       expect(contextState.custom).toBe(true);
-      expect(contextState.surface).toBe(true);
+      expect(contextState.trailheadMarker).toBe(true);
     });
   });
 
@@ -414,16 +415,16 @@ describe('buildHttpRoutes', () => {
       // "entity/show" derives path /entity/show (slashes are preserved)
       // Both have intent: read -> GET, so they collide on GET /entity/show
       const dotTrail = trail('entity.show', {
+        blaze: () => Result.ok({ dot: true }),
         description: 'Show entity (dot notation)',
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok({ dot: true }),
       });
       const slashTrail = trail('entity/show', {
+        blaze: () => Result.ok({ slash: true }),
         description: 'Show entity (slash notation)',
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok({ slash: true }),
       });
       const app = topo('testapp', { dotTrail, slashTrail });
       const result = buildHttpRoutes(app);
@@ -438,15 +439,15 @@ describe('buildHttpRoutes', () => {
       // "item/resource" derives POST /item/resource (default intent: write)
       // Same path, different methods — no collision
       const getItem = trail('item.resource', {
+        blaze: () => Result.ok({ get: true }),
         description: 'Get item',
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok({ get: true }),
       });
       const createItem = trail('item/resource', {
+        blaze: () => Result.ok({ created: true }),
         description: 'Create item',
         input: z.object({ name: z.string() }),
-        run: () => Result.ok({ created: true }),
       });
       const app = topo('testapp', { createItem, getItem });
       const result = buildHttpRoutes(app);
@@ -457,16 +458,16 @@ describe('buildHttpRoutes', () => {
 
     test('collision error message identifies both trail IDs', () => {
       const dotTrail = trail('entity.show', {
+        blaze: () => Result.ok({ one: true }),
         description: 'Trail one',
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok({ one: true }),
       });
       const slashTrail = trail('entity/show', {
+        blaze: () => Result.ok({ two: true }),
         description: 'Trail two',
         input: z.object({}),
         intent: 'read',
-        run: () => Result.ok({ two: true }),
       });
       const app = topo('testapp', { dotTrail, slashTrail });
       const result = buildHttpRoutes(app);

package/src/build.ts

@@ -2,19 +2,19 @@
  * Build framework-agnostic HTTP route definitions from a Trails topo.
  *
  * Each route definition describes the path, method, input source, and an
- * `execute` function that validates input, composes layers, and runs the
+ * `execute` function that validates input, composes gates, and runs the
  * implementation -- all without referencing any HTTP framework types.
  */
 
 import {
   Result,
-  SURFACE_KEY,
+  TRAILHEAD_KEY,
   ValidationError,
   executeTrail,
 } from '@ontrails/core';
 import type {
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   Trail,
   TrailContextInit,
@@ -26,15 +26,15 @@ import type {
 
 export interface BuildHttpRoutesOptions {
   readonly basePath?: string | undefined;
-  /** Config values for services that declare a `config` schema, keyed by service ID. */
+  /** Config values for provisions that declare a `config` schema, keyed by provision ID. */
   readonly configValues?:
     | Readonly<Record<string, Record<string, unknown>>>
     | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  readonly layers?: readonly Layer[] | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly gates?: readonly Gate[] | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
 }
 
 export type HttpMethod = 'GET' | 'POST' | 'DELETE';
@@ -49,19 +49,19 @@ export interface HttpRouteDefinition {
   readonly inputSource: InputSource;
   readonly trail: Trail<unknown, unknown>;
   /**
-   * Validate input, compose layers, and execute the trail implementation.
+   * Validate input, compose gates, and execute the trail implementation.
    *
    * The caller is responsible for parsing raw input from the request and
    * mapping the Result to an HTTP response. This function is framework-agnostic.
    *
-   * @param signal - Optional AbortSignal from the HTTP request. When provided,
+   * @param abortSignal - Optional AbortSignal from the HTTP request. When provided,
    *   it takes final precedence over any context factory signal, allowing
    *   client-initiated cancellation to propagate into trail execution.
    */
   readonly execute: (
     input: unknown,
     requestId?: string | undefined,
-    signal?: AbortSignal | undefined
+    abortSignal?: AbortSignal | undefined
   ) => Promise<Result<unknown, Error>>;
 }
 
@@ -93,15 +93,15 @@ const deriveInputSource = (method: HttpMethod): InputSource =>
 
 /** Check if a trail should be included (skip internal trails). */
 const shouldInclude = (trail: Trail<unknown, unknown>): boolean =>
-  trail.metadata?.['internal'] !== true;
+  trail.meta?.['internal'] !== true;
 
-/** Build per-request context overrides with the HTTP surface marker. */
-const withHttpSurface = (
+/** Build per-request context overrides with the HTTP trailhead marker. */
+const withHttpTrailhead = (
   requestId: string | undefined
 ): Partial<TrailContextInit> => ({
   ...(requestId === undefined ? {} : { requestId }),
   extensions: {
-    [SURFACE_KEY]: 'http' as const,
+    [TRAILHEAD_KEY]: 'http' as const,
   },
 });
 
@@ -118,17 +118,17 @@ const withHttpSurface = (
 const createExecute =
   (
     t: Trail<unknown, unknown>,
-    layers: readonly Layer[],
+    gates: readonly Gate[],
     options: BuildHttpRoutesOptions
   ): HttpRouteDefinition['execute'] =>
-  (input, requestId, signal) =>
+  (input, requestId, abortSignal) =>
     executeTrail(t, input, {
+      abortSignal,
       configValues: options.configValues,
       createContext: options.createContext,
-      ctx: withHttpSurface(requestId),
-      layers,
-      services: options.services,
-      signal,
+      ctx: withHttpTrailhead(requestId),
+      gates,
+      provisions: options.provisions,
     });
 
 // ---------------------------------------------------------------------------
@@ -143,13 +143,13 @@ const eligibleTrails = (app: Topo): Trail<unknown, unknown>[] =>
 const buildRoute = (
   trail: Trail<unknown, unknown>,
   basePath: string,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildHttpRoutesOptions
 ): HttpRouteDefinition => {
   const method = deriveMethod(trail);
   const path = derivePath(basePath, trail.id);
   return {
-    execute: createExecute(trail, layers, options),
+    execute: createExecute(trail, gates, options),
     inputSource: deriveInputSource(method),
     method,
     path,
@@ -190,14 +190,14 @@ const registerRoute = (
 const accumulateRoutes = (
   trails: Trail<unknown, unknown>[],
   basePath: string,
-  layers: readonly Layer[],
+  gates: readonly Gate[],
   options: BuildHttpRoutesOptions
 ): Result<HttpRouteDefinition[], Error> => {
   const routes: HttpRouteDefinition[] = [];
   const seenRoutes = new Map<string, string>();
 
   for (const trail of trails) {
-    const route = buildRoute(trail, basePath, layers, options);
+    const route = buildRoute(trail, basePath, gates, options);
     const registered = registerRoute(route, seenRoutes, routes);
     if (registered.isErr()) {
       return registered;
@@ -218,7 +218,7 @@ const accumulateRoutes = (
  * - An HTTP method derived from intent (read -> GET, write -> POST, destroy -> DELETE)
  * - A path derived from the trail ID (dots become slashes)
  * - An input source derived from the method (GET -> query, others -> body)
- * - An `execute` function that validates, layers, and runs the implementation
+ * - An `execute` function that validates, gates, and runs the implementation
  *
  * Returns `Result.err(ValidationError)` if two trails derive the same
  * (method, path) pair. Returns `Result.ok(routes)` on success.
@@ -228,6 +228,6 @@ export const buildHttpRoutes = (
   options: BuildHttpRoutesOptions = {}
 ): Result<HttpRouteDefinition[], Error> => {
   const basePath = (options.basePath ?? '').replace(/\/+$/, '');
-  const layers = options.layers ?? [];
-  return accumulateRoutes(eligibleTrails(app), basePath, layers, options);
+  const gates = options.gates ?? [];
+  return accumulateRoutes(eligibleTrails(app), basePath, gates, options);
 };