@ontrails/http 0.2.0

package/README.md

@@ -0,0 +1,169 @@
+# @ontrails/http
+
+Framework-agnostic HTTP route derivation and Web Fetch request handling for Trails. Pair this package with `@ontrails/hono` when you want Hono portability, or use `@ontrails/http/bun` when you want Bun-native serving without a third-party framework.
+
+## Usage
+
+```typescript
+import { trail, topo, Result } from '@ontrails/core';
+import { surface } from '@ontrails/hono';
+import { z } from 'zod';
+
+const greet = trail('greet', {
+  input: z.object({ name: z.string().describe('Who to greet') }),
+  output: z.object({ message: z.string() }),
+  intent: 'read',
+  implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+});
+
+const graph = topo('myapp', { greet });
+await surface(graph, { port: 3000 });
+```
+
+This starts a Hono-based HTTP server. The `greet` trail becomes `GET /greet?name=...` because its `intent` is `'read'`.
+
+For Bun-native HTTP without Hono, use the Bun-native HTTP binding subpath:
+
+```typescript
+import { surface } from '@ontrails/http/bun';
+
+await surface(graph, { port: 3000 });
+```
+
+`@ontrails/http/bun` uses Bun's native `Bun.serve({ routes })` fast path and keeps the shared Web Fetch handler as the fallback. It requires Bun `>=1.2.3` and does not add a third-party runtime dependency.
+
+## Rendering and runtime binding
+
+The HTTP package follows the surface API naming split:
+
+- `derive*` exports are pure renderings from the topo. Use `deriveHttpRoutes()` for route definitions and `deriveOpenApiSpec()` for the OpenAPI contract.
+- `create*` exports build runtime objects without opening a network boundary.
+  `@ontrails/http/fetch` exports `createRouteHandler()` for one route and
+  `createFetchHandler()` for a full topo dispatcher.
+- `surface()` opens the runtime boundary. `@ontrails/hono` opens an adapter
+  binding to Hono; `@ontrails/http/bun` opens the native Bun HTTP binding.
+
+The shared `@ontrails/http/fetch` kernel owns query/body parsing, content-length validation, public error rendering, diagnostics, request IDs, headers, abort propagation, and webhook verification/parsing behavior. Hono and Bun both consume that kernel so route semantics stay aligned.
+
+For more control, build the routes yourself:
+
+```typescript
+import { deriveHttpRoutes } from '@ontrails/http';
+
+const result = deriveHttpRoutes(graph);
+if (result.isErr()) throw result.error; // ValidationError on route collision
+for (const route of result.value) {
+  console.log(`${route.method} ${route.path} → ${route.trailId}`);
+}
+```
+
+`deriveHttpRoutes` returns `Result<HttpRouteDefinition[], Error>` rather than a bare array. It returns `Result.err(ValidationError)` if two trails derive the same `(method, path)` pair.
+
+OpenAPI is the HTTP surface's persisted client contract rendering:
+
+```typescript
+import { deriveOpenApiSpec } from '@ontrails/http';
+
+const spec = deriveOpenApiSpec(graph, { basePath: '/api' });
+```
+
+`deriveOpenApiSpec()` emits an OpenAPI 3.1 document from the same trail contracts used by `deriveHttpRoutes()`.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `deriveHttpRoutes(graph, options?)` | Build framework-agnostic route definitions from a topo |
+| `deriveOpenApiSpec(graph, options?)` | Generate an OpenAPI 3.1 document for the HTTP surface |
+| `@ontrails/http/fetch` | Shared Web Fetch `createRouteHandler()` and `createFetchHandler()` kernel |
+| `@ontrails/http/bun` | Bun-native `createApp()` and `surface()` binding |
+| `@ontrails/http/testing` | Owner-owned adapter conformance factory for HTTP adapter authors |
+
+## Adapter authoring
+
+HTTP adapter authors should validate adapters through the owner-owned testing subpath instead of copying conformance behavior into each adapter:
+
+```typescript
+import {
+  createHttpAdapterConformanceCases,
+  runConformance,
+} from '@ontrails/http/testing';
+import { myHttpAdapter } from './adapter.js';
+
+runConformance(myHttpAdapter, createHttpAdapterConformanceCases());
+```
+
+The adapter under test provides a `name` and `createApp(graph, options)` method that returns an object with a Web Fetch-compatible `fetch(request)` handler. The conformance cases cover query and body input rendering, validation envelopes, public error redaction, request context, abort propagation, and webhook verification/parsing behavior.
+
+## Route derivation
+
+Trail intent maps directly to HTTP method and input source:
+
+| Trail field | HTTP method | Input source |
+| --- | --- | --- |
+| `intent: 'read'` | `GET` | Query string |
+| `intent: 'write'` | `POST` | JSON body |
+| `intent: 'destroy'` | `DELETE` | JSON body |
+| (none) | `POST` | JSON body |
+
+Trail IDs map to paths: `entity.show` becomes `/entity/show`. Dots become slashes, everything lowercase.
+
+## Collision detection
+
+`deriveHttpRoutes` detects when two trails would produce the same `(method, path)` pair and returns `Result.err(ValidationError)` describing both trail IDs. The `surface()` helper from `@ontrails/hono` throws on collision.
+
+## Resource resolution
+
+Declared resources on each trail are resolved into the context before the implementation receives input.
+
+## Filtering
+
+```typescript
+const result = deriveHttpRoutes(graph, {
+  include: ['entity.**'],
+  exclude: ['dev.**'],
+});
+```
+
+`*` matches one dotted segment and `**` matches any depth. Trails declared with `visibility: 'internal'` stay hidden unless you include their exact trail ID intentionally.
+
+## Request context and abort propagation
+
+The `execute` function on each `HttpRouteDefinition` accepts optional `requestId`, `abortSignal`, and request context arguments. HTTP adapters should pass the request's `AbortSignal` so client disconnects propagate into trail execution, and pass headers in the request context when Bearer auth should resolve into `ctx.permit`.
+
+## `HttpRouteDefinition`
+
+Each route definition produced by `deriveHttpRoutes` includes:
+
+| Field | Type | What it is |
+| --- | --- | --- |
+| `method` | `'GET' \| 'POST' \| 'DELETE'` | HTTP method |
+| `path` | `string` | Derived path (e.g. `/entity/show`) |
+| `trailId` | `string` | The trail ID this route was derived from |
+| `inputSource` | `'query' \| 'body'` | Where to read input |
+| `trail` | `Trail` | The original trail definition |
+| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the trail |
+
+For GET routes on the Hono surface, repeated query keys are passed through as arrays (`?tag=one&tag=two` -> `{ tag: ['one', 'two'] }`) while a single occurrence stays a scalar string. The adapter does not coerce singleton query values into arrays.
+
+GET query values declared as numbers or booleans are converted at the HTTP boundary before schema validation. This includes primitive literals and union or nullable schemas whose non-null branches all resolve to the same primitive kind. Root object unions convert a field only when every branch that has its required fields present explicitly owns the field with the same primitive shape; otherwise the raw value is preserved. This keeps unknown and passthrough fields unchanged without choosing a union branch. Fields authored with Zod coercion receive the raw query value so their authored parser retains the same behavior as direct and library invocation; if any supported union branch for a field uses coercion, the boundary conservatively preserves that field. Numbers use JSON number syntax and must be finite; booleans accept the exact spellings `true` and `false`. Malformed values and the string `null` continue through normal validation and return a `400` response when the authored schema rejects them. Declared strings remain strings. Repeated keys for declared primitive arrays, including homogeneous union or nullable array schemas, apply the same conversion to each element, while a singleton remains a scalar and must satisfy the authored schema as-is.
+
+For versioned trails, query conversion resolves the selected version's input schema. `X-Trails-Version` and `X-Trail-Version` headers take precedence over the `trailVersion` query field, matching execution. If a historical input field conflicts with a layer parameter name rendered for the current version, the boundary preserves raw query strings so it does not guess which schema owns the field.
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/http@0.2.0 @ontrails/hono@0.2.0
+# or, for Bun-native serving:
+bun add --exact @ontrails/http@0.2.0
+```
+
+## Migration
+
+Hono integration now lives in `@ontrails/hono`.
+
+<!-- warden-ignore-next-line -->
+- Replace `import { trailhead } from '@ontrails/http/hono'` with `import { surface } from '@ontrails/hono'`
+- Keep `deriveHttpRoutes()` and the route model imports on `@ontrails/http`

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ontrails/http",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/http"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./bun": "./src/bun.ts",
+    "./fetch": "./src/fetch.ts",
+    "./testing": "./src/testing.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/core": "^0.2.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapters": {
+      "./bun": {
+        "target": "http"
+      }
+    },
+    "adapterTargets": {
+      "http": {
+        "conformance": {
+          "adapterType": "HttpAdapterConformanceAdapter",
+          "casesFactory": "createHttpAdapterConformanceCases",
+          "runner": "runConformance"
+        },
+        "placements": [
+          "extracted",
+          "subpath"
+        ],
+        "testingImport": "@ontrails/http/testing"
+      }
+    }
+  }
+}

package/src/blob-output.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared recognition for BlobRef trail output schemas.
+ *
+ * The runtime handler (`fetch.ts`) and the OpenAPI derivation
+ * (`openapi.ts`) must agree on which routes serve raw bytes, so both
+ * read the same authored fact: the BlobRef marker meta on the trail's
+ * output schema.
+ */
+
+import { BLOB_REF_SCHEMA_META_KEY } from '@ontrails/core';
+
+/**
+ * True when a trail output schema carries the BlobRef marker meta — the
+ * authored fact that selects byte streaming over the JSON envelope on
+ * the HTTP surface and a binary response body in the OpenAPI derivation.
+ */
+export const isBlobOutputSchema = (output: unknown): boolean => {
+  if (typeof output !== 'object' || output === null) {
+    return false;
+  }
+  const maybeMeta = (output as { meta?: () => unknown }).meta;
+  if (typeof maybeMeta !== 'function') {
+    return false;
+  }
+  const meta = maybeMeta.call(output);
+  return (
+    typeof meta === 'object' &&
+    meta !== null &&
+    (meta as Record<string, unknown>)[BLOB_REF_SCHEMA_META_KEY] === true
+  );
+};