@ultimat3/http 30.7.0 → 30.9.0

package/CLAUDE.md

@@ -21,9 +21,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   `trustedProxyHops`, `rateLimit.scope`) is a type error where an app writes it. `mergeHttpConfig`
   merges `security.csp.extend` per directive. `type-pins.ts` refuses a key on `HttpConfig` missing
   from `HttpConfigInput`.
-- **No drain deadline here**: `drain.deadlineMs` is the one budget (core, per role). Key
-  `drainTimeoutMs` (deleted 25.0.0) is `X_CONFIG_INVALID` via `refuseDeletedHttpKeys`.
-  **`ServerOptions.drain`** passes only `readinessGraceMs`, and only when declared.
+- **No drain deadline here**: `drain.deadlineMs` is the one budget (core, per role); the deleted
+  key and `ServerOptions.drain`: `docs/history/http.md#no-drain-deadline`.
 - **`cors.origins: ['*']` with `credentials: true`, or `'null'` in the list, is `X_CORS_CONFIG_INVALID`.** A refused origin
   still gets `vary: origin`.
 - **`DEFAULT_CORS` is what `clientTransport` sends and reads**, off core's constants; `cors.test.ts` observes the transport's real traffic, so a new header fails it. `date` alone stays hidden: this server writes delta-seconds. An app's list replaces the default whole.
@@ -219,8 +218,8 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `context.ts` | `RequestContext` (core's `Ctx` plus the request's own), composed from `ctxOf`, the single `Ctx` adapter (`asCtx`) and the inbound-header readers |
 | `redirect.ts` | the intent slot a handler that cannot return a `Response` fills |
 | `set-cookie.ts` | `setCookie`/`deleteCookie`: one line each onto `ctx.headers` |
-| `object-response.ts` | `objectResponse`, the one answer for an object held elsewhere, structural (no storage import); `notModified`, the one `if-none-match` answer |
-| `stored-object-headers.ts` | inline only for raster images, audio, video; else `attachment` + `sandbox`. Private to `objectResponse` |
+| `object-response.ts` | `objectResponse`: an object held elsewhere, structural; `notModified`: the `if-none-match` answer |
+| `stored-object-headers.ts` | inline only for raster images, audio, video; else `attachment` + `sandbox` (private) |
 | `auth-redirect.ts` | where an unauthenticated browser goes, and where it comes back to |
 | `cache-policy.ts` | the default `CacheHint` for a route that declared none — route AND actor — and the review of a declared one (`reviewedHint`) |
 | `error-log-level.ts` | the level of the `error-map` stage's one line: `error` for 5xx, `warn` for 401/403/429, `info` for the rest |
@@ -245,6 +244,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
 | `app-config.ts` | the app's own HTTP declaration (`configureHttp`) and the layering that keeps a boot fact above it |
 | `compress.ts` | the `compress` stage's rule: which answers leave gzipped |
 | `compress-read.ts` | the one body read that rule does: counted, deadline-bound, replayable |
+| `request-as.ts` | `withRequestAs`: an exercise entry's `request` (cookies, headers) as an inbound request, for `x exercise` and the contract step |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "30.7.0",
+  "version": "30.9.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "keywords": [
     "ultimate",
@@ -45,9 +45,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.7.0",
-    "@ultimat3/i18n": "30.7.0",
-    "@ultimat3/schema": "30.7.0",
-    "@ultimat3/time": "30.7.0"
+    "@ultimat3/core": "30.9.0",
+    "@ultimat3/i18n": "30.9.0",
+    "@ultimat3/schema": "30.9.0",
+    "@ultimat3/time": "30.9.0"
   }
 }

package/src/error-map-http.ts

@@ -94,4 +94,6 @@ export const HTTP_ERROR_STATUS = {
   X_MCP_IDEMPOTENCY_KEY_SHADOWED: 500,
   X_ROUTE_POST_INVALID: 500,
   X_ROUTE_NAVIGATION_INVALID: 500,
+  // @ultimat3/http — an exercise entry's request is not one a browser could send
+  X_EXERCISE_REQUEST_INVALID: 500,
 } satisfies Readonly<Record<string, number>>;

package/src/error-titles.ts

@@ -38,6 +38,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_WEBHOOK_SIGNATURE_STALE',
   'X_BEARER_MOUNT_INVALID',
   'X_RATE_LIMIT_STORE_TIMEOUT',
+  'X_EXERCISE_REQUEST_INVALID',
 ] as const;
 
 export type HttpOwnedErrorCode = (typeof HTTP_OWNED_ERROR_CODES)[number];
@@ -73,6 +74,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_WEBHOOK_SIGNATURE_STALE: 'the inbound webhook is signed correctly and is too old to accept',
   X_BEARER_MOUNT_INVALID: 'a bearer mount declaration cannot be served as written',
   X_RATE_LIMIT_STORE_TIMEOUT: 'the shared rate-limit store did not answer inside its own deadline',
+  X_EXERCISE_REQUEST_INVALID: "an exercise entry's request is not one a browser could send",
 };
 
 // Registered at module load, unconditionally, in one call, so core's registry renders OUR title

package/src/index.ts

@@ -201,6 +201,8 @@ export { RATE_LIMIT_STORE_DEADLINE_MS } from './rate-limit-store-deadline';
 export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
 export { UltimateRequest } from './request';
+export type { ExerciseRequest, ExerciseRequestOption } from './request-as';
+export { withRequestAs } from './request-as';
 export type { RequestFacts, RequestFactsInput } from './request-facts';
 export { requestFacts } from './request-facts';
 export type { CacheHint, RedirectIntent, RedirectStatus } from './response';

package/src/request-as.ts

@@ -0,0 +1,118 @@
+// A test-time call as an HTTP request reaches it: a fresh request, an actor seated on it, and the
+// cookies and headers an exercise entry declares. Here, below action, query and testing, because
+// the contract step and `x exercise` both make this call and one build of it is the only one.
+
+import type { Actor } from '@ultimat3/core';
+import {
+  anonymousActor,
+  renderCauseValue,
+  renderFixLiteral,
+  runWithContext,
+  UltimateError,
+  useContext,
+  withChildContext,
+} from '@ultimat3/core';
+import { defineHttpConfig } from './config';
+import { asCtx, requestContext } from './context';
+
+/** One exercise call's inbound request: `cookies` become its `Cookie:` header, never `headers`. */
+export interface ExerciseRequest {
+  readonly cookies?: Readonly<Record<string, string>>;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/** The request, or how to build it for the actor a call runs as (`null`: signed out). */
+export type ExerciseRequestOption =
+  | ExerciseRequest
+  | ((actor: Actor | null) => ExerciseRequest | Promise<ExerciseRequest>);
+
+/** Where these requests say they came from: no host an app serves, and never sent. */
+const EXERCISE_ORIGIN = 'https://exercise.test';
+
+/** RFC 6265 `cookie-name` is an RFC 9110 `token`: a name outside it no browser sends. */
+const COOKIE_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+function refuse(name: string, why: string): never {
+  throw new UltimateError({
+    code: 'X_EXERCISE_REQUEST_INVALID',
+    cause: `defineExercise() gives ${renderCauseValue(name)} a request ${why}`,
+    fix: `defineExercise({ ${renderFixLiteral(name, '<name>')}: { request: { cookies: { <token>: '<value>' }, headers: { '<x-name>': '<value>' } } } })   # in apps/web/exercise.ts — a cookie goes in cookies, never a Cookie header`,
+    meta: { name },
+  });
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * The declared request as inbound headers. Each cookie value is percent-encoded, which
+ * `useRequestCookie` (core's `readCookie`) inverts exactly: the value declared is the value read.
+ */
+function inboundHeaders(name: string, declared: unknown): Headers {
+  if (!isRecord(declared)) return refuse(name, 'that is not an object of cookies and headers');
+  const { cookies = {}, headers = {} } = declared;
+  if (!isRecord(cookies) || !isRecord(headers)) {
+    return refuse(name, 'whose cookies or headers is not an object of strings');
+  }
+  const inbound = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === 'cookie') return refuse(name, 'with a Cookie header');
+    if (typeof value !== 'string') return refuse(name, `whose header ${key} is not a string`);
+    try {
+      inbound.set(key, value);
+    } catch {
+      return refuse(name, `whose header ${renderCauseValue(key)} Headers refuses`);
+    }
+  }
+  const pairs = Object.entries(cookies).map(([key, value]) => {
+    if (!COOKIE_NAME.test(key)) return refuse(name, `naming cookie ${renderCauseValue(key)}`);
+    if (typeof value !== 'string') return refuse(name, `whose cookie ${key} is not a string`);
+    return `${key}=${encodeURIComponent(value)}`;
+  });
+  if (pairs.length > 0) inbound.set('cookie', pairs.join('; '));
+  return inbound;
+}
+
+/**
+ * `fn` inside a fresh request as `actor`: a POST to `name`, its rate limits process-scoped,
+ * carrying `request` (none: no cookie, no header). A function `request` is awaited first, inside a
+ * bare request as the same actor, so it can mint a session for whoever acts. The actor is ON the
+ * request, so the caller passes `invoke` no `actor` — its impersonation path rebuilds a plain child
+ * context and drops the request's fields. The child is derived first for the services an actor
+ * binds, then the request's fields go over it, as `withAnonymousRequest` does.
+ */
+export async function withRequestAs<T>(
+  name: string,
+  actor: Actor | null,
+  request: ExerciseRequestOption | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const declared: ExerciseRequest | undefined =
+    typeof request === 'function'
+      ? await inRequest(name, actor, new Headers(), () => Promise.resolve(request(actor)))
+      : request;
+  const headers = declared === undefined ? new Headers() : inboundHeaders(name, declared);
+  return inRequest(name, actor, headers, fn);
+}
+
+function inRequest<T>(
+  name: string,
+  actor: Actor | null,
+  requestHeaders: Headers,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const request = requestContext({
+    url: new URL(`/${encodeURIComponent(name)}`, EXERCISE_ORIGIN),
+    method: 'POST',
+    role: 'web',
+    config: defineHttpConfig({ rateLimit: { scope: 'process' } }),
+    requestHeaders,
+  });
+  return runWithContext(asCtx(request), () =>
+    withChildContext({ actor: actor ?? anonymousActor() }, () => {
+      const child = useContext();
+      const scope = { ...child, ...request, actor: child.actor };
+      return runWithContext(asCtx(scope), fn);
+    }),
+  );
+}