@ultimat3/http 20.2.0 → 21.0.0

package/CLAUDE.md

@@ -126,6 +126,21 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `logger` loses to the request's own field and stays reachable as `ctx.services['actor']`; the
   context's meaning never depends on what an app named a service. `context.test.ts` pins the
   factory install, the spread and the collision order.
+- **A member's saved locale and zone apply, re-resolved after `auth`** (21.0.0). The `locale`
+  stage runs before `auth`, so it resolved from the cookie and `Accept-Language` alone and the
+  `user` rung of `resolveLocale` / `resolveTimeZone` was filled by nothing since 2.0.0. Core's
+  `Actor` now carries `locale?` / `tz?` (the saved preferences, set by whoever authenticates), and
+  the `auth` stage re-runs `resolvePreferences` when either is present — the owners' order, so a
+  locale cookie still beats a saved locale and a saved zone beats the cookie. `member-preferences.test.ts`.
+- **A request's registered services are LAZY and bound to the actor that authenticated**
+  (`request-services.ts`, 21.0.0). The context is built before the `auth` stage names anyone, and
+  core's constructor built every `defineService` factory right there — so every service acted as
+  the anonymous actor for the whole request while `ctx.actor` read the real one: the reference
+  app's like answered 500 `X_ORG_NOT_A_MEMBER` for a member. `createRequestContext` passes core
+  `installServices: false` and `bindRequestServices` turns `ctx.services` and each registered
+  `ctx.<name>` into getters: built on first read, rebuilt only if the actor, locale or tz it closed
+  over changed. One build for a handler; a hook that reads a service before auth gets its own.
+  `request-services.test.ts` drives the real pipeline. Pre-existing since 13.0.0.
 - **The two inbound ids are read BEFORE the context and the span, in `correlation.ts`.** `startSpan`
   resolves its parent from `currentSpanContext()`, which reads `ctx.traceId`, so a `traceparent`
   parsed by a stage arrived one frame after the span's context was already frozen: the caller's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "20.2.0",
+  "version": "21.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.0",
-    "@ultimat3/i18n": "20.2.0",
-    "@ultimat3/schema": "20.2.0",
-    "@ultimat3/time": "20.2.0"
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/i18n": "21.0.0",
+    "@ultimat3/schema": "21.0.0",
+    "@ultimat3/time": "21.0.0"
   }
 }

package/src/context.ts

@@ -24,6 +24,7 @@ import type { AuthzDecision } from './hooks';
 import { readCookie } from './locale';
 import type { PeerIdentity } from './peer-identity';
 import type { RateLimitDecision } from './rate-limit';
+import { bindRequestServices } from './request-services';
 import type { CacheHint, RedirectIntent } from './response';
 import type { Route, RouteParams } from './router';
 
@@ -195,8 +196,11 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
       ? {}
       : { deadlineAt: init.deadlineAt }),
     ...(init.services === undefined ? {} : { services: init.services }),
+    // Registered services are bound lazily below, to the actor the `auth` stage authenticates —
+    // built here they would close over the anonymous actor for the whole request.
+    installServices: false,
   });
-  return {
+  const ctx: RequestContext = {
     ...base,
     // Everything below is either this package's own or a core member the PIPELINE rewrites: the
     // mutable slots are re-declared here so a stage can write them, and they must therefore be
@@ -227,6 +231,8 @@ export const createRequestContext = (init: RequestContextInit): RequestContext =
     response: undefined,
     error: undefined,
   };
+  bindRequestServices(ctx, init.services ?? {});
+  return ctx;
 };
 
 /**

package/src/error-map.ts

@@ -401,6 +401,19 @@ export const ERROR_STATUS = {
   // the answer. Deliberately not 409 — that spelling asks the client to reconcile and try again,
   // and a fenced answer has nothing to reconcile against.
   X_SUPERSEDED: 499,
+  // Plan 101's client seam. A typed call made from a server handler: an upstream that gave no usable
+  // answer is 502, the fence is `X_SUPERSEDED`'s twin. The rest are browser-side or declaration-time
+  // refusals no request carries; their rows keep the table closed.
+  X_CLIENT_TRANSPORT_FAILED: 502,
+  X_CLIENT_RECORD_ENVELOPE_INVALID: 502,
+  X_CLIENT_SCOPE_CHANGED: 499,
+  X_CHANNEL_DECLARATION_INVALID: 500,
+  X_LOCAL_STORE_UNAVAILABLE: 500,
+  X_MUTATOR_CLOCK_MISSING: 500,
+  X_REALTIME_UNINSTALLED: 500,
+  X_RECORD_KEY_MISSING: 500,
+  X_RECORD_REJECTED: 500,
+  X_SYNC_UNCONFIGURED: 500,
   X_INTERNAL: 500,
   // The keys are LITERAL — deliberately not `Readonly<Record<string, number>>`, which is what the
   // annotation used to say. This table is the closed one, so `ERROR_STATUS.X_QUERY_NOT_PAGABLE`

package/src/request-services.ts

@@ -0,0 +1,65 @@
+// A request's registered services (`defineService`), bound to the actor that AUTHENTICATED. The
+// context exists before the `auth` stage names anyone, so core's constructor is told to install
+// nothing and every registered name becomes a lazy member here instead: built on first read, and
+// built again only if the actor, locale or time zone it closed over has since changed.
+
+import type { CtxFacts, ServiceBag } from '@ultimat3/core';
+import { installedServices, registeredServiceNames } from '@ultimat3/core';
+import type { RequestContext } from './context';
+
+interface Built {
+  readonly actor: CtxFacts['actor'];
+  readonly locale: string;
+  readonly tz: string;
+  readonly bag: ServiceBag;
+}
+
+/**
+ * Makes `ctx.services` and each registered `ctx.<name>` lazy. Non-enumerable, so building the
+ * preview a factory reads — the context's facts, no sibling service — never reads one back.
+ * An explicit service (`init.services`) stays what it was: a caller's mock overrides the real one.
+ */
+export function bindRequestServices(ctx: RequestContext, explicit: ServiceBag): void {
+  let built: Built | undefined;
+  const bag = (): ServiceBag => {
+    if (
+      built !== undefined &&
+      built.actor === ctx.actor &&
+      built.locale === ctx.locale &&
+      built.tz === ctx.tz
+    ) {
+      return built.bag;
+    }
+    const preview: CtxFacts = Object.freeze({
+      ...explicit,
+      requestId: ctx.requestId,
+      traceId: ctx.traceId,
+      actor: ctx.actor,
+      locale: ctx.locale,
+      tz: ctx.tz,
+      buildId: ctx.buildId,
+      role: ctx.role,
+      clock: ctx.clock,
+      now: ctx.now,
+      logger: ctx.logger,
+      signal: ctx.signal,
+      deadlineAt: ctx.deadlineAt,
+      services: explicit,
+    });
+    const next = Object.freeze({ ...installedServices(preview), ...explicit });
+    built = { actor: ctx.actor, locale: ctx.locale, tz: ctx.tz, bag: next };
+    return next;
+  };
+  Object.defineProperty(ctx, 'services', { get: bag, enumerable: false, configurable: true });
+  for (const name of registeredServiceNames()) {
+    // Already an own property: a framework field (which keeps its meaning whatever an app named a
+    // service — core's rule) or an explicit `init.services` entry, which core's constructor spread
+    // onto the context and which overrides the registered factory of the same name.
+    if (Object.hasOwn(ctx, name)) continue;
+    Object.defineProperty(ctx, name, {
+      get: () => bag()[name],
+      enumerable: false,
+      configurable: true,
+    });
+  }
+}

package/src/request.ts

@@ -167,7 +167,20 @@ export class UltimateRequest {
       throw bodyInvalid(this.pathname, [`body is ${declared} bytes, limit is ${limit}`]);
     }
     const type = contentTypeOf(this.raw);
-    if (type === '' || declared === 0) return undefined;
+    // An EMPTY form is a form with no fields, never "no input": a button-only `<form>` posts
+    // `content-length: 0`, and reading that as `undefined` failed every schema with 400.
+    const form = type === 'application/x-www-form-urlencoded' || type === 'multipart/form-data';
+    if (type === '') return undefined;
+    // A multipart body is only a FORM with the boundary its header must announce. Checked before
+    // the empty-form shortcut below, so a zero-length body cannot launder a malformed header into
+    // `{}` — without it the parser would have refused, and an empty body must refuse the same.
+    if (
+      type === 'multipart/form-data' &&
+      !/;\s*boundary=[^;\s]/i.test(this.header('content-type') ?? '')
+    ) {
+      throw bodyInvalid(this.pathname, ['multipart/form-data without a boundary parameter']);
+    }
+    if (declared === 0) return form ? {} : undefined;
 
     // One capped read for every content type, multipart included: the parser runs on bytes this
     // process already agreed to hold, never on a stream it hands to the runtime unbounded.
@@ -175,7 +188,7 @@ export class UltimateRequest {
     if ('over' in read) {
       throw bodyInvalid(this.pathname, [`body is at least ${read.over} bytes, limit is ${limit}`]);
     }
-    if (read.bytes.byteLength === 0) return undefined;
+    if (read.bytes.byteLength === 0) return form ? {} : undefined;
 
     if (type === 'multipart/form-data') {
       try {

package/src/stages.ts

@@ -188,16 +188,7 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
      * get one answer in the framework rather than one per package.
      */
     locale: (request, ctx) => {
-      const cookies = request.header('cookie');
-      ctx.locale = resolveLocale({
-        header: request.header('accept-language'),
-        cookie: readCookie(cookies, config.locale.cookie),
-      }).locale;
-      ctx.tz = resolveTimeZone({
-        cookie: readCookie(cookies, config.tz.cookie),
-        header: request.header(config.tz.header),
-      }).zone;
-      ctx.headers.set('content-language', ctx.locale);
+      resolvePreferences(request, ctx, config);
       return undefined;
     },
 
@@ -206,6 +197,11 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         // 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();
+        // The `user` rung the `locale` stage could not know: re-resolved through the same owners,
+        // so a cookie the reader chose still beats a saved locale where i18n's order says it does.
+        if (ctx.actor.locale !== undefined || ctx.actor.tz !== undefined) {
+          resolvePreferences(request, ctx, config);
+        }
       }
       if (ctx.route?.meta.auth === 'required' && isAnonymous(ctx.actor)) {
         throw unauthenticated(ctx.url.pathname);
@@ -465,3 +461,28 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
   };
   return table;
 };
+
+/**
+ * `ctx.locale`, `ctx.tz` and `content-language` from every source the request carries — the
+ * cookie, the header and, once `auth` has run, the actor's saved preference. One function for both
+ * stages, so the order is always the owners' (`resolveLocale`, `resolveTimeZone`) and never this
+ * file's.
+ */
+function resolvePreferences(
+  request: UltimateRequest,
+  ctx: RequestContext,
+  config: HttpConfig,
+): void {
+  const cookies = request.header('cookie');
+  ctx.locale = resolveLocale({
+    header: request.header('accept-language'),
+    cookie: readCookie(cookies, config.locale.cookie),
+    user: ctx.actor.locale,
+  }).locale;
+  ctx.tz = resolveTimeZone({
+    cookie: readCookie(cookies, config.tz.cookie),
+    header: request.header(config.tz.header),
+    user: ctx.actor.tz ?? null,
+  }).zone;
+  ctx.headers.set('content-language', ctx.locale);
+}