@beignet/core 0.0.36 → 0.0.38

package/src/outbox/index.ts

@@ -7,6 +7,7 @@
 
 import {
   type EventPayloadDef,
+  type EventPublishOptions,
   type InferEventPayload,
   parseEventPayload,
 } from "../events/index.js";
@@ -21,15 +22,20 @@ import {
   shouldRetryJob,
 } from "../jobs/index.js";
 import type { JobDispatcherPort } from "../ports/events.js";
-import type {
-  BufferedDomainEventRecorder,
-  DomainEventRecorderPort,
-} from "../ports/unit-of-work.js";
+import type { DomainEventRecorderPort } from "../ports/unit-of-work.js";
 import {
   type BaseProviderInstrumentationEvent,
   createProviderInstrumentation,
   type ProviderInstrumentationTarget,
 } from "../providers/index.js";
+import {
+  captureTraceCarrier,
+  parseTraceCarrier,
+  resolveTracingPort,
+  runWithTracing,
+  type TraceCarrier,
+  type TracingPort,
+} from "../tracing/index.js";
 
 /**
  * Value or promise of that value.
@@ -113,6 +119,8 @@ export interface OutboxEnqueueInput {
    * JSON-serializable payload.
    */
   payload: OutboxJsonValue;
+  /** Versioned trace context captured when the message was recorded. */
+  trace?: TraceCarrier;
   /**
    * Earliest time the message may be claimed.
    */
@@ -143,6 +151,8 @@ export interface OutboxMessage {
    * JSON-serializable payload.
    */
   payload: OutboxJsonValue;
+  /** Versioned trace context captured when the message was recorded. */
+  trace?: TraceCarrier;
   /**
    * Current delivery status.
    */
@@ -490,6 +500,10 @@ export interface EnqueueTypedOutboxOptions {
    * Maximum delivery attempts before dead-lettering.
    */
   maxAttempts?: number;
+  /** Explicit trace context to persist with this message. */
+  trace?: TraceCarrier;
+  /** Tracing port used to capture the active context at enqueue time. */
+  tracing?: TracingPort;
 }
 
 /**
@@ -547,6 +561,7 @@ export interface DrainOutboxOptions {
     publish<E extends EventPayloadDef>(
       event: E,
       payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
     ): MaybePromise<void>;
   };
   /**
@@ -592,6 +607,23 @@ export interface DrainOutboxOptions {
     error: unknown,
     message: ClaimedOutboxMessage,
   ) => MaybePromise<void>;
+  /**
+   * Observer called after a failed delivery is successfully moved to the dead
+   * letter state. Observer failures are ignored.
+   */
+  onDeadLetter?: (
+    error: unknown,
+    message: ClaimedOutboxMessage,
+  ) => MaybePromise<void>;
+  /**
+   * Observer called when a failed delivery cannot be settled as retryable or
+   * dead-lettered. Observer failures are ignored.
+   */
+  onSettlementError?: (
+    settlementError: unknown,
+    message: ClaimedOutboxMessage,
+    deliveryError: unknown,
+  ) => MaybePromise<void>;
 }
 
 /**
@@ -921,11 +953,13 @@ export function createOutboxMessage(
   }
 
   const now = options.now ?? new Date();
+  const trace = parseTraceCarrier(input.trace);
   return {
     id: options.id ?? input.id ?? options.createId?.() ?? createId(),
     kind: input.kind,
     name: input.name,
     payload: toOutboxJsonValue(input.payload),
+    ...(trace ? { trace } : {}),
     status: "pending",
     attempts: 0,
     maxAttempts: input.maxAttempts ?? DEFAULT_OUTBOX_MAX_ATTEMPTS,
@@ -1236,11 +1270,14 @@ export async function enqueueEvent<E extends EventPayloadDef>(
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
   const parsed = await parseEventPayload(event, payload);
+  const trace =
+    parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "event",
     name: event.name,
     payload: toOutboxJsonValue(parsed),
+    trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts,
   });
@@ -1256,11 +1293,14 @@ export async function enqueueJob<J extends JobDef>(
   options: EnqueueTypedOutboxOptions = {},
 ): Promise<OutboxMessage> {
   const parsed = await parseJobPayload(job, payload);
+  const trace =
+    parseTraceCarrier(options.trace) ?? captureTraceCarrier(options.tracing);
   return outbox.enqueue({
     id: options.id,
     kind: "job",
     name: job.name,
     payload: toOutboxJsonValue(parsed),
+    trace,
     availableAt: options.availableAt,
     maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
   });
@@ -1272,16 +1312,14 @@ export async function enqueueJob<J extends JobDef>(
 export function createOutboxEventRecorder(
   outbox: OutboxPort,
   options: EnqueueTypedOutboxOptions = {},
-): BufferedDomainEventRecorder {
+): DomainEventRecorderPort {
   return {
-    async record(event, payload) {
-      await enqueueEvent(outbox, event, payload, options);
-    },
-    entries() {
-      return [];
+    async record(event, payload, publishOptions) {
+      await enqueueEvent(outbox, event, payload, {
+        ...options,
+        trace: publishOptions?.trace ?? options.trace,
+      });
     },
-    clear() {},
-    async flush() {},
   };
 }
 
@@ -1293,8 +1331,11 @@ export function createOutboxJobDispatcher(
   options: EnqueueTypedOutboxOptions = {},
 ): JobDispatcherPort {
   return {
-    async dispatch(job, payload) {
-      await enqueueJob(outbox, job, payload, options);
+    async dispatch(job, payload, dispatchOptions) {
+      await enqueueJob(outbox, job, payload, {
+        ...options,
+        trace: dispatchOptions?.trace ?? options.trace,
+      });
     },
   };
 }
@@ -1365,6 +1406,7 @@ function outboxInstrumentationDetails(
 async function deliverOutboxMessage(
   options: DrainOutboxOptions,
   message: ClaimedOutboxMessage,
+  trace?: TraceCarrier,
 ): Promise<void> {
   if (message.kind === "event") {
     if (!options.eventBus) {
@@ -1381,7 +1423,11 @@ async function deliverOutboxMessage(
     }
 
     const payload = await parseEventPayload(event, message.payload);
-    await options.eventBus.publish(event, payload);
+    await options.eventBus.publish(
+      event,
+      payload,
+      trace ? { trace } : undefined,
+    );
     return;
   }
 
@@ -1414,11 +1460,12 @@ async function deliverOutboxMessage(
     await singleAttempt(job, payload, {
       attempt: message.attempts,
       maxAttempts: message.maxAttempts,
+      trace,
     });
     return;
   }
 
-  await options.jobs.dispatch(job, payload);
+  await options.jobs.dispatch(job, payload, trace ? { trace } : undefined);
 }
 
 /**
@@ -1448,6 +1495,7 @@ export async function drainOutbox(
       watcher: "jobs",
     },
   );
+  const tracing = resolveTracingPort(options.instrumentation);
 
   const now = options.now ?? new Date();
   const messages = await options.outbox.claimBatch({
@@ -1464,7 +1512,28 @@ export async function drainOutbox(
 
   for (const message of messages) {
     try {
-      await deliverOutboxMessage(options, message);
+      const parentTrace = parseTraceCarrier(message.trace);
+      const traceAttributes = {
+        "beignet.outbox.message_kind": message.kind,
+        "beignet.outbox.message_name": message.name,
+      } as const;
+      await runWithTracing(
+        tracing,
+        {
+          name: `beignet.outbox deliver ${message.name}`,
+          type: "outbox",
+          kind: "consumer",
+          parent: parentTrace,
+          attributes: traceAttributes,
+          metricAttributes: traceAttributes,
+        },
+        (span) =>
+          deliverOutboxMessage(
+            options,
+            message,
+            captureTraceCarrier(span?.context ?? parentTrace),
+          ),
+      );
       await options.outbox.markDelivered({
         id: message.id,
         claimToken: message.claimToken,
@@ -1492,18 +1561,41 @@ export async function drainOutbox(
       const retryDelayMs = deadLetter
         ? 0
         : resolveRetryDelayMs(options, message, error, now);
-      await options.outbox.markFailed({
-        id: message.id,
-        claimToken: message.claimToken,
-        error,
-        deadLetter,
-        now,
-        retryAt: deadLetter
-          ? undefined
-          : new Date(now.getTime() + retryDelayMs),
-      });
+      try {
+        await options.outbox.markFailed({
+          id: message.id,
+          claimToken: message.claimToken,
+          error,
+          deadLetter,
+          now,
+          retryAt: deadLetter
+            ? undefined
+            : new Date(now.getTime() + retryDelayMs),
+        });
+      } catch (settlementError) {
+        try {
+          await options.onSettlementError?.(settlementError, message, error);
+        } catch {
+          // Preserve the settlement failure when its observer also fails.
+        }
+        instrumentation.custom({
+          name: "outbox.settlement.failed",
+          label: "Outbox settlement failed",
+          summary: `Could not settle failed ${message.kind} "${message.name}"`,
+          details: outboxInstrumentationDetails(message, {
+            deliveryError: serializeOutboxError(error),
+            settlementError: serializeOutboxError(settlementError),
+          }),
+        });
+        continue;
+      }
 
       if (deadLetter) {
+        try {
+          await options.onDeadLetter?.(error, message);
+        } catch {
+          // Dead-letter observers must not change the settled message state.
+        }
         instrumentation.record({
           type: "outbox",
           ...options.instrumentationContext,

package/src/ports/events.ts

@@ -1,11 +1,13 @@
 import type {
   EventPayloadDef,
+  EventPublishOptions,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
 } from "../events/index.js";
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
+  JobDispatchOptions,
 } from "../jobs/index.js";
 
 /**
@@ -74,6 +76,7 @@ export interface EventBusPort {
   publish<E extends DomainEventDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): Promise<void> | void;
 
   /**
@@ -81,7 +84,10 @@ export interface EventBusPort {
    */
   subscribe<E extends DomainEventDef>(
     event: E,
-    handler: (payload: InferEventPayload<E>) => Promise<void> | void,
+    handler: (
+      payload: InferEventPayload<E>,
+      options?: EventPublishOptions,
+    ) => Promise<void> | void,
   ): () => void;
 }
 
@@ -96,5 +102,6 @@ export interface JobDispatcherPort {
   dispatch<J extends JobDef>(
     job: J,
     payload: InferJobPayload<J>,
+    options?: JobDispatchOptions,
   ): Promise<void> | void;
 }

package/src/ports/index.ts

@@ -75,7 +75,7 @@ export type DeferredPortsDefinition<
  * Define the set of ports (outbound dependencies) for your application.
  *
  * The identity form captures the exact shape of the provided `ports` object
- * so you can export `type AppPorts = typeof appPorts`.
+ * so you can export `type AppPorts = typeof initialPorts`.
  *
  * The curried form, `definePorts<AppPorts>()({ bound, deferred })`, declares
  * which port keys providers contribute at server startup. Deferred keys boot
@@ -86,14 +86,14 @@ export type DeferredPortsDefinition<
  * @example
  * ```ts
  * // Identity form: every port is bound directly.
- * const appPorts = definePorts({
+ * const initialPorts = definePorts({
  *   db: dbAdapter,
  *   mailer: mailerAdapter,
  * });
- * export type AppPorts = typeof appPorts;
+ * export type AppPorts = typeof initialPorts;
  *
  * // Deferred form: providers contribute the rest at startup.
- * export const appPorts = definePorts<AppPorts>()({
+ * export const initialPorts = definePorts<AppPorts>()({
  *   bound: { gate },
  *   deferred: ["db", "mailer", "storage"],
  * });

package/src/ports/unbound.ts

@@ -13,7 +13,7 @@ function unboundPortMessage(portName: string): string {
   return (
     `Port "${portName}" is not bound. "${portName}" is declared as deferred ` +
     "in definePorts(...). Register a provider that contributes it " +
-    "(server/providers.ts) or bind it in infra/app-ports.ts."
+    "(server/providers.ts) or bind it in infra/port-wiring.ts."
   );
 }
 

package/src/ports/unit-of-work.ts

@@ -1,4 +1,7 @@
-import { parseEventPayload } from "../events/index.js";
+import {
+  type EventPublishOptions,
+  parseEventPayload,
+} from "../events/index.js";
 import type {
   DomainEventDef,
   EventBusPort,
@@ -71,6 +74,8 @@ export interface RecordedDomainEvent {
    * Unparsed payload recorded during the transaction.
    */
   payload: unknown;
+  /** Optional metadata propagated when the event is flushed. */
+  options?: EventPublishOptions;
 }
 
 /**
@@ -87,6 +92,7 @@ export interface DomainEventRecorderPort {
   record<E extends DomainEventDef>(
     event: E,
     payload: InferEventPayload<E>,
+    options?: EventPublishOptions,
   ): Promise<void> | void;
 }
 
@@ -167,11 +173,12 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
   const records: RecordedDomainEvent[] = [];
 
   return {
-    record(event, payload) {
+    record(event, payload, options) {
       records.push({
         event,
         eventName: event.name,
         payload,
+        ...(options ? { options } : {}),
       });
     },
 
@@ -187,7 +194,7 @@ export function createDomainEventRecorder(): BufferedDomainEventRecorder {
       while (records.length > 0) {
         const record = records[0];
         const payload = await parseEventPayload(record.event, record.payload);
-        await eventBus.publish(record.event, payload);
+        await eventBus.publish(record.event, payload, record.options);
         records.shift();
       }
     },

package/src/query-codec.ts

@@ -0,0 +1,130 @@
+const QUERY_VALUE_PREFIX = "~beignet-query:";
+
+type EncodedQueryValue =
+  | { type: "null" }
+  | { type: "string"; value: string }
+  | { type: "number"; value: number }
+  | { type: "boolean"; value: boolean }
+  | { type: "date"; value: string }
+  | { type: "array"; value: EncodedQueryValue[] }
+  | { type: "object"; value: Record<string, EncodedQueryValue> };
+
+function encodeStructuredValue(
+  value: unknown,
+  ancestors: Set<object>,
+): EncodedQueryValue {
+  if (value === null) return { type: "null" };
+  if (typeof value === "string") return { type: "string", value };
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return { type: "number", value };
+  }
+  if (typeof value === "boolean") return { type: "boolean", value };
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return { type: "date", value: value.toISOString() };
+  }
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError("Query value is not serializable.");
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError("Query value contains a circular reference.");
+  }
+
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return {
+        type: "array",
+        value: value.map((entry) => encodeStructuredValue(entry, ancestors)),
+      };
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("Query value contains a non-plain object.");
+    }
+    return {
+      type: "object",
+      value: Object.fromEntries(
+        Object.entries(value)
+          .filter(([, entry]) => entry !== undefined)
+          .map(([key, entry]) => [
+            key,
+            encodeStructuredValue(entry, ancestors),
+          ]),
+      ),
+    };
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function decodeStructuredValue(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || !("type" in value)) {
+    throw new TypeError("Invalid encoded query value.");
+  }
+  const encoded = value as { type: unknown; value?: unknown };
+
+  switch (encoded.type) {
+    case "null":
+      return null;
+    case "string":
+      if (typeof encoded.value === "string") return encoded.value;
+      break;
+    case "number":
+      if (typeof encoded.value === "number" && Number.isFinite(encoded.value)) {
+        return encoded.value;
+      }
+      break;
+    case "boolean":
+      if (typeof encoded.value === "boolean") return encoded.value;
+      break;
+    case "date": {
+      if (typeof encoded.value !== "string") break;
+      const date = new Date(encoded.value);
+      if (Number.isFinite(date.getTime())) return date;
+      break;
+    }
+    case "array":
+      if (Array.isArray(encoded.value)) {
+        return encoded.value.map(decodeStructuredValue);
+      }
+      break;
+    case "object":
+      if (
+        typeof encoded.value === "object" &&
+        encoded.value !== null &&
+        !Array.isArray(encoded.value)
+      ) {
+        return Object.fromEntries(
+          Object.entries(encoded.value).map(([key, entry]) => [
+            key,
+            decodeStructuredValue(entry),
+          ]),
+        );
+      }
+      break;
+  }
+
+  throw new TypeError("Invalid encoded query value.");
+}
+
+export function encodeQueryValue(value: unknown): string {
+  if (typeof value === "string" && !value.startsWith(QUERY_VALUE_PREFIX)) {
+    return value;
+  }
+  return `${QUERY_VALUE_PREFIX}${JSON.stringify(
+    encodeStructuredValue(value, new Set()),
+  )}`;
+}
+
+export function decodeQueryValue(value: string): unknown {
+  if (!value.startsWith(QUERY_VALUE_PREFIX)) return value;
+
+  try {
+    return decodeStructuredValue(
+      JSON.parse(value.slice(QUERY_VALUE_PREFIX.length)) as unknown,
+    );
+  } catch {
+    return value;
+  }
+}

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 {