@ultimat3/http 0.0.1

package/src/index.ts

@@ -0,0 +1,119 @@
+// The public surface of @ultimat3/http. Explicit, never `export *`: what is not
+// listed here is an implementation detail and may change without a major bump.
+
+export type { HttpConfig, HttpConfigInput } from './config';
+export { defineHttpConfig, stripBasePath } from './config';
+export type { ActorView, RequestContext, RequestContextInit } from './context';
+export {
+  actorView,
+  asCtx,
+  createRequestContext,
+  elapsedMs,
+  useRequestContext,
+} from './context';
+export type { CorsConfig } from './cors';
+export { corsHeaders, DEFAULT_CORS, preflight } from './cors';
+export type { ErrorFacts, ProblemDocument } from './error-map';
+export {
+  DEFAULT_STATUS,
+  ERROR_STATUS,
+  factsOf,
+  renderErrorLines,
+  statusFor,
+  toProblem,
+} from './error-map';
+export type { HttpErrorCode } from './errors';
+export {
+  bodyInvalid,
+  buildSkew,
+  forbidden,
+  HTTP_ERROR_CODES,
+  HTTP_ERROR_TITLES,
+  HttpError,
+  methodNotAllowed,
+  pipelineNoResponse,
+  rateLimited,
+  routeConflict,
+  routeNotFound,
+  serverNotStarted,
+  unauthenticated,
+} from './errors';
+export type { AuthzDecision, ServerHooks } from './hooks';
+export type { LocaleConfig, TimeZoneConfig } from './locale';
+export {
+  DEFAULT_LOCALE_CONFIG,
+  DEFAULT_TZ_CONFIG,
+  isValidTimeZone,
+  negotiateLocale,
+  readCookie,
+  resolveTimeZone,
+} from './locale';
+export type { Middleware } from './middleware';
+export { compose } from './middleware';
+export type { OverlayMeta } from './overlay';
+export { overlayResponse, renderOverlay, wantsOverlay } from './overlay';
+export type {
+  HandleInit,
+  Pipeline,
+  PipelineDeps,
+  Stage,
+  StageDoc,
+  StageName,
+  StagePhase,
+  StageRun,
+} from './pipeline';
+export { createPipeline, PIPELINE_STAGES } from './pipeline';
+export type {
+  Bucket,
+  RateLimitConfig,
+  RateLimitDecision,
+  RateLimiter,
+  RateLimitKeyParts,
+  RateLimitStore,
+} from './rate-limit';
+export {
+  createRateLimiter,
+  DEFAULT_RATE_LIMIT,
+  memoryRateLimitStore,
+  rateLimitKey,
+} from './rate-limit';
+export type { QueryValues } from './request';
+export { UltimateRequest } from './request';
+export type { CacheHint } from './response';
+export {
+  applyCacheHeaders,
+  cacheControl,
+  html,
+  json,
+  NO_STORE,
+  noContent,
+  problem,
+  redirect,
+  stream,
+  text,
+  withHeaders,
+} from './response';
+export type {
+  HttpMethod,
+  MatchResult,
+  RenderMode,
+  Route,
+  RouteDescription,
+  RouteHandler,
+  RouteMeta,
+  RouteParams,
+  RouteTable,
+} from './router';
+export {
+  createRouter,
+  describeRoutes,
+  HTTP_METHODS,
+  matchRoute,
+  normalizePath,
+} from './router';
+export type { SecurityConfig } from './security-headers';
+export { buildCsp, DEFAULT_SECURITY, securityHeaders } from './security-headers';
+export type { LifecycleState, ServerHandle, ServerOptions } from './server';
+export { createServer } from './server';
+export type { InferOutput, Schema, ValidationOutcome } from './validate';
+export { formatIssue, validate, validateSync } from './validate';

package/src/locale.ts

@@ -0,0 +1,109 @@
+// Locale and time zone are resolved once per request, before any handler runs, so
+// no code path can format a date or a number without them. `@ultimat3/i18n` owns
+// catalogs; this file only owns the negotiation of the two request-scoped values.
+
+export interface LocaleConfig {
+  readonly supported: readonly string[];
+  readonly default: string;
+  /** Cookie the client sets when the user picks a locale explicitly. */
+  readonly cookie: string;
+}
+
+export interface TimeZoneConfig {
+  readonly default: string;
+  /** Header the client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+  readonly header: string;
+  readonly cookie: string;
+}
+
+export const DEFAULT_LOCALE_CONFIG: LocaleConfig = {
+  supported: ['en'],
+  default: 'en',
+  cookie: 'x-locale',
+};
+
+export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
+  default: 'UTC',
+  header: 'x-timezone',
+  cookie: 'x-timezone',
+};
+
+export const readCookie = (header: string | null, name: string): string | null => {
+  if (header === null) return null;
+  for (const part of header.split(';')) {
+    const index = part.indexOf('=');
+    if (index === -1) continue;
+    if (part.slice(0, index).trim() !== name) continue;
+    return decodeURIComponent(part.slice(index + 1).trim());
+  }
+  return null;
+};
+
+interface Weighted {
+  readonly tag: string;
+  readonly q: number;
+}
+
+const parseAcceptLanguage = (header: string): readonly Weighted[] =>
+  header
+    .split(',')
+    .map((entry): Weighted => {
+      const [tag = '', ...params] = entry.trim().split(';');
+      const qParam = params.find((p) => p.trim().startsWith('q='));
+      const q = qParam === undefined ? 1 : Number.parseFloat(qParam.trim().slice(2));
+      return { tag: tag.trim().toLowerCase(), q: Number.isFinite(q) ? q : 0 };
+    })
+    .filter((entry) => entry.tag.length > 0 && entry.q > 0)
+    .sort((a, b) => b.q - a.q);
+
+/**
+ * Exact match wins, then primary-subtag match (`de-CH` -> `de`), then the config
+ * default. `*` is treated as "no preference" rather than "any locale" so the
+ * default stays predictable for SEO and cache keys.
+ */
+export const negotiateLocale = (
+  acceptLanguage: string | null,
+  config: LocaleConfig = DEFAULT_LOCALE_CONFIG,
+  explicit?: string | null,
+): string => {
+  const supported = config.supported.map((locale) => locale.toLowerCase());
+  const pick = (candidate: string): string | undefined => {
+    const wanted = candidate.toLowerCase();
+    const exact = supported.indexOf(wanted);
+    if (exact !== -1) return config.supported[exact];
+    const primary = wanted.split('-')[0] ?? wanted;
+    const loose = supported.findIndex((locale) => (locale.split('-')[0] ?? locale) === primary);
+    return loose === -1 ? undefined : config.supported[loose];
+  };
+
+  if (explicit !== undefined && explicit !== null) {
+    const chosen = pick(explicit);
+    if (chosen !== undefined) return chosen;
+  }
+  if (acceptLanguage !== null) {
+    for (const entry of parseAcceptLanguage(acceptLanguage)) {
+      if (entry.tag === '*') break;
+      const chosen = pick(entry.tag);
+      if (chosen !== undefined) return chosen;
+    }
+  }
+  return config.default;
+};
+
+/** A time zone is only accepted if `Intl` can actually format with it. */
+export const isValidTimeZone = (candidate: string): boolean => {
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: candidate }).format(0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const resolveTimeZone = (
+  candidate: string | null,
+  config: TimeZoneConfig = DEFAULT_TZ_CONFIG,
+): string => {
+  if (candidate !== null && candidate.length > 0 && isValidTimeZone(candidate)) return candidate;
+  return config.default;
+};

package/src/middleware.ts

@@ -0,0 +1,24 @@
+// Middleware exists for the one thing the pipeline cannot express: wrapping a
+// handler (timing, transactions, retries). It is deliberately tiny — the ordered
+// pipeline is the blessed extension point, and there is no plugin API before v1.
+import type { RequestContext } from './context';
+import type { UltimateRequest } from './request';
+import type { RouteHandler } from './router';
+
+export type Middleware = (
+  request: UltimateRequest,
+  ctx: RequestContext,
+  next: RouteHandler,
+) => Response | Promise<Response>;
+
+/**
+ * Left-to-right: `compose([a, b])(handler)` runs `a` outermost. Composition is done
+ * once at server start, not per request, so the closure chain is built exactly once.
+ */
+export const compose =
+  (middleware: readonly Middleware[]) =>
+  (handler: RouteHandler): RouteHandler =>
+    middleware.reduceRight<RouteHandler>(
+      (next, current) => (request, ctx) => current(request, ctx, next),
+      handler,
+    );

package/src/overlay.ts

@@ -0,0 +1,106 @@
+// The dev error overlay. It renders the SAME facts object the terminal prints and
+// `--json` emits, so a code/cause/fix string can never differ between the three
+// surfaces. Labels here ("cause", "fix") are protocol strings from the error
+// contract, not UI copy, so they are not routed through the i18n catalog.
+import { factsOf, renderErrorLines, toProblem } from './error-map';
+import { html } from './response';
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+
+export interface OverlayMeta {
+  readonly requestId?: string;
+  readonly method?: string;
+  readonly path?: string;
+  readonly buildId?: string | null;
+}
+
+// Token definitions live here and nowhere else; every rule below uses var().
+const STYLE = `
+:root {
+  --x-bg: #fbfbfd; --x-surface: #ffffff; --x-border: #e3e3ea;
+  --x-text: #1b1b1f; --x-muted: #6b6b76; --x-danger: #b3261e; --x-accent: #2f4fd8;
+  --x-code-bg: #f3f3f7;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --x-bg: #111115; --x-surface: #1a1a20; --x-border: #2e2e38;
+    --x-text: #ececf1; --x-muted: #9b9baa; --x-danger: #ff8a80; --x-accent: #9db2ff;
+    --x-code-bg: #22222b;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; padding: 2rem; background: var(--x-bg); color: var(--x-text);
+  font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+main { max-width: 60rem; margin: 0 auto; }
+.card {
+  background: var(--x-surface); border: 1px solid var(--x-border);
+  border-radius: 8px; padding: 1.25rem 1.5rem; margin-bottom: 1rem;
+}
+h1 { font-size: 1.1rem; margin: 0 0 .25rem; color: var(--x-danger); }
+h2 { font-size: .8rem; margin: 0 0 .5rem; color: var(--x-muted);
+     text-transform: uppercase; letter-spacing: .08em; }
+dl { display: grid; grid-template-columns: 5rem 1fr; gap: .35rem 1rem; margin: 0; }
+dt { color: var(--x-muted); }
+dd { margin: 0; overflow-wrap: anywhere; }
+pre { background: var(--x-code-bg); border-radius: 6px; padding: .75rem;
+      margin: 0; overflow-x: auto; }
+a { color: var(--x-accent); }
+.title { color: var(--x-muted); font-weight: normal; }
+`;
+
+export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string => {
+  const facts = factsOf(error);
+  const problem = toProblem(error, {
+    ...(meta.requestId === undefined ? {} : { requestId: meta.requestId }),
+    ...(meta.path === undefined ? {} : { instance: meta.path }),
+  });
+  const where = `${meta.method ?? ''} ${meta.path ?? ''}`.trim();
+  return `<style>${STYLE}</style>
+<main>
+  <section class="card">
+    <h1>${escapeHtml(facts.code)} <span class="title">${escapeHtml(facts.title)}</span></h1>
+    <dl>
+      <dt>cause</dt><dd>${escapeHtml(facts.cause)}</dd>
+      <dt>fix</dt><dd><code>${escapeHtml(facts.fix)}</code></dd>
+      <dt>docs</dt><dd><a href="${escapeHtml(facts.docs)}">${escapeHtml(facts.docs)}</a></dd>
+      ${where === '' ? '' : `<dt>route</dt><dd>${escapeHtml(where)}</dd>`}
+      ${meta.requestId === undefined ? '' : `<dt>request</dt><dd>${escapeHtml(meta.requestId)}</dd>`}
+      ${
+        meta.buildId === undefined || meta.buildId === null
+          ? ''
+          : `<dt>build</dt><dd>${escapeHtml(meta.buildId)}</dd>`
+      }
+    </dl>
+  </section>
+  <section class="card">
+    <h2>terminal</h2>
+    <pre>${escapeHtml(renderErrorLines(error))}</pre>
+  </section>
+  ${
+    facts.stack === undefined
+      ? ''
+      : `<section class="card"><h2>stack</h2><pre>${escapeHtml(facts.stack)}</pre></section>`
+  }
+  <section class="card">
+    <h2>json</h2>
+    <pre>${escapeHtml(JSON.stringify(problem, null, 2))}</pre>
+  </section>
+</main>`;
+};
+
+export const overlayResponse = (error: unknown, meta: OverlayMeta = {}): Response =>
+  html(renderOverlay(error, meta), {
+    status: factsOf(error).status,
+    headers: { 'cache-control': 'no-store' },
+  });
+
+/** Dev only, and only when the caller is a browser: agents and RPC want problem+json. */
+export const wantsOverlay = (request: Request): boolean =>
+  (request.headers.get('accept') ?? '').includes('text/html');