@beignet/core 0.0.37 → 0.0.38

package/src/server/hooks/cors.ts

@@ -104,8 +104,9 @@ export function applyCorsHeaders(
 /**
  * Create CORS hooks for preflight and regular responses.
  *
- * `OPTIONS` requests short-circuit with a 204 response. All other responses are
- * decorated in `beforeSend`.
+ * CORS preflight requests short-circuit with a 204 response. Explicit
+ * `OPTIONS` routes without `Access-Control-Request-Method` continue through the
+ * normal route pipeline. All responses are decorated in `beforeSend`.
  */
 export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
   const corsConfig = resolveCorsConfig(config);
@@ -113,7 +114,13 @@ export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
   return {
     name: "cors",
     onRequest: ({ req }) => {
-      if (req.method !== "OPTIONS") return undefined;
+      if (
+        req.method !== "OPTIONS" ||
+        !req.headers.get("Origin") ||
+        !req.headers.get("Access-Control-Request-Method")
+      ) {
+        return undefined;
+      }
       const headers: Record<string, string> = {};
       applyCorsHeaders(headers, req, corsConfig);
       return {

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

@@ -889,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 = {

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

@@ -391,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

@@ -734,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.
    */

package/src/tracing/index.ts

@@ -9,6 +9,29 @@
  */
 
 const TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+const MAX_TRACESTATE_LENGTH = 512;
+const MAX_TRACESTATE_MEMBERS = 32;
+const TRACESTATE_SIMPLE_KEY_PATTERN = /^[a-z][a-z0-9_*/-]{0,255}$/;
+const TRACESTATE_VENDOR_KEY_PATTERN =
+  /^[a-z0-9][a-z0-9_*/-]{0,240}@[a-z][a-z0-9_*/-]{0,13}$/;
+const TRACESTATE_VALUE_PATTERN =
+  /^[\x20-\x2b\x2d-\x3c\x3e-\x7e]{0,255}[\x21-\x2b\x2d-\x3c\x3e-\x7e]$/;
+
+/** Current version of Beignet's durable trace carrier. */
+export const TRACE_CARRIER_VERSION = 1 as const;
+
+/**
+ * Vendor-neutral trace context stored in durable messages and transport
+ * envelopes. Unknown versions and malformed values are ignored by consumers.
+ */
+export interface TraceCarrier {
+  /** Carrier schema version. */
+  readonly version: typeof TRACE_CARRIER_VERSION;
+  /** W3C traceparent value captured at the producing boundary. */
+  readonly traceparent: string;
+  /** Optional W3C tracestate value captured at the producing boundary. */
+  readonly tracestate?: string;
+}
 
 /**
  * Trace context used to correlate related activity.
@@ -161,6 +184,103 @@ export function resolveTracingPort(target: unknown): TracingPort | undefined {
   return resolveTracingPort(ports);
 }
 
+function validTracestate(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim();
+  if (normalized.length === 0 || normalized.length > MAX_TRACESTATE_LENGTH) {
+    return undefined;
+  }
+
+  const members = normalized.split(",");
+  if (members.length > MAX_TRACESTATE_MEMBERS) return undefined;
+
+  const keys = new Set<string>();
+  for (const rawMember of members) {
+    const member = rawMember.trim();
+    const separator = member.indexOf("=");
+    if (separator <= 0) return undefined;
+
+    const key = member.slice(0, separator).trim();
+    const memberValue = member.slice(separator + 1).trimStart();
+    if (
+      (!TRACESTATE_SIMPLE_KEY_PATTERN.test(key) &&
+        !TRACESTATE_VENDOR_KEY_PATTERN.test(key)) ||
+      !TRACESTATE_VALUE_PATTERN.test(memberValue) ||
+      keys.has(key)
+    ) {
+      return undefined;
+    }
+    keys.add(key);
+  }
+
+  return normalized;
+}
+
+/**
+ * Parse an untrusted durable trace carrier.
+ *
+ * Invalid carriers return `undefined`; trace metadata must never prevent
+ * message delivery.
+ */
+export function parseTraceCarrier(value: unknown): TraceCarrier | undefined {
+  if (!isObject(value) || value.version !== TRACE_CARRIER_VERSION) {
+    return undefined;
+  }
+
+  const parsed = parseTraceparent(
+    typeof value.traceparent === "string" ? value.traceparent : undefined,
+  );
+  if (!parsed) return undefined;
+
+  if (value.tracestate !== undefined) {
+    const tracestate = validTracestate(value.tracestate);
+    if (!tracestate) return undefined;
+    return {
+      version: TRACE_CARRIER_VERSION,
+      traceparent: parsed.traceparent,
+      tracestate,
+    };
+  }
+
+  return {
+    version: TRACE_CARRIER_VERSION,
+    traceparent: parsed.traceparent,
+  };
+}
+
+/**
+ * Capture the current trace context from a tracing port, ports object, app
+ * context, or explicit trace context. Returns `undefined` when no valid
+ * context is available.
+ */
+export function captureTraceCarrier(target: unknown): TraceCarrier | undefined {
+  let context: TraceContextInput | undefined;
+  try {
+    context = resolveTraceContextInput(target);
+  } catch {
+    // Context-like inputs may be proxy-backed and reject unknown properties.
+  }
+
+  try {
+    context = resolveTracingPort(target)?.current() ?? context;
+  } catch {
+    // Tracing is best-effort and must not block the owning operation.
+  }
+
+  try {
+    if (!context?.traceparent) return undefined;
+
+    return parseTraceCarrier({
+      version: TRACE_CARRIER_VERSION,
+      traceparent: context.traceparent,
+      ...(context.tracestate ? { tracestate: context.tracestate } : {}),
+    });
+  } catch {
+    // Trace contexts are app-provided and remain best-effort inputs.
+    return undefined;
+  }
+}
+
 /** Resolve trace fields from a trace context or context-like object. */
 export function resolveTraceContextInput(
   target: unknown,