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

package/src/hono/__tests__/{blaze.test.ts → trailhead.test.ts}

@@ -4,55 +4,55 @@ import {
   InternalError,
   NotFoundError,
   Result,
-  service,
+  provision,
   trail,
   topo,
 } from '@ontrails/core';
-import type { Layer } from '@ontrails/core';
+import type { Gate } from '@ontrails/core';
 import { z } from 'zod';
 
-import { blaze } from '../blaze.js';
+import { trailhead } from '../trailhead.js';
 
 // ---------------------------------------------------------------------------
 // Test trails
 // ---------------------------------------------------------------------------
 
 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 dbService = service('db.main', {
+const dbProvision = provision('db.main', {
   create: () =>
     Result.ok({
       source: 'factory',
@@ -65,7 +65,7 @@ const dbService = service('db.main', {
 
 /** Make a request against a Hono test app. */
 const request = (
-  app: Awaited<ReturnType<typeof blaze>>,
+  app: Awaited<ReturnType<typeof trailhead>>,
   method: string,
   path: string,
   body?: Record<string, unknown>,
@@ -82,7 +82,7 @@ const request = (
 
 /** Make a request with a raw string body. */
 const requestRaw = (
-  app: Awaited<ReturnType<typeof blaze>>,
+  app: Awaited<ReturnType<typeof trailhead>>,
   method: string,
   path: string,
   rawBody: string,
@@ -100,29 +100,31 @@ const requestRaw = (
 // Tests
 // ---------------------------------------------------------------------------
 
-describe('blaze (Hono adapter)', () => {
+describe('trailhead (Hono connector)', () => {
   describe('validation', () => {
-    test('blaze throws on invalid topo', async () => {
+    test('trailhead throws on invalid topo', async () => {
       const t = trail('broken', {
-        follow: ['nonexistent.trail'],
+        blaze: () => Result.ok({}),
+        crosses: ['nonexistent.trail'],
         input: z.object({}),
         output: z.object({}),
-        run: () => Result.ok({}),
       });
       const app = topo('test', { t });
-      await expect(blaze(app, { serve: false })).rejects.toThrow(/validation/i);
+      await expect(trailhead(app, { serve: false })).rejects.toThrow(
+        /validation/i
+      );
     });
 
-    test('blaze skips validation when validate: false', async () => {
+    test('trailhead skips validation when validate: false', async () => {
       const t = trail('broken', {
-        follow: ['nonexistent.trail'],
+        blaze: () => Result.ok({}),
+        crosses: ['nonexistent.trail'],
         input: z.object({}),
         output: z.object({}),
-        run: () => Result.ok({}),
       });
       const app = topo('test', { t });
       await expect(
-        blaze(app, { serve: false, validate: false })
+        trailhead(app, { serve: false, validate: false })
       ).resolves.toBeDefined();
     });
   });
@@ -130,7 +132,7 @@ describe('blaze (Hono adapter)', () => {
   describe('GET handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/echo?message=hello');
       expect(res.status).toBe(200);
@@ -141,7 +143,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 on invalid input', async () => {
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/echo');
       expect(res.status).toBe(400);
@@ -155,7 +157,7 @@ describe('blaze (Hono adapter)', () => {
   describe('POST handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/item/create', {
         name: 'Widget',
@@ -168,7 +170,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 on invalid input', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/item/create', {});
       expect(res.status).toBe(400);
@@ -179,14 +181,14 @@ describe('blaze (Hono adapter)', () => {
 
     test('POST with empty input schema succeeds without a body', async () => {
       const emptyWriteTrail = trail('empty.write', {
+        blaze: () => Result.ok({ ok: true }),
         input: z.object({}),
         intent: 'write',
         output: z.object({ ok: z.boolean() }),
-        run: () => Result.ok({ ok: true }),
       });
 
       const app = topo('testapp', { emptyWriteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       // No body, no Content-Type header — mirrors a client that obeys the
       // OpenAPI spec (no requestBody declared for empty-input POST routes).
@@ -201,7 +203,7 @@ describe('blaze (Hono adapter)', () => {
   describe('DELETE handler', () => {
     test('returns 200 with data on success', async () => {
       const app = topo('testapp', { deleteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'DELETE', '/item/delete', {
         id: 'abc',
@@ -216,7 +218,7 @@ describe('blaze (Hono adapter)', () => {
   describe('error mapping', () => {
     test('NotFoundError maps to 404', async () => {
       const app = topo('testapp', { notFoundTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/item/get?id=missing');
       expect(res.status).toBe(404);
@@ -228,7 +230,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('InternalError maps to 500', async () => {
       const app = topo('testapp', { internalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/crash', {});
       expect(res.status).toBe(500);
@@ -239,14 +241,14 @@ describe('blaze (Hono adapter)', () => {
 
     test('thrown exceptions map to 500', async () => {
       const throwTrail = trail('throw', {
-        input: z.object({}),
-        run: () => {
+        blaze: () => {
           throw new Error('unexpected crash');
         },
+        input: z.object({}),
       });
 
       const app = topo('testapp', { throwTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'POST', '/throw', {});
       expect(res.status).toBe(500);
@@ -256,12 +258,12 @@ describe('blaze (Hono adapter)', () => {
     });
   });
 
-  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');
@@ -273,7 +275,7 @@ describe('blaze (Hono adapter)', () => {
       };
 
       const app = topo('testapp', { echoTrail });
-      const hono = await blaze(app, { layers: [testLayer], serve: false });
+      const hono = await trailhead(app, { gates: [testGate], serve: false });
 
       const res = await request(hono, 'GET', '/echo?message=hi');
       expect(res.status).toBe(200);
@@ -284,7 +286,7 @@ describe('blaze (Hono adapter)', () => {
   describe('malformed JSON body', () => {
     test('returns 400 for invalid JSON in POST body', async () => {
       const app = topo('testapp', { createTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await requestRaw(hono, 'POST', '/item/create', '{invalid');
       expect(res.status).toBe(400);
@@ -297,7 +299,7 @@ describe('blaze (Hono adapter)', () => {
 
     test('returns 400 for invalid JSON in DELETE body', async () => {
       const app = topo('testapp', { deleteTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await requestRaw(hono, 'DELETE', '/item/delete', 'not-json');
       expect(res.status).toBe(400);
@@ -310,13 +312,13 @@ describe('blaze (Hono adapter)', () => {
   describe('query param parsing', () => {
     test('numeric-looking string is preserved as string', async () => {
       const stringIdTrail = trail('lookup', {
+        blaze: (input) => Result.ok({ id: input.id }),
         input: z.object({ id: z.string() }),
         intent: 'read',
-        run: (input) => Result.ok({ id: input.id }),
       });
 
       const app = topo('testapp', { stringIdTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/lookup?id=00123');
       expect(res.status).toBe(200);
@@ -327,13 +329,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('repeated keys become arrays', async () => {
       const tagsTrail = trail('tags', {
+        blaze: (input) => Result.ok({ tags: input.tags }),
         input: z.object({ tags: z.array(z.string()) }),
         intent: 'read',
-        run: (input) => Result.ok({ tags: input.tags }),
       });
 
       const app = topo('testapp', { tagsTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/tags?tags=a&tags=b');
       expect(res.status).toBe(200);
@@ -344,13 +346,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('single value is wrapped in array when schema expects z.array()', async () => {
       const tagsTrail = trail('tags.single', {
+        blaze: (input) => Result.ok({ tags: input.tags }),
         input: z.object({ tags: z.array(z.string()) }),
         intent: 'read',
-        run: (input) => Result.ok({ tags: input.tags }),
       });
 
       const app = topo('testapp', { tagsTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/tags/single?tags=foo');
       expect(res.status).toBe(200);
@@ -361,13 +363,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('single value stays scalar when schema expects a string', async () => {
       const nameTrail = trail('name.check', {
+        blaze: (input) => Result.ok({ name: input.name }),
         input: z.object({ name: z.string() }),
         intent: 'read',
-        run: (input) => Result.ok({ name: input.name }),
       });
 
       const app = topo('testapp', { nameTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/name/check?name=bar');
       expect(res.status).toBe(200);
@@ -378,13 +380,13 @@ describe('blaze (Hono adapter)', () => {
 
     test('optional array field with single value is wrapped in array', async () => {
       const optArrayTrail = trail('opt.array', {
+        blaze: (input) => Result.ok({ ids: input.ids }),
         input: z.object({ ids: z.array(z.string()).optional() }),
         intent: 'read',
-        run: (input) => Result.ok({ ids: input.ids }),
       });
 
       const app = topo('testapp', { optArrayTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/opt/array?ids=one');
       expect(res.status).toBe(200);
@@ -399,17 +401,17 @@ describe('blaze (Hono adapter)', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.check', {
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
+          return Result.ok({ ok: true });
+        },
         input: z.object({}),
         intent: 'read',
         output: z.object({ ok: z.boolean() }),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
-          return Result.ok({ ok: true });
-        },
       });
 
       const app = topo('testapp', { signalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/signal/check');
       expect(res.status).toBe(200);
@@ -420,17 +422,17 @@ describe('blaze (Hono adapter)', () => {
       let capturedSignal: AbortSignal | undefined;
 
       const signalTrail = trail('signal.aborted', {
+        blaze: (_input, ctx) => {
+          capturedSignal = ctx.abortSignal;
+          return Result.ok({ ok: true });
+        },
         input: z.object({}),
         intent: 'read',
         output: z.object({ ok: z.boolean() }),
-        run: (_input, ctx) => {
-          capturedSignal = ctx.signal;
-          return Result.ok({ ok: true });
-        },
       });
 
       const app = topo('testapp', { signalTrail });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const controller = new AbortController();
       controller.abort();
@@ -453,16 +455,16 @@ describe('blaze (Hono adapter)', () => {
       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 });
-      const hono = await blaze(app, { serve: false });
+      const hono = await trailhead(app, { serve: false });
 
       const res = await request(hono, 'GET', '/ctx/check', undefined, {
         'X-Request-ID': 'custom-req-123',
@@ -476,20 +478,20 @@ describe('blaze (Hono adapter)', () => {
       let contextUsed = false;
 
       const ctxTrail = trail('ctx.custom', {
-        input: z.object({}),
-        intent: 'read',
-        run: (_input, ctx) => {
+        blaze: (_input, ctx) => {
           contextUsed = ctx.extensions?.['custom'] === true;
           return Result.ok({ ok: true });
         },
+        input: z.object({}),
+        intent: 'read',
       });
 
       const app = topo('testapp', { ctxTrail });
-      const hono = await blaze(app, {
+      const hono = await trailhead(app, {
         createContext: () => ({
+          abortSignal: new AbortController().signal,
           extensions: { custom: true },
           requestId: 'test-id',
-          signal: new AbortController().signal,
         }),
         serve: false,
       });
@@ -499,23 +501,23 @@ describe('blaze (Hono adapter)', () => {
       expect(contextUsed).toBe(true);
     });
 
-    test('service overrides reach the trail through blaze()', async () => {
-      const serviceTrail = trail('service.check', {
+    test('provision overrides reach the trail through trailhead()', async () => {
+      const provisionTrail = trail('provision.check', {
+        blaze: (_input, ctx) =>
+          Result.ok({ source: dbProvision.from(ctx).source as string }),
         input: z.object({}),
         intent: 'read',
         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', { dbService, serviceTrail });
-      const hono = await blaze(app, {
+      const app = topo('testapp', { dbProvision, provisionTrail });
+      const hono = await trailhead(app, {
+        provisions: { 'db.main': { source: 'override' } },
         serve: false,
-        services: { 'db.main': { source: 'override' } },
       });
 
-      const res = await request(hono, 'GET', '/service/check');
+      const res = await request(hono, 'GET', '/provision/check');
       expect(res.status).toBe(200);
 
       const json = await res.json();

package/src/hono/index.ts

@@ -1 +1 @@
-export { blaze, type BlazeHttpOptions } from './blaze.js';
+export { trailhead, type TrailheadHttpOptions } from './trailhead.js';

package/src/hono/{blaze.ts → trailhead.ts}

@@ -1,19 +1,19 @@
 /**
- * Hono adapter for Trails HTTP routes.
+ * 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 blaze(app, { port: 3000 });
+ * await trailhead(app, { port: 3000 });
  * ```
  */
 
 import { isTrailsError, statusCodeMap, validateTopo } from '@ontrails/core';
 import type {
-  Layer,
-  ServiceOverrideMap,
+  Gate,
+  ProvisionOverrideMap,
   Topo,
   TrailContextInit,
 } from '@ontrails/core';
@@ -29,9 +29,9 @@ import { buildHttpRoutes } from '../build.js';
 // Options
 // ---------------------------------------------------------------------------
 
-export interface BlazeHttpOptions {
+export interface TrailheadHttpOptions {
   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;
@@ -39,10 +39,10 @@ export interface BlazeHttpOptions {
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
   readonly hostname?: string | undefined;
-  readonly layers?: readonly Layer[] | undefined;
+  readonly gates?: readonly Gate[] | undefined;
   readonly name?: string | undefined;
   readonly port?: number | undefined;
-  readonly services?: ServiceOverrideMap | undefined;
+  readonly provisions?: ProvisionOverrideMap | undefined;
   /** Set false to return the Hono app without starting a server. */
   readonly serve?: boolean | undefined;
   /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
@@ -233,10 +233,10 @@ const createHonoHandler =
     }
 
     const requestId = c.req.header('X-Request-ID') ?? undefined;
-    const { signal } = c.req.raw;
+    const { signal: abortSignal } = c.req.raw;
 
     try {
-      const result = await route.execute(rawInput, requestId, signal);
+      const result = await route.execute(rawInput, requestId, abortSignal);
       return mapResultToResponse(result, c);
     } catch (error: unknown) {
       return handleCaughtError(error, c);
@@ -309,16 +309,16 @@ const assertValidTopo = (app: Topo, skip = false): void => {
 };
 
 // ---------------------------------------------------------------------------
-// blaze
+// 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 blaze() surfaces
-export const blaze = async (
+// oxlint-disable-next-line require-await -- async for consistency with other trailhead() entrypoints
+export const trailhead = async (
   app: Topo,
-  options: BlazeHttpOptions = {}
+  options: TrailheadHttpOptions = {}
 ): Promise<Hono> => {
   assertValidTopo(app, options.validate === false);
 
@@ -330,8 +330,8 @@ export const blaze = async (
     basePath: options.basePath,
     configValues: options.configValues,
     createContext: options.createContext,
-    layers: options.layers,
-    services: options.services,
+    gates: options.gates,
+    provisions: options.provisions,
   });
 
   if (routesResult.isErr()) {

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/build.ts","./src/index.ts","./src/hono/blaze.ts","./src/hono/index.ts"],"version":"5.9.3"}
+{"root":["./src/build.ts","./src/index.ts","./src/hono/index.ts","./src/hono/trailhead.ts"],"version":"5.9.3"}