@beignet/core 0.0.2 → 0.0.4

package/src/server/hooks/idempotency.ts

@@ -0,0 +1,263 @@
+/**
+ * Idempotency hooks for @beignet/core/server
+ */
+
+import { AppError, httpErrors } from "../../errors/index.js";
+import {
+  createIdempotencyFingerprint,
+  IdempotencyConflictError,
+  IdempotencyInProgressError,
+  type IdempotencyMeta,
+  type IdempotencyPort,
+  type IdempotencyScope,
+} from "../../idempotency/index.js";
+import type { ActivityActor, ActivityTenant } from "../../ports/index.js";
+import type {
+  HttpRequestLike,
+  HttpResponseLike,
+  ServerHook,
+} from "../types.js";
+
+/**
+ * Ports required by idempotency hooks.
+ */
+export type IdempotencyPorts = {
+  idempotency: IdempotencyPort;
+};
+
+/**
+ * Minimal context shape required for actor- and tenant-scoped idempotency.
+ */
+export type CtxWithIdempotency = {
+  ports: IdempotencyPorts;
+  actor?: ActivityActor;
+  tenant?: ActivityTenant;
+};
+
+/**
+ * Options for `createIdempotencyHooks(...)`.
+ */
+export interface IdempotencyHooksOptions<Ctx> {
+  /**
+   * Build the idempotency namespace for a contract.
+   *
+   * Defaults to `http.<contract name>` so HTTP reservations never collide with
+   * use-case `runIdempotently(...)` namespaces.
+   */
+  namespace?: (args: { contract: { name: string } }) => string;
+  /**
+   * Build the idempotency scope after context exists.
+   *
+   * Defaults to a scope derived from `meta.scope`: `"global"` stays global,
+   * `"actor"` scopes by `ctx.actor?.id`, `"tenant"` scopes by `ctx.tenant?.id`,
+   * and `"actor-tenant"` scopes by both.
+   */
+  scope?: (args: {
+    ctx: Ctx;
+    req: HttpRequestLike;
+    meta: IdempotencyMeta;
+  }) => IdempotencyScope;
+  /**
+   * Build the fingerprint input from the parsed request.
+   *
+   * Defaults to `{ path, query, body }`.
+   */
+  fingerprintInput?: (args: {
+    path: unknown;
+    query: unknown;
+    body: unknown;
+  }) => unknown;
+}
+
+/**
+ * Header set on replayed responses.
+ */
+const IDEMPOTENCY_REPLAYED_HEADER = "idempotency-replayed";
+
+type PendingReservation = {
+  port: IdempotencyPort;
+  namespace: string;
+  key: string;
+  scope: IdempotencyScope;
+  fingerprint: string;
+};
+
+function defaultIdempotencyScope(
+  ctx: CtxWithIdempotency,
+  meta: IdempotencyMeta,
+): IdempotencyScope {
+  const mode = meta.scope ?? "global";
+
+  switch (mode) {
+    case "global":
+      return "global";
+    case "actor":
+      return { actorId: ctx.actor?.id };
+    case "tenant":
+      return { tenantId: ctx.tenant?.id };
+    case "actor-tenant":
+      return { actorId: ctx.actor?.id, tenantId: ctx.tenant?.id };
+  }
+}
+
+function isReplayableHttpResponse(value: unknown): value is HttpResponseLike {
+  if (typeof value !== "object" || value === null) return false;
+
+  const candidate = value as { status?: unknown; headers?: unknown };
+  if (typeof candidate.status !== "number") return false;
+
+  if (
+    candidate.headers !== undefined &&
+    (typeof candidate.headers !== "object" ||
+      candidate.headers === null ||
+      Array.isArray(candidate.headers))
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Create metadata-driven idempotency hooks.
+ *
+ * The hook reads `contract.metadata.idempotency` and enforces it with
+ * `ctx.ports.idempotency`. In `beforeHandle` it reserves the client key after
+ * request parsing, replays completed matching responses with an
+ * `idempotency-replayed: true` header, and rejects in-progress or conflicting
+ * keys with the framework `IdempotencyInProgress`/`IdempotencyConflict` catalog
+ * errors. In `beforeSend` it stores 2xx framework-neutral responses for replay
+ * and releases the reservation for errors, non-2xx responses, and native
+ * `Response` results, which are not replayable.
+ *
+ * Use `runIdempotently(...)` from `@beignet/core/idempotency` for non-HTTP
+ * workflows such as jobs, listeners, webhooks, and schedules.
+ *
+ * @param options - Optional namespace, scope, and fingerprint-input builders.
+ * @returns A server hook backed by `ctx.ports.idempotency`.
+ */
+export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
+  options: IdempotencyHooksOptions<Ctx> = {},
+): ServerHook<Ctx, IdempotencyPorts> {
+  const pending = new WeakMap<HttpRequestLike, PendingReservation>();
+
+  return {
+    name: "idempotency",
+    beforeHandle: async ({ ctx, contract, req, path, query, body }) => {
+      const meta = contract.metadata?.idempotency;
+      if (!meta) {
+        return undefined;
+      }
+
+      const header = (meta.header ?? "idempotency-key").toLowerCase();
+      const key = req.headers.get(header);
+
+      if (!key) {
+        if (meta.required) {
+          throw new AppError(
+            httpErrors.BadRequest,
+            {
+              contract: contract.name,
+              header,
+            },
+            `Missing required idempotency key header "${header}"`,
+          );
+        }
+        return undefined;
+      }
+
+      const namespace =
+        options.namespace?.({ contract: { name: contract.name } }) ??
+        `http.${contract.name}`;
+      const scope =
+        options.scope?.({ ctx, req, meta }) ??
+        defaultIdempotencyScope(ctx, meta);
+      const fingerprint = await createIdempotencyFingerprint(
+        options.fingerprintInput?.({ path, query, body }) ?? {
+          path,
+          query,
+          body,
+        },
+      );
+
+      const reservation = await ctx.ports.idempotency.reserve({
+        namespace,
+        key,
+        scope,
+        fingerprint,
+        ttlSec: meta.ttlSec,
+      });
+
+      switch (reservation.status) {
+        case "replay": {
+          if (!isReplayableHttpResponse(reservation.result)) {
+            throw new AppError(
+              httpErrors.InternalServerError,
+              { namespace, key },
+              `Stored idempotency result for "${namespace}" key "${key}" is not a replayable HTTP response`,
+            );
+          }
+
+          return {
+            status: reservation.result.status,
+            headers: {
+              ...(reservation.result.headers ?? {}),
+              [IDEMPOTENCY_REPLAYED_HEADER]: "true",
+            },
+            body: reservation.result.body,
+          };
+        }
+        case "inProgress": {
+          throw new IdempotencyInProgressError(reservation);
+        }
+        case "conflict": {
+          throw new IdempotencyConflictError(reservation);
+        }
+        case "reserved": {
+          pending.set(req, {
+            port: ctx.ports.idempotency,
+            namespace,
+            key,
+            scope,
+            fingerprint,
+          });
+          return undefined;
+        }
+      }
+    },
+    beforeSend: async ({ req, response, error, native }) => {
+      const reservation = pending.get(req);
+      if (!reservation) {
+        return undefined;
+      }
+      pending.delete(req);
+
+      const { port, namespace, key, scope, fingerprint } = reservation;
+
+      if (
+        !native &&
+        !error &&
+        response.status >= 200 &&
+        response.status < 300
+      ) {
+        await port.complete({
+          namespace,
+          key,
+          scope,
+          fingerprint,
+          result: {
+            status: response.status,
+            headers: response.headers,
+            body: response.body,
+          },
+        });
+        return undefined;
+      }
+
+      // Errors, non-2xx responses, and native `Response` results release the
+      // reservation. Streams are not replayable.
+      await port.fail({ namespace, key, scope, fingerprint, error });
+      return undefined;
+    },
+  };
+}

package/src/server/hooks/index.ts

@@ -2,39 +2,42 @@
  * Hook utilities for @beignet/core/server
  */
 
-import type { AnyPorts } from "../../ports";
-import type { ServerHook } from "../http";
+import type { AnyPorts } from "../../ports/index.js";
+import type { ServerHook } from "../http.js";
 
 export {
   type AuthHookArgs,
-  type AuthHookAssignArgs,
-  type AuthHookMode,
-  type AuthHookModeInput,
   type AuthHooksOptions,
-  type AuthHookUnauthorizedArgs,
-  type CtxWithAuthPort,
+  type AuthRouteHooks,
   createAuthHooks,
-} from "./auth";
+} from "./auth.js";
 export {
   applyCorsHeaders,
   type CorsConfig,
   createCorsHooks,
-} from "./cors";
+} from "./cors.js";
 export {
   defaultMapErrorToResponse,
   type ErrorMappingConfig,
   type ErrorMappingResult,
-} from "./errors";
+} from "./errors.js";
+export {
+  type CtxWithIdempotency,
+  createIdempotencyHooks,
+  type IdempotencyHooksOptions,
+  type IdempotencyPorts,
+} from "./idempotency.js";
 export {
   createLoggingHooks,
   type Logger,
   type LoggingConfig,
-} from "./logging";
+} from "./logging.js";
 export {
   type CtxWithRateLimit,
   createRateLimitHooks,
+  type RateLimitIpSource,
   type RateLimitOptions,
-} from "./rate-limit";
+} from "./rate-limit.js";
 
 /**
  * Flatten hook arrays into a single hook list.

package/src/server/hooks/logging.ts

@@ -2,9 +2,9 @@
  * Logging hook utilities for @beignet/core/server
  */
 
-import type { HttpContractConfig } from "../../contracts";
-import type { HttpRequestLike, ServerHook } from "../types";
-import { getRequestIdFromContext } from "./utils";
+import type { HttpContractConfig } from "../../contracts/index.js";
+import type { HttpRequestLike, ServerHook } from "../types.js";
+import { getRequestIdFromContext } from "./utils.js";
 
 /**
  * Minimal logger shape accepted by `createLoggingHooks(...)`.

package/src/server/hooks/rate-limit.ts

@@ -2,10 +2,14 @@
  * Rate limit hooks for @beignet/core/server
  */
 
-import type { RateLimitScope } from "../../contracts";
-import { AppError, httpErrors } from "../../errors";
-import type { ActivityActor, RateLimitPort } from "../../ports";
-import type { HttpRequestLike, ServerHook } from "../types";
+import type { RateLimitScope } from "../../contracts/index.js";
+import { AppError, httpErrors } from "../../errors/index.js";
+import type { ActivityActor, RateLimitPort } from "../../ports/index.js";
+import {
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "../../providers/index.js";
+import type { HttpRequestLike, ServerHook } from "../types.js";
 
 /**
  * Ports required by rate-limit hooks.
@@ -24,6 +28,23 @@ export type CtxWithRateLimit = {
 
 type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
 
+/**
+ * Strategy for resolving the client IP used by `ip`-scoped limits.
+ *
+ * - `"x-forwarded-for-last"` (default): the last `x-forwarded-for` entry.
+ *   This is the address appended by the platform's trusted reverse proxy and
+ *   cannot be chosen by the client.
+ * - `"x-forwarded-for-first"`: the first `x-forwarded-for` entry. This value
+ *   is client-controlled, so only use it when a trusted edge normalizes the
+ *   header before it reaches the app.
+ * - A function receives the raw request and returns the client IP, for
+ *   platform-specific headers such as `cf-connecting-ip`.
+ */
+export type RateLimitIpSource =
+  | "x-forwarded-for-last"
+  | "x-forwarded-for-first"
+  | ((req: HttpRequestLike) => string | undefined);
+
 /**
  * Options for `createRateLimitHooks(...)`.
  */
@@ -48,14 +69,38 @@ export interface RateLimitOptions<Ctx> {
     scope: EarlyRateLimitScope;
   }) => string;
   /**
-   * Resolve a client IP from the raw request.
+   * Resolve the client IP for `ip`-scoped limits.
+   *
+   * Defaults to `"x-forwarded-for-last"`, the entry appended by the
+   * platform's trusted proxy. Pass a function for platform-specific headers.
    */
-  getClientIp?: (req: HttpRequestLike) => string | undefined;
+  ipSource?: RateLimitIpSource;
 }
 
-function defaultGetClientIp(req: HttpRequestLike): string | undefined {
-  const xfwd = req.headers.get("x-forwarded-for") ?? "";
-  return xfwd.split(",")[0].trim() || undefined;
+function parseForwardedFor(req: HttpRequestLike): string[] {
+  const header = req.headers.get("x-forwarded-for") ?? "";
+  return header
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function resolveClientIp(
+  req: HttpRequestLike,
+  ipSource: RateLimitIpSource,
+): string | undefined {
+  if (typeof ipSource === "function") {
+    return ipSource(req) || undefined;
+  }
+
+  const entries = parseForwardedFor(req);
+  if (entries.length === 0) {
+    return undefined;
+  }
+
+  return ipSource === "x-forwarded-for-first"
+    ? entries[0]
+    : entries[entries.length - 1];
 }
 
 function emitUserKey(userId: string): string {
@@ -104,7 +149,7 @@ function defaultEarlyRateLimitKey(
 }
 
 async function enforceRateLimit(
-  rateLimit: RateLimitPort,
+  ports: RateLimitPorts,
   args: {
     key: string;
     limit: number;
@@ -112,7 +157,7 @@ async function enforceRateLimit(
     scope: RateLimitScope;
   },
 ): Promise<void> {
-  const result = await rateLimit.hit({
+  const result = await ports.rateLimit.hit({
     key: args.key,
     limit: args.limit,
     windowSec: args.windowSec,
@@ -122,10 +167,30 @@ async function enforceRateLimit(
     return;
   }
 
+  // App ports may carry an `instrumentation` or `devtools` sink alongside the
+  // typed rate-limit port; the helper resolves them at runtime.
+  const instrumentation = createProviderInstrumentation(
+    ports as ProviderInstrumentationTarget,
+    {
+      providerName: "rate-limit",
+      watcher: "rateLimit",
+    },
+  );
+  instrumentation.custom({
+    name: "rateLimit.denied",
+    label: "Rate limit denied",
+    summary: `Rate limit denied for ${args.key}`,
+    details: {
+      key: args.key,
+      scope: args.scope,
+      limit: args.limit,
+      windowSec: args.windowSec,
+    },
+  });
+
   throw new AppError(
     httpErrors.TooManyRequests,
     {
-      key: args.key,
       scope: args.scope,
       retryAfterSeconds: result.retryAfterSeconds,
       resetAt: result.resetAt?.toISOString() ?? null,
@@ -140,15 +205,18 @@ async function enforceRateLimit(
  * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
  * in `onRequest` before context creation; user-scoped limits run in
  * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
- * framework `TooManyRequests` app error.
+ * framework `TooManyRequests` app error with `scope`, `retryAfterSeconds`, and
+ * `resetAt` details. The bucket key is never sent to clients; denials emit a
+ * `rateLimit.denied` instrumentation event that carries the key for operators.
  *
- * @param options - Optional key builders and client-IP resolver.
+ * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
  */
 export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   options: RateLimitOptions<Ctx> = {},
 ): ServerHook<Ctx, RateLimitPorts> {
-  const getClientIp = options.getClientIp ?? defaultGetClientIp;
+  const ipSource = options.ipSource ?? "x-forwarded-for-last";
+  const getClientIp = (req: HttpRequestLike) => resolveClientIp(req, ipSource);
 
   return {
     name: "rate-limit",
@@ -167,7 +235,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
         options.earlyKey?.({ req, scope }) ??
         defaultEarlyRateLimitKey({ req, scope }, getClientIp);
 
-      await enforceRateLimit(ports.rateLimit, {
+      await enforceRateLimit(ports, {
         key,
         limit: rlMeta.max,
         windowSec: rlMeta.windowSec,
@@ -191,7 +259,7 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
         options.key?.({ ctx, req, scope }) ??
         defaultRateLimitKey({ ctx, req, scope }, getClientIp);
 
-      await enforceRateLimit(ctx.ports.rateLimit, {
+      await enforceRateLimit(ctx.ports, {
         key,
         limit: rlMeta.max,
         windowSec: rlMeta.windowSec,

package/src/server/hooks.ts

@@ -1 +1 @@
-export * from "./hooks/index";
+export * from "./hooks/index.js";

package/src/server/http.ts

@@ -3,8 +3,8 @@ import type {
   InferHeaderSchemaOutput,
   InferOutput,
   StandardSchema,
-} from "../contracts";
-import type { AnyPorts } from "../ports";
+} from "../contracts/index.js";
+import type { AnyPorts } from "../ports/index.js";
 
 /**
  * Framework-neutral request shape consumed by Beignet server adapters.
@@ -84,6 +84,50 @@ export interface HttpResponseLike {
  */
 export type HttpResponse = HttpResponseLike | Response;
 
+/**
+ * Framework-neutral Beignet API handler consumed by HTTP adapters.
+ */
+export type HttpAdapterApiHandler = (
+  req: HttpRequestLike,
+) => Promise<HttpResponse>;
+
+/**
+ * Native handler shape produced by an HTTP adapter.
+ */
+export type HttpAdapterHandler<NativeRequest, NativeResponse> = (
+  req: NativeRequest,
+) => Promise<NativeResponse>;
+
+/**
+ * Contract implemented by packages that adapt Beignet's framework-neutral
+ * server runtime to a platform HTTP API.
+ *
+ * Core owns request parsing, hooks, route matching, validation, error mapping,
+ * response ownership, and provider lifecycle. Adapters own only the conversion
+ * between the platform request/response types and Beignet's `HttpRequestLike`
+ * / `HttpResponse` boundary.
+ */
+export interface HttpAdapter<NativeRequest, NativeResponse> {
+  /**
+   * Human-readable adapter name for diagnostics and documentation.
+   */
+  name: string;
+  /**
+   * Convert a platform request into Beignet's framework-neutral request shape.
+   */
+  toRequestLike(req: NativeRequest): HttpRequestLike;
+  /**
+   * Convert a Beignet response into the platform response type.
+   */
+  toNativeResponse(res: HttpResponse): NativeResponse | Promise<NativeResponse>;
+  /**
+   * Wrap a Beignet API handler in the platform's native handler shape.
+   */
+  createHandler(
+    handler: HttpAdapterApiHandler,
+  ): HttpAdapterHandler<NativeRequest, NativeResponse>;
+}
+
 type InferSchemaOrFallback<
   T extends StandardSchema | null,
   Fallback,
@@ -130,7 +174,7 @@ export interface HandlerArgs<Ctx, C extends HttpContractConfig> {
    */
   req: HttpRequestLike;
   /**
-   * Application context returned by `createContext`.
+   * Application context assembled by the server context blueprint.
    */
   ctx: Ctx;
   /**
@@ -168,6 +212,59 @@ export type Handler<Ctx, C extends HttpContractConfig> = (
  */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Arguments passed to a route-scoped hook after request parsing and context
+ * creation.
+ */
+export type RouteHookArgs<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = HandlerArgs<Ctx, C>;
+
+/**
+ * Hook that runs only for the route or route group where it is attached.
+ *
+ * Route hooks are for scoped policy and context enrichment such as
+ * authentication, tenant resolution, feature gates, and idempotency. They add
+ * fields to the handler context instead of replacing the app context.
+ *
+ * Hook additions must not include `gate`: the server re-attaches the gate
+ * declared by the context blueprint after every hook, so identity changes are
+ * picked up automatically.
+ */
+export interface RouteHook<
+  Ctx,
+  AddedCtx extends object & { gate?: never } = Record<string, never>,
+> {
+  /**
+   * Optional name used in diagnostics and devtools.
+   */
+  name?: string;
+  /**
+   * Resolve additional context for this route or throw to stop handling.
+   */
+  resolve: (args: RouteHookArgs<Ctx>) => MaybePromise<AddedCtx | undefined>;
+}
+
+type AddedCtxFromHook<Hook> =
+  Hook extends RouteHook<infer _Ctx, infer AddedCtx> ? AddedCtx : unknown;
+
+type UnionToIntersection<Union> = (
+  Union extends unknown
+    ? (value: Union) => void
+    : never
+) extends (value: infer Intersection) => void
+  ? Intersection
+  : never;
+
+/**
+ * Intersection of the context fields added by a route hook list.
+ */
+export type AddedCtxFromHooks<Hooks extends readonly unknown[]> =
+  Hooks extends readonly []
+    ? unknown
+    : UnionToIntersection<AddedCtxFromHook<Hooks[number]>>;
+
 /**
  * Hook that runs after a route is matched but before request parsing and
  * context creation.
@@ -215,10 +312,11 @@ export type BeforeHandleHook<
 }) => MaybePromise<BeforeHandleResult<Ctx>>;
 
 /**
- * Hook that runs before a framework-neutral response is returned.
+ * Hook that runs before the response is returned.
  *
  * Return a response to replace or decorate the outgoing response. Hooks run in
- * declaration order.
+ * declaration order. For native web `Response` results the hook receives a
+ * headers-only view and only header changes are applied.
  */
 export type BeforeSendHook<
   Ctx,
@@ -233,6 +331,13 @@ export type BeforeSendHook<
   body?: InferBody<C>;
   response: HttpResponseLike;
   error?: unknown;
+  /**
+   * True when the route returned a native web Response. The response argument
+   * is a headers-only view ({ status, headers }); the body is not readable and
+   * returned body/status changes are ignored. Header changes are merged onto
+   * the native Response.
+   */
+  native?: boolean;
 }) => MaybePromise<HttpResponseLike | undefined>;
 
 /**
@@ -316,7 +421,8 @@ export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
    */
   beforeHandle?: BeforeHandleHook<Ctx>;
   /**
-   * Runs before a framework-neutral response is returned.
+   * Runs before the response is returned. Native web `Response` results get a
+   * headers-only view with `native: true`.
    */
   beforeSend?: BeforeSendHook<Ctx>;
   /**