@beignet/core 0.0.36 → 0.0.38

package/src/server/hooks/error-reporting.ts

@@ -7,6 +7,14 @@ import type {
   ErrorReporterPort,
   ErrorReportOptions,
 } from "../../error-reporting/index.js";
+import {
+  DEFAULT_ERROR_REPORTING_TIMEOUT_MS,
+  tryReportException,
+} from "../../error-reporting/index.js";
+import {
+  errorReportingObserverTimeout,
+  runErrorReportingOperation,
+} from "../../error-reporting/internal.js";
 import { isAppError, SchemaValidationError } from "../../errors/index.js";
 import {
   IdempotencyConflictError,
@@ -81,6 +89,14 @@ export interface ErrorReportingHooksOptions<Ctx> {
   reportOptions?:
     | ErrorReportOptions
     | ((args: ErrorReportingHookArgs<Ctx>) => MaybePromise<ErrorReportOptions>);
+  /**
+   * Maximum time allowed for reporting preparation, capture, and failure
+   * observation. Each phase is bounded independently. Set to `false` only for
+   * intentionally unbounded reporters.
+   *
+   * @default 1000
+   */
+  timeoutMs?: number | false;
   /**
    * Observer for reporter failures. Reporter failures are otherwise ignored so
    * error reporting cannot change the HTTP response.
@@ -107,42 +123,82 @@ export function createErrorReportingHooks<
   return {
     name: "error-reporting",
     async onCaughtError(args) {
-      const shouldReport = config.shouldReport
-        ? await config.shouldReport(args)
-        : shouldReportServerError(args.err);
-      if (!shouldReport) return;
+      const timeoutMs = config.timeoutMs ?? DEFAULT_ERROR_REPORTING_TIMEOUT_MS;
+      let prepared:
+        | { reporter: ErrorReporterPort; reportOptions: ErrorReportOptions }
+        | undefined;
 
-      const reporter = await resolveReporter(config.reporter, args);
-      if (!reporter) return;
+      try {
+        prepared = await runErrorReportingOperation(async () => {
+          const shouldReport = config.shouldReport
+            ? await config.shouldReport(args)
+            : shouldReportServerError(args.err);
+          if (!shouldReport) return undefined;
 
-      const baseOptions = createDefaultReportOptions(args);
-      const customOptions =
-        typeof config.reportOptions === "function"
-          ? await config.reportOptions(args)
-          : config.reportOptions;
+          const reporter = await resolveReporter(config.reporter, args);
+          if (!reporter) return undefined;
 
-      try {
-        await reporter.captureException(
-          args.err,
-          mergeReportOptions(baseOptions, customOptions),
-        );
+          const baseOptions = createDefaultReportOptions(args);
+          const customOptions =
+            typeof config.reportOptions === "function"
+              ? await config.reportOptions(args)
+              : config.reportOptions;
+
+          return {
+            reporter,
+            reportOptions: mergeReportOptions(baseOptions, customOptions),
+          };
+        }, timeoutMs);
       } catch (reportingError) {
-        try {
-          await config.onReporterError?.({
+        await notifyReporterError(config, args, reportingError, timeoutMs);
+        return;
+      }
+
+      if (!prepared) return;
+
+      await tryReportException({
+        reporter: prepared.reporter,
+        error: args.err,
+        reportOptions: prepared.reportOptions,
+        timeoutMs,
+        onReporterError: ({ reportingError }) =>
+          config.onReporterError?.({
             error: args.err,
             reportingError,
             ctx: args.ctx,
             req: args.req,
             contract: args.contract,
-          });
-        } catch {
-          // Reporter failure observers must not affect request handling.
-        }
-      }
+          }),
+      });
     },
   };
 }
 
+async function notifyReporterError<Ctx>(
+  config: ErrorReportingHooksOptions<Ctx>,
+  args: ErrorReportingHookArgs<Ctx>,
+  reportingError: unknown,
+  timeoutMs: number | false,
+): Promise<void> {
+  if (!config.onReporterError) return;
+
+  try {
+    await runErrorReportingOperation(
+      () =>
+        config.onReporterError?.({
+          error: args.err,
+          reportingError,
+          ctx: args.ctx,
+          req: args.req,
+          contract: args.contract,
+        }),
+      errorReportingObserverTimeout(timeoutMs),
+    );
+  } catch {
+    // Reporting observers must not affect request handling.
+  }
+}
+
 /**
  * Default filter for HTTP error reporting.
  */

package/src/server/hooks/idempotency.ts

@@ -11,11 +11,17 @@ import {
   type IdempotencyPort,
   type IdempotencyScope,
 } from "../../idempotency/index.js";
-import type { ActivityActor, ActivityTenant } from "../../ports/index.js";
+import {
+  type ActivityActor,
+  type ActivityTenant,
+  AuthUnauthorizedError,
+  TenantRequiredError,
+} from "../../ports/index.js";
 import {
   type ResponseFinalizerServerHook,
   responseFinalizerHook,
 } from "../internal-hooks.js";
+import { finalizeResponse } from "../response-finalization.js";
 import type {
   HttpRequestLike,
   HttpResponseLike,
@@ -84,6 +90,7 @@ type PendingReservation = {
   key: string;
   scope: IdempotencyScope;
   fingerprint: string;
+  reservationToken: string;
 };
 
 function defaultIdempotencyScope(
@@ -96,11 +103,15 @@ function defaultIdempotencyScope(
     case "global":
       return "global";
     case "actor":
-      return { actorId: ctx.actor?.id };
+      if (!ctx.actor?.id) throw new AuthUnauthorizedError();
+      return { actorId: ctx.actor.id };
     case "tenant":
-      return { tenantId: ctx.tenant?.id };
+      if (!ctx.tenant?.id) throw new TenantRequiredError();
+      return { tenantId: ctx.tenant.id };
     case "actor-tenant":
-      return { actorId: ctx.actor?.id, tenantId: ctx.tenant?.id };
+      if (!ctx.actor?.id) throw new AuthUnauthorizedError();
+      if (!ctx.tenant?.id) throw new TenantRequiredError();
+      return { actorId: ctx.actor.id, tenantId: ctx.tenant.id };
   }
 }
 
@@ -193,6 +204,7 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
         scope,
         fingerprint,
         ttlSec: meta.ttlSec,
+        reservationTtlSec: meta.reservationTtlSec,
       });
 
       switch (reservation.status) {
@@ -205,13 +217,17 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
             );
           }
 
+          const validated = await finalizeResponse(
+            contract,
+            reservation.result,
+          );
           return {
-            status: reservation.result.status,
+            status: validated.status,
             headers: {
-              ...(reservation.result.headers ?? {}),
+              ...(validated.headers ?? {}),
               [IDEMPOTENCY_REPLAYED_HEADER]: "true",
             },
-            body: reservation.result.body,
+            body: validated.body,
           };
         }
         case "inProgress": {
@@ -227,6 +243,7 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
             key,
             scope,
             fingerprint,
+            reservationToken: reservation.reservationToken,
           });
           return undefined;
         }
@@ -246,11 +263,12 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
       }
       pending.delete(req);
 
-      const { port, namespace, key, scope, fingerprint } = reservation;
+      const { port, namespace, key, scope, fingerprint, reservationToken } =
+        reservation;
 
       if (
         owner === "route" &&
-        responseValidation !== "not-applicable" &&
+        responseValidation === "validated" &&
         !native &&
         !error &&
         response.status >= 200 &&
@@ -261,6 +279,7 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
           key,
           scope,
           fingerprint,
+          reservationToken,
           result: {
             status: response.status,
             headers: response.headers,
@@ -272,7 +291,14 @@ export function createIdempotencyHooks<Ctx extends CtxWithIdempotency>(
 
       // Framework-owned responses, errors, non-2xx responses, and native
       // `Response` results release the reservation. Streams are not replayable.
-      await port.fail({ namespace, key, scope, fingerprint, error });
+      await port.fail({
+        namespace,
+        key,
+        scope,
+        fingerprint,
+        reservationToken,
+        error,
+      });
       return undefined;
     },
   };

package/src/server/request-executor.ts

@@ -72,6 +72,7 @@ import {
   responseForHooks,
   responseOwnerFor,
   toContractViolationResponse,
+  withContractLifecycleHeaders,
   withFrameworkErrorOwnerHeader,
 } from "./response-finalization.js";
 import {
@@ -888,28 +889,20 @@ export function createRequestExecutor<
       let finalOwner = responseOwnerFor(finalResponse, result.owner);
       let responseValidation: ResponseFinalizerValidationState =
         "not-applicable";
-      if (
-        finalOwner === "route" &&
-        !isWebResponse(finalResponse) &&
-        !(options.validateResponses ?? true)
-      ) {
-        responseValidation = "disabled";
-      } else if (
-        finalOwner === "route" &&
-        !isWebResponse(finalResponse) &&
-        (options.validateResponses ?? true)
-      ) {
+      if (finalOwner === "route" && !isWebResponse(finalResponse)) {
+        const validateContract = options.validateResponses ?? true;
         try {
           finalResponse = await finalizeResponse(
             contract,
             finalResponse,
             target.responseValidationExemptStatus,
+            { validateContract },
           );
           result = {
             ...result,
             response: finalResponse,
           };
-          responseValidation = "validated";
+          responseValidation = validateContract ? "validated" : "disabled";
         } catch (error) {
           if (error instanceof ResponseContractViolationError) {
             result = {
@@ -947,6 +940,7 @@ export function createRequestExecutor<
           finalOwner,
         );
       }
+      finalResponse = withContractLifecycleHeaders(finalResponse, contract);
       finalResponse = withoutHeadResponseBody(finalResponse, req.method);
       stages.sendMs = performance.now() - sendStartedAt;
 
@@ -987,7 +981,10 @@ export function createRequestExecutor<
         },
       );
       const response = withoutHeadResponseBody(
-        normalizeHttpResponse(result.response),
+        withContractLifecycleHeaders(
+          normalizeHttpResponse(result.response),
+          contract,
+        ),
         req.method,
       );
       if (isWebResponse(response)) {

package/src/server/request-preparation.ts

@@ -4,6 +4,7 @@ import {
   methodSupportsRequestBody,
   type StandardSchema,
 } from "../contracts/index.js";
+import { decodeQueryValue } from "../query-codec.js";
 import type { HttpRequestLike, HttpResponseLike } from "./http.js";
 import {
   parseStandardSchema,
@@ -272,10 +273,11 @@ export async function prepareRequestInputs(args: {
     maxRequestBodyBytes,
     rawRoute,
   } = args;
-  const rawQuery: Record<string, string | string[]> = {};
+  const rawQuery: Record<string, unknown> = {};
   for (const key of new Set(url.searchParams.keys())) {
     const values = url.searchParams.getAll(key);
-    rawQuery[key] = values.length === 1 ? values[0] : values;
+    const decoded = values.map(decodeQueryValue);
+    rawQuery[key] = decoded.length === 1 ? decoded[0] : decoded;
   }
 
   let query: unknown = rawQuery;

package/src/server/response-finalization.ts

@@ -3,6 +3,7 @@ import {
   type ContractErrorDefinition,
   type HttpContractConfig,
 } from "../contracts/index.js";
+import { contractLifecycleResponseHeaders } from "../contracts/lifecycle.js";
 import {
   createErrorResponseBody,
   isErrorResponseBody,
@@ -74,6 +75,63 @@ export function withFrameworkErrorOwnerHeader(
   };
 }
 
+function setRecordHeader(
+  headers: Record<string, string>,
+  name: string,
+  value: string,
+): void {
+  const existingName = Object.keys(headers).find(
+    (key) => key.toLowerCase() === name.toLowerCase(),
+  );
+  if (existingName && existingName !== name) {
+    delete headers[existingName];
+  }
+  headers[name] = value;
+}
+
+/** Apply contract-owned deprecation headers to any response representation. */
+export function withContractLifecycleHeaders(
+  res: HttpResponse,
+  contract: HttpContractConfig,
+): HttpResponse {
+  const lifecycleHeaders = contractLifecycleResponseHeaders(contract);
+  if (Object.keys(lifecycleHeaders).length === 0) return res;
+
+  if (isWebResponse(res)) {
+    const headers = new Headers(res.headers);
+    for (const [name, value] of Object.entries(lifecycleHeaders)) {
+      if (name.toLowerCase() === "link" && headers.has(name)) {
+        headers.append(name, value);
+      } else {
+        headers.set(name, value);
+      }
+    }
+    return new Response(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    });
+  }
+
+  const headers = { ...(res.headers ?? {}) };
+  for (const [name, value] of Object.entries(lifecycleHeaders)) {
+    if (name.toLowerCase() === "link") {
+      const existingName = Object.keys(headers).find(
+        (key) => key.toLowerCase() === "link",
+      );
+      const existing = existingName ? headers[existingName] : undefined;
+      setRecordHeader(
+        headers,
+        name,
+        existing ? `${existing}, ${value}` : value,
+      );
+    } else {
+      setRecordHeader(headers, name, value);
+    }
+  }
+  return { ...res, headers };
+}
+
 export function responseOwnerFor(
   res: HttpResponse,
   owner?: ResponseOwner,
@@ -333,17 +391,48 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
   }
 }
 
+const BODYLESS_RESPONSE_STATUSES = new Set([204, 205, 304]);
+
+function validateHttpResponseSemantics(
+  contract: HttpContractConfig,
+  res: HttpResponseLike,
+): void {
+  if (
+    !BODYLESS_RESPONSE_STATUSES.has(res.status) ||
+    res.body === undefined ||
+    res.body === null
+  ) {
+    return;
+  }
+
+  throw new ResponseContractViolationError({
+    code: "RESPONSE_VALIDATION_ERROR",
+    message: responseContractViolationMessage(contract, res.status),
+    details: responseContractViolationDetails(contract, res.status, {
+      issues: [
+        {
+          message: `HTTP status ${res.status} must not include a response body.`,
+        },
+      ],
+    }),
+  });
+}
+
 export async function finalizeResponse<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
   responseValidationExemptStatus?: number,
+  options: { validateContract?: boolean } = {},
 ): Promise<HttpResponseLike> {
   const normalized = normalizeResponse(res);
-  await validateResponseAgainstContract(
-    contract,
-    normalized,
-    responseValidationExemptStatus,
-  );
+  validateHttpResponseSemantics(contract, normalized);
+  if (options.validateContract ?? true) {
+    await validateResponseAgainstContract(
+      contract,
+      normalized,
+      responseValidationExemptStatus,
+    );
+  }
   return normalized;
 }
 

package/src/server/server.ts

@@ -3,6 +3,10 @@ import {
   type HttpContractConfig,
   methodSupportsRequestBody,
 } from "../contracts/index.js";
+import {
+  assertValidContractLifecycle,
+  getContractOperationId,
+} from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
   formatPathParamsMismatch,
@@ -539,6 +543,7 @@ export async function createServer<
   const registeredPaths = new Set<string>();
   const registeredShapes = new Map<string, string>();
   const registeredNames = new Map<string, string>();
+  const registeredOperationIds = new Map<string, string>();
 
   const registerRoute = <C extends HttpContractConfig>(
     contract: C,
@@ -546,6 +551,7 @@ export async function createServer<
     routeHooks: readonly RouteHook<unknown, object>[] = [],
     responseValidationExemptStatus?: number,
   ): void => {
+    assertValidContractLifecycle(contract);
     if (contract.body && !methodSupportsRequestBody(contract.method)) {
       throw new Error(
         `Request bodies are not supported for ${contract.method} contracts. Use POST, PUT, or PATCH for contract request bodies.`,
@@ -572,6 +578,13 @@ export async function createServer<
         `Duplicate contract name: "${contract.name}" is registered for both ${conflictingName} and ${routeKey}. Contract names must be unique because typed clients, OpenAPI operations, and devtools key on them.`,
       );
     }
+    const operationId = getContractOperationId(contract);
+    const conflictingOperationId = registeredOperationIds.get(operationId);
+    if (conflictingOperationId) {
+      throw new Error(
+        `Duplicate OpenAPI operationId: "${operationId}" is registered for both ${conflictingOperationId} and ${routeKey}. Operation IDs must be unique across the registered route surface.`,
+      );
+    }
     if (contract.pathParams) {
       const shape = getObjectSchemaShape(contract.pathParams);
       if (shape) {
@@ -590,6 +603,7 @@ export async function createServer<
     registeredPaths.add(routeKey);
     registeredShapes.set(shapeRouteKey, routeKey);
     registeredNames.set(contract.name, routeKey);
+    registeredOperationIds.set(operationId, routeKey);
 
     const builtHandler = buildHandler(
       options,
@@ -720,7 +734,7 @@ export async function createServer<
         const message =
           `Unbound ports after provider startup: ${unboundKeys.join(", ")}. ` +
           "Each port declared as deferred in definePorts(...) must be contributed " +
-          "by a provider (server/providers.ts) or bound in infra/app-ports.ts. " +
+          "by a provider (server/providers.ts) or bound in infra/port-wiring.ts. " +
           'Pass onUnboundPorts: "warn" or "ignore" to change this behavior.';
         if (onUnboundPorts === "error") {
           throw new Error(message);

package/src/testing/index.ts

@@ -13,7 +13,11 @@ import {
   createMemoryNotificationPort,
   type MemoryNotificationPort,
 } from "../notifications/index.js";
-import { createMemoryOutbox, type MemoryOutboxPort } from "../outbox/index.js";
+import {
+  createMemoryOutbox,
+  enqueueEvent,
+  type MemoryOutboxPort,
+} from "../outbox/index.js";
 import {
   createMemoryPayments,
   type MemoryPaymentsPort,
@@ -289,11 +293,11 @@ export interface CreateTestPortsTransactionOptions<
    */
   afterRollback?: (error: unknown, tx: TxPorts) => MaybePromise<void>;
   /**
-   * Flush `tx.events` (a buffered domain event recorder) to `ports.eventBus`
+   * Enqueue `tx.events` (a buffered domain event recorder) to `ports.outbox`
    * after the transaction commits, and clear it after a rollback.
    *
-   * Requires `transaction.ports` to include an `events` recorder such as
-   * `createDomainEventRecorder()` or `createOutboxEventRecorder(...)`.
+   * Requires `transaction.ports` to include an `events` recorder created by
+   * `createDomainEventRecorder()`.
    */
   outbox?: boolean;
 }
@@ -328,7 +332,7 @@ export interface CreateTestPortsOptions<
   TxPorts = Ports,
 > {
   /**
-   * App-owned default ports, usually imported from `infra/app-ports`. Common
+   * App-owned default ports, usually imported from `infra/port-wiring`. Common
    * Beignet test defaults replace matching keys from `base`; use `overrides`
    * for app ports that should win.
    *
@@ -452,9 +456,16 @@ export function createTestPorts<
     {
       afterCommit: async (tx) => {
         if (flushEventsToOutbox) {
-          await resolveBufferedTransactionEvents(tx).flush(
-            (portsWithoutUow as unknown as { eventBus: EventBusPort }).eventBus,
-          );
+          const events = resolveBufferedTransactionEvents(tx);
+          const outbox = (
+            portsWithoutUow as unknown as {
+              outbox: MemoryOutboxPort;
+            }
+          ).outbox;
+          for (const entry of events.entries()) {
+            await enqueueEvent(outbox, entry.event, entry.payload);
+          }
+          events.clear();
         }
         await transactionOptions?.afterCommit?.(tx);
       },
@@ -578,26 +589,26 @@ function completeTestPortOverrides<Ports extends AnyPorts>(
 
 function resolveBufferedTransactionEvents(
   tx: unknown,
-): Pick<BufferedDomainEventRecorder, "flush" | "clear"> {
+): Pick<BufferedDomainEventRecorder, "entries" | "clear"> {
   const events =
     tx && typeof tx === "object"
       ? (tx as { events?: unknown }).events
       : undefined;
   const recorder = events as
-    | Partial<Pick<BufferedDomainEventRecorder, "flush" | "clear">>
+    | Partial<Pick<BufferedDomainEventRecorder, "entries" | "clear">>
     | undefined;
   if (
     !recorder ||
-    typeof recorder.flush !== "function" ||
+    typeof recorder.entries !== "function" ||
     typeof recorder.clear !== "function"
   ) {
     throw new Error(
       "createTestPorts transaction.outbox requires tx.events to be a buffered domain event recorder. " +
-        "Add events: createDomainEventRecorder() or createOutboxEventRecorder(...) to transaction.ports.",
+        "Add events: createDomainEventRecorder() to transaction.ports.",
     );
   }
 
-  return recorder as Pick<BufferedDomainEventRecorder, "flush" | "clear">;
+  return recorder as Pick<BufferedDomainEventRecorder, "entries" | "clear">;
 }
 
 /**
@@ -831,7 +842,7 @@ export interface CreateTestContextOptions<Ctx, Ports extends AnyPorts> {
    */
   auth?: unknown;
   /**
-   * App-owned default ports, usually imported from `infra/app-ports`. Common
+   * App-owned default ports, usually imported from `infra/port-wiring`. Common
    * Beignet test defaults replace matching keys from `base`; use `ports` for
    * app ports that should win.
    */