@ontrails/http 1.0.0-beta.12

package/src/__tests__/build.test.ts

@@ -0,0 +1,478 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+  InternalError,
+  NotFoundError,
+  Result,
+  SURFACE_KEY,
+  service,
+  ValidationError,
+  trail,
+  topo,
+} from '@ontrails/core';
+import type { Layer } from '@ontrails/core';
+import { z } from 'zod';
+
+import { buildHttpRoutes } from '../build.js';
+
+// ---------------------------------------------------------------------------
+// Test trails
+// ---------------------------------------------------------------------------
+
+const echoTrail = trail('echo', {
+  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', {
+  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', {
+  description: 'Delete an item',
+  input: z.object({ id: z.string() }),
+  intent: 'destroy',
+  run: (_input) => Result.ok({ deleted: true }),
+});
+
+const notFoundTrail = trail('item.get', {
+  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', {
+  description: 'Always fails with internal error',
+  input: z.object({}),
+  run: () => Result.err(new InternalError('Something broke')),
+});
+
+const internalMetaTrail = trail('secret', {
+  description: 'Internal trail that should be skipped',
+  input: z.object({}),
+  metadata: { internal: true },
+  run: () => Result.ok({ ok: true }),
+});
+
+const dbService = service('db.main', {
+  create: () =>
+    Result.ok({
+      source: 'factory',
+    }),
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('buildHttpRoutes', () => {
+  describe('method derivation', () => {
+    test('intent: read maps to GET', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.method).toBe('GET');
+    });
+
+    test('intent: destroy maps to DELETE', () => {
+      const app = topo('testapp', { deleteTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.method).toBe('DELETE');
+    });
+
+    test('default intent (write) maps to POST', () => {
+      const app = topo('testapp', { createTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.method).toBe('POST');
+    });
+  });
+
+  describe('path derivation', () => {
+    test('dotted ID becomes slashed path', () => {
+      const app = topo('testapp', { createTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.path).toBe('/item/create');
+    });
+
+    test('simple ID becomes /id', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.path).toBe('/echo');
+    });
+
+    test('basePath is prepended', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app, { basePath: '/api/v1' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.path).toBe('/api/v1/echo');
+    });
+
+    test('basePath trailing slash is normalized', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app, { basePath: '/api/v1/' });
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.path).toBe('/api/v1/echo');
+    });
+  });
+
+  describe('input source derivation', () => {
+    test('GET routes use query input source', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.inputSource).toBe('query');
+    });
+
+    test('POST routes use body input source', () => {
+      const app = topo('testapp', { createTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.inputSource).toBe('body');
+    });
+
+    test('DELETE routes use body input source', () => {
+      const app = topo('testapp', { deleteTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.inputSource).toBe('body');
+    });
+  });
+
+  describe('filtering', () => {
+    test('internal trails are skipped', () => {
+      const app = topo('testapp', { echoTrail, internalMetaTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      const routes = result.value;
+      expect(routes).toHaveLength(1);
+      expect(routes[0]?.trailId).toBe('echo');
+    });
+  });
+
+  describe('route definition shape', () => {
+    test('includes trail reference', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value[0]?.trail).toBe(echoTrail);
+    });
+
+    test('execute is a function', () => {
+      const app = topo('testapp', { echoTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(typeof result.value[0]?.execute).toBe('function');
+    });
+  });
+
+  describe('execute', () => {
+    test('returns ok Result on valid input', async () => {
+      const app = topo('testapp', { echoTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({ message: 'hello' });
+      expect(result?.isOk()).toBe(true);
+      expect(result?.value).toEqual({ reply: 'hello' });
+    });
+
+    test('returns err Result on invalid input', async () => {
+      const app = topo('testapp', { echoTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({});
+      expect(result?.isErr()).toBe(true);
+    });
+
+    test('returns err Result from trail error', async () => {
+      const app = topo('testapp', { notFoundTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({ id: 'missing' });
+      expect(result?.isErr()).toBe(true);
+      expect(result?.error?.message).toBe('Item not found');
+    });
+
+    test('returns err Result from internal error', async () => {
+      const app = topo('testapp', { internalTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({});
+      expect(result?.isErr()).toBe(true);
+      expect(result?.error?.message).toBe('Something broke');
+    });
+
+    test('returns err Result when run function throws', async () => {
+      const throwingTrail = trail('throwing', {
+        input: z.object({}),
+        run: () => {
+          throw new Error('unexpected throw');
+        },
+      });
+      const app = topo('testapp', { throwingTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({});
+      expect(result?.isErr()).toBe(true);
+      expect(result?.error).toBeInstanceOf(InternalError);
+      expect(result?.error?.message).toBe('unexpected throw');
+    });
+
+    test('returns err Result when createContext throws', async () => {
+      const app = topo('testapp', { echoTrail });
+      const buildResult = buildHttpRoutes(app, {
+        createContext: () => {
+          throw new Error('context creation failed');
+        },
+      });
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({ message: 'hi' });
+      expect(result?.isErr()).toBe(true);
+      expect(result?.error).toBeInstanceOf(InternalError);
+      expect(result?.error?.message).toBe('context creation failed');
+    });
+
+    test('passes requestId to context', async () => {
+      let capturedRequestId: string | undefined;
+
+      const ctxTrail = trail('ctx.check', {
+        input: z.object({}),
+        intent: 'read',
+        run: (_input, ctx) => {
+          capturedRequestId = ctx.requestId;
+          return Result.ok({ ok: true });
+        },
+      });
+
+      const app = topo('testapp', { ctxTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      await route?.execute({}, 'custom-req-123');
+      expect(capturedRequestId).toBe('custom-req-123');
+    });
+
+    test('uses default requestId when none provided', async () => {
+      let capturedRequestId: string | undefined;
+
+      const ctxTrail = trail('ctx.default', {
+        input: z.object({}),
+        intent: 'read',
+        run: (_input, ctx) => {
+          capturedRequestId = ctx.requestId;
+          return Result.ok({ ok: true });
+        },
+      });
+
+      const app = topo('testapp', { ctxTrail });
+      const buildResult = buildHttpRoutes(app);
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      await route?.execute({});
+      expect(capturedRequestId).toBeDefined();
+      expect(capturedRequestId).not.toBe('');
+    });
+
+    test('forwards service overrides into executeTrail', async () => {
+      const serviceTrail = trail('service.check', {
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        run: (_input, ctx) =>
+          Result.ok({ source: dbService.from(ctx).source as string }),
+        services: [dbService],
+      });
+
+      const app = topo('testapp', { serviceTrail });
+      const buildResult = buildHttpRoutes(app, {
+        services: { 'db.main': { source: 'override' } },
+      });
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({});
+      expect(result?.isOk()).toBe(true);
+      expect(result?.value).toEqual({ source: 'override' });
+    });
+  });
+
+  describe('layers', () => {
+    test('layers compose around trail execution', async () => {
+      const calls: string[] = [];
+
+      const testLayer: Layer = {
+        name: 'test-layer',
+        wrap(_trail, impl) {
+          return async (input, ctx) => {
+            calls.push('before');
+            const result = await impl(input, ctx);
+            calls.push('after');
+            return result;
+          };
+        },
+      };
+
+      const app = topo('testapp', { echoTrail });
+      const buildResult = buildHttpRoutes(app, { layers: [testLayer] });
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({ message: 'hi' });
+      expect(result?.isOk()).toBe(true);
+      expect(calls).toEqual(['before', 'after']);
+    });
+  });
+
+  describe('custom createContext', () => {
+    test('custom createContext is used when provided', async () => {
+      const contextState = { custom: false, surface: false };
+
+      const ctxTrail = trail('ctx.custom', {
+        input: z.object({}),
+        intent: 'read',
+        run: (_input, ctx) => {
+          contextState.custom = ctx.extensions?.['custom'] === true;
+          contextState.surface = ctx.extensions?.[SURFACE_KEY] === 'http';
+          return Result.ok({ ok: true });
+        },
+      });
+
+      const app = topo('testapp', { ctxTrail });
+      const buildResult = buildHttpRoutes(app, {
+        createContext: () => ({
+          extensions: { custom: true },
+          requestId: 'test-id',
+          signal: new AbortController().signal,
+        }),
+      });
+
+      expect(buildResult.isOk()).toBe(true);
+      const [route] = buildResult.value;
+
+      const result = await route?.execute({});
+      expect(result?.isOk()).toBe(true);
+      expect(contextState.custom).toBe(true);
+      expect(contextState.surface).toBe(true);
+    });
+  });
+
+  describe('collision detection', () => {
+    test('returns err on duplicate (path, method) pair', () => {
+      // "entity.show" derives path /entity/show (dots become slashes)
+      // "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', {
+        description: 'Show entity (dot notation)',
+        input: z.object({}),
+        intent: 'read',
+        run: () => Result.ok({ dot: true }),
+      });
+      const slashTrail = trail('entity/show', {
+        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);
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+      expect(result.error?.message).toContain('GET /entity/show');
+    });
+
+    test('same path with different methods is allowed', () => {
+      // "item.resource" derives GET /item/resource (intent: read)
+      // "item/resource" derives POST /item/resource (default intent: write)
+      // Same path, different methods — no collision
+      const getItem = trail('item.resource', {
+        description: 'Get item',
+        input: z.object({}),
+        intent: 'read',
+        run: () => Result.ok({ get: true }),
+      });
+      const createItem = trail('item/resource', {
+        description: 'Create item',
+        input: z.object({ name: z.string() }),
+        run: () => Result.ok({ created: true }),
+      });
+      const app = topo('testapp', { createItem, getItem });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value).toHaveLength(2);
+    });
+
+    test('collision error message identifies both trail IDs', () => {
+      const dotTrail = trail('entity.show', {
+        description: 'Trail one',
+        input: z.object({}),
+        intent: 'read',
+        run: () => Result.ok({ one: true }),
+      });
+      const slashTrail = trail('entity/show', {
+        description: 'Trail two',
+        input: z.object({}),
+        intent: 'read',
+        run: () => Result.ok({ two: true }),
+      });
+      const app = topo('testapp', { dotTrail, slashTrail });
+      const result = buildHttpRoutes(app);
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error?.message).toContain('entity');
+    });
+  });
+});

package/src/build.ts

@@ -0,0 +1,233 @@
+/**
+ * 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
+ * implementation -- all without referencing any HTTP framework types.
+ */
+
+import {
+  Result,
+  SURFACE_KEY,
+  ValidationError,
+  executeTrail,
+} from '@ontrails/core';
+import type {
+  Layer,
+  ServiceOverrideMap,
+  Topo,
+  Trail,
+  TrailContextInit,
+} from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface BuildHttpRoutesOptions {
+  readonly basePath?: string | undefined;
+  /** Config values for services that declare a `config` schema, keyed by service 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;
+}
+
+export type HttpMethod = 'GET' | 'POST' | 'DELETE';
+
+/** Input source derived from the HTTP method. */
+export type InputSource = 'query' | 'body';
+
+export interface HttpRouteDefinition {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly trailId: string;
+  readonly inputSource: InputSource;
+  readonly trail: Trail<unknown, unknown>;
+  /**
+   * Validate input, compose layers, 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,
+   *   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
+  ) => Promise<Result<unknown, Error>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Explicit intent → HTTP method mapping. */
+const intentToMethod: Record<string, HttpMethod> = {
+  destroy: 'DELETE',
+  read: 'GET',
+  write: 'POST',
+};
+
+/** Derive HTTP method from trail intent. */
+const deriveMethod = (trail: Trail<unknown, unknown>): HttpMethod =>
+  intentToMethod[trail.intent] ?? 'POST';
+
+/** Derive HTTP path from trail ID: `entity.show` -> `/entity/show`. */
+const derivePath = (basePath: string, trailId: string): string => {
+  const segments = trailId.replaceAll('.', '/');
+  const base = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  return `${base}/${segments}`;
+};
+
+/** Derive input source from HTTP method. */
+const deriveInputSource = (method: HttpMethod): InputSource =>
+  method === 'GET' ? 'query' : 'body';
+
+/** Check if a trail should be included (skip internal trails). */
+const shouldInclude = (trail: Trail<unknown, unknown>): boolean =>
+  trail.metadata?.['internal'] !== true;
+
+/** Build per-request context overrides with the HTTP surface marker. */
+const withHttpSurface = (
+  requestId: string | undefined
+): Partial<TrailContextInit> => ({
+  ...(requestId === undefined ? {} : { requestId }),
+  extensions: {
+    [SURFACE_KEY]: 'http' as const,
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Execute factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an `execute` function for a single trail.
+ *
+ * Delegates to the centralized `executeTrail` pipeline in core.
+ * The returned function returns a `Result` and never throws.
+ */
+const createExecute =
+  (
+    t: Trail<unknown, unknown>,
+    layers: readonly Layer[],
+    options: BuildHttpRoutesOptions
+  ): HttpRouteDefinition['execute'] =>
+  (input, requestId, signal) =>
+    executeTrail(t, input, {
+      configValues: options.configValues,
+      createContext: options.createContext,
+      ctx: withHttpSurface(requestId),
+      layers,
+      services: options.services,
+      signal,
+    });
+
+// ---------------------------------------------------------------------------
+// Builder helpers
+// ---------------------------------------------------------------------------
+
+/** Filter topo items to eligible trails. */
+const eligibleTrails = (app: Topo): Trail<unknown, unknown>[] =>
+  app.list().filter((trail) => shouldInclude(trail));
+
+/** Build a single route definition from a trail. */
+const buildRoute = (
+  trail: Trail<unknown, unknown>,
+  basePath: string,
+  layers: readonly Layer[],
+  options: BuildHttpRoutesOptions
+): HttpRouteDefinition => {
+  const method = deriveMethod(trail);
+  const path = derivePath(basePath, trail.id);
+  return {
+    execute: createExecute(trail, layers, options),
+    inputSource: deriveInputSource(method),
+    method,
+    path,
+    trail,
+    trailId: trail.id,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Collision detection
+// ---------------------------------------------------------------------------
+
+/** Derive the lookup key for (method, path) collision detection. */
+const routeKey = (route: HttpRouteDefinition): `${string} ${string}` =>
+  `${route.method} ${route.path}`;
+
+/** Register a route, checking for (path, method) collisions. */
+const registerRoute = (
+  route: HttpRouteDefinition,
+  seenRoutes: Map<string, string>,
+  routes: HttpRouteDefinition[]
+): Result<void, Error> => {
+  const key = routeKey(route);
+  const existingId = seenRoutes.get(key);
+  if (existingId !== undefined) {
+    return Result.err(
+      new ValidationError(
+        `HTTP route collision: trails "${existingId}" and "${route.trailId}" both derive ${route.method} ${route.path}`
+      )
+    );
+  }
+  seenRoutes.set(key, route.trailId);
+  routes.push(route);
+  return Result.ok();
+};
+
+/** Accumulate route definitions, returning early on the first collision. */
+const accumulateRoutes = (
+  trails: Trail<unknown, unknown>[],
+  basePath: string,
+  layers: readonly Layer[],
+  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 registered = registerRoute(route, seenRoutes, routes);
+    if (registered.isErr()) {
+      return registered;
+    }
+  }
+
+  return Result.ok(routes);
+};
+
+// ---------------------------------------------------------------------------
+// Builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build HTTP route definitions from a topo.
+ *
+ * Each trail becomes an HttpRouteDefinition with:
+ * - 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
+ *
+ * Returns `Result.err(ValidationError)` if two trails derive the same
+ * (method, path) pair. Returns `Result.ok(routes)` on success.
+ */
+export const buildHttpRoutes = (
+  app: Topo,
+  options: BuildHttpRoutesOptions = {}
+): Result<HttpRouteDefinition[], Error> => {
+  const basePath = (options.basePath ?? '').replace(/\/+$/, '');
+  const layers = options.layers ?? [];
+  return accumulateRoutes(eligibleTrails(app), basePath, layers, options);
+};