@ultimat3/http 0.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "0.0.1",
+  "version": "1.1.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "^0.0.1",
-    "@ultimat3/schema": "^0.0.1"
+    "@ultimat3/core": "1.1.0",
+    "@ultimat3/schema": "1.1.0"
   }
 }

package/src/config.ts

@@ -50,13 +50,17 @@ export interface HttpConfigInput {
   readonly rateLimit?: Partial<RateLimitConfig>;
 }
 
-/** `basePath` is stripped before matching so route paths never encode the mount point. */
+/**
+ * `basePath` is stripped before matching so route paths never encode the mount point.
+ * Matching is on a segment boundary: a mount at `/api` owns `/api` and `/api/...` but
+ * never `/apix`, which is a different route whose first three characters happen to agree.
+ */
 export const stripBasePath = (pathname: string, basePath: string): string => {
   if (basePath === '/' || basePath === '') return pathname;
   const prefix = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
-  if (!pathname.startsWith(prefix)) return pathname;
-  const rest = pathname.slice(prefix.length);
-  return rest.length === 0 ? '/' : rest;
+  if (pathname === prefix) return '/';
+  if (!pathname.startsWith(`${prefix}/`)) return pathname;
+  return pathname.slice(prefix.length);
 };
 
 const env = (name: string): string | undefined => {

package/src/context.ts

@@ -1,7 +1,15 @@
 // The per-request context. It is created by the pipeline before any user code runs
 // and published through core's ALS, which is why nothing in the framework has to
 // thread a request object by hand — and why nothing can accidentally skip it.
-import { type Actor, type Ctx, type Role, useContext, uuid } from '@ultimat3/core';
+import {
+  type Actor,
+  anonymousActor,
+  type Ctx,
+  isAnonymous,
+  type Role,
+  useContext,
+  uuid,
+} from '@ultimat3/core';
 import type { HttpConfig } from './config';
 import type { AuthzDecision } from './hooks';
 import type { RateLimitDecision } from './rate-limit';
@@ -29,7 +37,12 @@ export interface RequestContext {
   parentSpanId: string | null;
   params: RouteParams;
   route: Route | undefined;
-  actor: Actor | null;
+  /**
+   * Never null: core models "nobody" as the anonymous actor, and `asCtx` publishes this very
+   * object through ALS — so a null here would reach every `ctx.actor` reader in the framework
+   * as a contract violation that only shows up on the first unauthenticated request.
+   */
+  actor: Actor;
   locale: string;
   tz: string;
   buildId: string | null;
@@ -66,7 +79,7 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
   parentSpanId: null,
   params: {},
   route: undefined,
-  actor: null,
+  actor: anonymousActor(),
   locale: init.config.locale.default,
   tz: init.config.tz.default,
   buildId: null,
@@ -101,5 +114,6 @@ export interface ActorView {
   readonly orgId?: string | null;
 }
 
+/** Anonymous reads as "no actor" so the rate limiter keys an unauthenticated call by IP. */
 export const actorView = (actor: Actor | null): ActorView | null =>
-  actor === null ? null : (actor as unknown as ActorView);
+  actor === null || isAnonymous(actor) ? null : (actor as unknown as ActorView);

package/src/error-map.ts

@@ -29,7 +29,12 @@ export const ERROR_STATUS: Readonly<Record<string, number>> = {
   // @ultimat3/policy
   X_POLICY_MISSING: 500,
   X_PERMISSION_UNKNOWN: 500,
+  // @ultimat3/seo — a transform query the caller wrote, so the caller is the one who can fix it.
+  X_IMAGE_QUERY_INVALID: 400,
   // @ultimat3/core
+  // The caller asked for a format the pipeline cannot produce (`?f=avif`): the request names an
+  // unsupported representation, which is 415 — not a 500, which would blame the server for it.
+  X_IMAGE_UNSUPPORTED: 415,
   X_NOT_IMPLEMENTED: 501,
   X_TIMEOUT: 504,
   X_ABORTED: 499,
@@ -68,7 +73,12 @@ const asRecord = (value: unknown): Record<string, unknown> =>
 export const factsOf = (error: unknown): ErrorFacts => {
   const record = asRecord(error);
   const code = str(record, 'code') ?? 'X_INTERNAL';
+  // The error's own title first: every `UltimateError` resolves one from the code registry at
+  // construction, so this renders the OWNING package's title — including the codes http only
+  // borrows (`X_FORBIDDEN` is policy's, `X_UNAUTHENTICATED` is auth's) and so cannot title itself.
+  // Falling through to `message` here shipped the code twice: `X_FORBIDDEN: policy denied… — …`.
   const title =
+    str(record, 'title') ??
     HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES] ??
     str(record, 'message') ??
     'unhandled server error';

package/src/errors.ts

@@ -1,14 +1,13 @@
 // The HTTP layer's stable error codes. Every throw in this package goes through a
 // factory here so a code, a cause and an exact fix always travel together — the
 // terminal, the dev overlay and `--json` all render the same three strings.
-import { UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 
-export const HTTP_ERROR_CODES = [
+/** Codes this package declares and owns. */
+export const HTTP_OWNED_ERROR_CODES = [
   'X_ROUTE_NOT_FOUND',
   'X_METHOD_NOT_ALLOWED',
   'X_BODY_INVALID',
-  'X_UNAUTHENTICATED',
-  'X_FORBIDDEN',
   'X_RATE_LIMITED',
   'X_BUILD_SKEW',
   'X_ROUTE_CONFLICT',
@@ -16,15 +15,25 @@ export const HTTP_ERROR_CODES = [
   'X_PIPELINE_NO_RESPONSE',
 ] as const;
 
+/**
+ * Codes this package throws but does NOT own. `X_FORBIDDEN` belongs to `@ultimat3/policy` and
+ * `X_UNAUTHENTICATED` to `@ultimat3/auth`; registering either here would throw
+ * `X_ERROR_CODE_DUPLICATE` at import. No titles for them either — the owner writes the one title
+ * every surface renders, and a copy kept here is a copy that goes stale without anything failing.
+ */
+export const HTTP_BORROWED_ERROR_CODES = ['X_UNAUTHENTICATED', 'X_FORBIDDEN'] as const;
+
+/** Every code http can throw: the ones it owns plus the two it borrows. */
+export const HTTP_ERROR_CODES = [...HTTP_OWNED_ERROR_CODES, ...HTTP_BORROWED_ERROR_CODES] as const;
+
+export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
 export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
 
-/** Human title per code. Kept next to the codes so one edit updates every surface. */
-export const HTTP_ERROR_TITLES: Readonly<Record<HttpErrorCode, string>> = {
+/** Human title per owned code. Kept next to the codes so one edit updates every surface. */
+export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_ROUTE_NOT_FOUND: 'no route matches this request',
   X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
   X_BODY_INVALID: 'request body failed its schema',
-  X_UNAUTHENTICATED: 'route requires an authenticated actor',
-  X_FORBIDDEN: 'policy denied this actor',
   X_RATE_LIMITED: 'rate limit exhausted for this key',
   X_BUILD_SKEW: 'client build id does not match the server build id',
   X_ROUTE_CONFLICT: 'two routes claim the same path',
@@ -32,10 +41,19 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpErrorCode, string>> = {
   X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
 };
 
+// Registered at module load, unconditionally, in one call, so core's registry renders OUR title
+// everywhere. Without this the registry humanises the code (`X_BUILD_SKEW` → "build skew"); with a
+// presence guard, a package that claimed one of these first would silently keep its own title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(HTTP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
 const docsFor = (code: HttpErrorCode): string => `https://ultimate.dev/errors/${code}`;
 
 /** Base class for every error this package throws. Never throw a bare `Error`. */
 export class HttpError extends UltimateError {
+  override readonly name = 'HttpError';
+
   constructor(init: { code: HttpErrorCode; cause: string; fix: string }) {
     super({
       code: init.code,
@@ -43,7 +61,6 @@ export class HttpError extends UltimateError {
       fix: init.fix,
       docs: docsFor(init.code),
     });
-    this.name = 'HttpError';
   }
 }
 

package/src/pipeline.ts

@@ -2,7 +2,7 @@
 // this order IS the framework's guarantee: context before user code, identity before
 // rate limiting, validation before authz, authz before the handler. Nothing can skip a
 // stage, and the array is exported so `/_x` renders it and pipeline.test.ts asserts it.
-import { logger, runWithContext, withSpan } from '@ultimat3/core';
+import { anonymousActor, isAnonymous, logger, runWithContext, withSpan } from '@ultimat3/core';
 import { defineHttpConfig, type HttpConfig, stripBasePath } from './config';
 import { actorView, asCtx, createRequestContext, elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
@@ -95,7 +95,7 @@ export const PIPELINE_STAGES: readonly StageDoc[] = [
   {
     name: 'authz',
     phase: 'request',
-    why: 'the last gate: one policy, evaluated here exactly as it is in jobs, live queries and MCP tools',
+    why: 'the last gate, and only for a route whose policy nothing downstream evaluates: one policy, decided here exactly as it is in jobs, live queries and MCP tools. A route marked enforcedBy: handler is skipped, because its handler holds the row this stage cannot load',
   },
   { name: 'handler', phase: 'terminal', why: 'the only stage that is app code' },
   {
@@ -204,9 +204,11 @@ const runners = (deps: PipelineDeps, config: HttpConfig, limiter: RateLimiter) =
 
     auth: async (request, ctx) => {
       if (hooks.authenticate !== undefined) {
-        ctx.actor = await hooks.authenticate(request, ctx);
+        // The hook says "anonymous" with null; the context says it with core's anonymous actor,
+        // because `asCtx` publishes this object as a `Ctx` and `Ctx.actor` is never null.
+        ctx.actor = (await hooks.authenticate(request, ctx)) ?? anonymousActor();
       }
-      if (ctx.route?.meta.auth === 'required' && ctx.actor === null) {
+      if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
         throw unauthenticated(ctx.url.pathname);
       }
       return undefined;
@@ -247,6 +249,10 @@ const runners = (deps: PipelineDeps, config: HttpConfig, limiter: RateLimiter) =
     authz: async (request, ctx) => {
       const route = ctx.route;
       if (route === undefined || route.meta.policy === undefined) return undefined;
+      // The handler owns this route's single evaluation (`RouteMeta.enforcedBy`). Deciding
+      // here as well would be a second authz system holding strictly less than the first —
+      // no row — and it is the one that answers first, so it is the one that would win.
+      if (route.meta.enforcedBy === 'handler') return undefined;
       if (hooks.authorize === undefined) {
         // A declared policy with no evaluator is a wiring bug, and failing open
         // here is exactly how a framework ends up with two authz systems.
@@ -385,7 +391,24 @@ export const createPipeline = (deps: PipelineDeps): Pipeline => {
       // The ALS scope is entered here, before stage 1, so every stage — and everything
       // a handler calls — sees the same context object without threading it by hand.
       return await runWithContext(asCtx(ctx), () =>
-        withSpan(`${ctx.method} ${url.pathname}`, () => execute(request, ctx)),
+        withSpan(
+          `${ctx.method} ${url.pathname}`,
+          async (span) => {
+            const response = await execute(request, ctx);
+            // The root span of every request carried no attributes at all, so an exporter got a
+            // name and a duration and nothing to correlate: which request, which outcome. These
+            // four are what a reader joins on — `x-request-id` off the response, the status the
+            // client saw, and the method/path split out of the span name.
+            span.setAttributes({
+              'http.request_id': ctx.requestId,
+              'http.method': ctx.method,
+              'http.route': url.pathname,
+              'http.status_code': response.status,
+            });
+            return response;
+          },
+          { kind: 'server' },
+        ),
       );
     },
   };

package/src/request.ts

@@ -55,7 +55,8 @@ export class UltimateRequest {
     return this.ctx.params;
   }
 
-  get actor(): Actor | null {
+  /** Never null — an unauthenticated call carries core's anonymous actor, same as `Ctx`. */
+  get actor(): Actor {
     return this.ctx.actor;
   }
 

package/src/router.ts

@@ -42,6 +42,18 @@ export interface RouteMeta {
   readonly auth: 'public' | 'required';
   /** Name of the policy the authz stage must satisfy. Resolved by tier 3. */
   readonly policy?: string;
+  /**
+   * Which layer evaluates `policy`. `'pipeline'` — the default, and what a page route
+   * wants — means the `authz` stage decides through `ServerHooks.authorize`. `'handler'`
+   * means the handler is the one evaluation and the stage must not pre-judge.
+   *
+   * An action route says `'handler'` because `invoke` loads the row a row-level rule
+   * decides about, and the stage cannot: deciding here too would evaluate the same policy
+   * with `row: null`, deny the row's own author, and never reach the evaluation that had
+   * the row. Two authz systems is how every Meteor-like framework died — this field is
+   * which one is the system.
+   */
+  readonly enforcedBy?: 'pipeline' | 'handler';
   /** Validated in the body stage; also what the OpenAPI/MCP emitters read. */
   readonly input?: Schema;
   readonly render?: RenderMode;
@@ -216,6 +228,8 @@ export interface RouteDescription {
   readonly params: readonly string[];
   readonly auth: 'public' | 'required';
   readonly policy: string | null;
+  /** Named, not inferred: a policy with no stated evaluator reads as an unguarded one. */
+  readonly enforcedBy: 'pipeline' | 'handler';
   readonly render: RenderMode | null;
   readonly rateLimit: string | null;
   readonly tags: readonly string[];
@@ -240,6 +254,7 @@ export const describeRoutes = (table: RouteTable): readonly RouteDescription[] =
       params: paramsOf(route.path),
       auth: route.meta.auth,
       policy: route.meta.policy ?? null,
+      enforcedBy: route.meta.enforcedBy ?? 'pipeline',
       render: route.meta.render ?? null,
       rateLimit: route.meta.rateLimit ?? null,
       tags: route.meta.tags ?? [],

package/src/server.ts

@@ -2,8 +2,19 @@
 // context, tracing and authz must be impossible to skip — a route is a data
 // declaration, never a chance to hand-roll a request handler.
 
-import type { Role } from '@ultimat3/core';
-import { logger, onShutdown } from '@ultimat3/core';
+import type { HealthPayload, HealthState, Role } from '@ultimat3/core';
+import {
+  beginWork,
+  configureLifecycle,
+  drain,
+  healthzPayload,
+  lifecycleState,
+  logger,
+  markListening,
+  markReady,
+  onShutdown,
+  readyzPayload,
+} from '@ultimat3/core';
 import type { Server } from 'bun';
 import { defineHttpConfig, type HttpConfig } from './config';
 import { serverNotStarted } from './errors';
@@ -13,7 +24,8 @@ import { createPipeline, type Pipeline } from './pipeline';
 import { json } from './response';
 import { createRouter, describeRoutes, type Route, type RouteDescription } from './router';
 
-export type LifecycleState = 'idle' | 'starting' | 'ready' | 'draining' | 'stopped';
+/** Core owns the state machine; this alias exists so callers need one import. */
+export type LifecycleState = HealthState;
 
 /** `Server` is generic over its websocket payload; the `web` role does not use one. */
 type BunServer = Server<unknown>;
@@ -38,7 +50,8 @@ export interface ServerHandle {
   url(): string;
   describe(): readonly RouteDescription[];
   start(): ServerHandle;
-  stop(options?: { readonly timeoutMs?: number }): Promise<void>;
+  /** Runs core's three-phase drain. The deadline is `config.drainTimeoutMs`. */
+  stop(): Promise<void>;
   /**
    * Runs one request through the entire lifecycle with no socket. This is the
    * supported way to test routes: there is no second, "lighter" code path.
@@ -59,35 +72,36 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     ...(options.middleware === undefined ? {} : { middleware: options.middleware }),
   });
 
-  let state: LifecycleState = 'idle';
-  let server: BunServer | undefined;
-  let inflight = 0;
+  // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget.
+  configureLifecycle({ deadlineMs: config.drainTimeoutMs });
 
-  const health = (): Response =>
-    json(
-      { status: 'ok', role, state, buildId: config.buildId },
-      {
-        headers: { 'cache-control': 'no-store' },
-      },
-    );
+  let server: BunServer | undefined;
+  let unregister: (() => void) | undefined;
+  let unregisterClose: (() => void) | undefined;
+  let stopListening: (() => void) | undefined;
 
-  // Readiness is the only thing a load balancer reads, so it must flip to 503 the
-  // instant we start draining — before the socket closes, so in-flight work finishes.
-  const ready = (): Response =>
+  /**
+   * Core owns the health state, the in-flight count and the drain deadline so every
+   * role reports identically. `HealthPayload` is `{ ok, status, body }` — core stays
+   * HTTP-free and hands us the status code as data, which we render here.
+   */
+  const healthResponse = (payload: HealthPayload): Response =>
     json(
-      { status: state === 'ready' ? 'ready' : state, role, buildId: config.buildId },
-      { status: state === 'ready' ? 200 : 503, headers: { 'cache-control': 'no-store' } },
+      { ...payload.body, role },
+      { status: payload.status, headers: { 'cache-control': 'no-store' } },
     );
 
   const dispatch = async (request: Request, socket?: BunServer): Promise<Response> => {
-    inflight += 1;
+    // beginWork() is what makes the `inflight` drain phase correct: core cannot finish
+    // in-flight work it does not know about.
+    const done = beginWork();
     try {
       return await pipeline.handle(request, {
         role,
         ip: socket?.requestIP(request)?.address ?? null,
       });
     } finally {
-      inflight -= 1;
+      done();
     }
   };
 
@@ -110,7 +124,7 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     role,
     config,
     pipeline,
-    state: () => state,
+    state: () => lifecycleState(),
     url: () => {
       if (server === undefined) throw serverNotStarted('url()');
       return server.url.origin;
@@ -118,7 +132,6 @@ export const createServer = (options: ServerOptions): ServerHandle => {
     describe: () => describeRoutes(table),
     fetch: (request) => dispatch(request),
     start() {
-      state = 'starting';
       server = Bun.serve({
         port: config.port,
         hostname: config.hostname,
@@ -127,28 +140,51 @@ export const createServer = (options: ServerOptions): ServerHandle => {
           ...nativeRoutes(),
           // Health endpoints answer outside the pipeline on purpose: a draining or
           // rate-limited process must still be able to say what it is doing.
-          '/healthz': () => health(),
-          '/readyz': () => ready(),
+          '/healthz': () => healthResponse(healthzPayload()),
+          '/readyz': () => healthResponse(readyzPayload()),
         },
         fetch: (request, socket) => dispatch(request, socket),
       });
-      state = 'ready';
+
+      // Tell core which socket we opened. A request to it is this process calling itself,
+      // so the test seal can let it through without an allowlist entry per random port.
+      stopListening = markListening(server.url.origin);
+
+      // 'accept' runs first on SIGTERM: readyz flips to 503 here, while the socket is
+      // still open, so the load balancer stops sending new work before we close it.
+      unregister = onShutdown(
+        `http:${role}`,
+        async () => {
+          await server?.stop(false);
+        },
+        { phase: 'accept' },
+      );
+      // 'close' runs after core has waited out the in-flight phase.
+      unregisterClose = onShutdown(
+        `http:${role}:close`,
+        async () => {
+          await server?.stop(true);
+          server = undefined;
+          stopListening?.();
+        },
+        { phase: 'close' },
+      );
+
+      markReady();
       logger.info(`ultimate ${role} listening on ${server.url.origin}`);
-      // SIGTERM handling belongs to core so every role drains identically.
-      onShutdown(() => handle.stop());
       return handle;
     },
-    async stop(stopOptions) {
-      if (state === 'stopped') return;
-      state = 'draining';
-      const deadline = Date.now() + (stopOptions?.timeoutMs ?? config.drainTimeoutMs);
-      while (inflight > 0 && Date.now() < deadline) await Bun.sleep(25);
-      if (inflight > 0) {
-        logger.warn(`ultimate ${role} draining timed out with ${inflight} in-flight requests`);
-      }
-      await server?.stop(true);
+    async stop() {
+      if (server === undefined) return;
+      // Delegate to core so a manual stop() and a real SIGTERM take the identical
+      // three-phase path. The drain deadline is core's, not ours.
+      await drain('manual');
+      unregister?.();
+      unregisterClose?.();
+      // Idempotent: the close hook already released, unless the drain deadline cut it short.
+      stopListening?.();
+      stopListening = undefined;
       server = undefined;
-      state = 'stopped';
       logger.info(`ultimate ${role} stopped`);
     },
   };

package/src/validate.ts

@@ -1,5 +1,5 @@
 // Validation goes through the Standard Schema interface, never through a vendor
-// API, so ArkType (`t`) is a default rather than a dependency of the HTTP layer.
+// API, so `t` is the schema layer's shipped default rather than a dependency of the HTTP layer.
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 
 export type Schema<Out = unknown> = StandardSchemaV1<unknown, Out>;