@beignet/core 0.0.49 → 0.0.50

package/src/idempotency/index.ts

@@ -451,6 +451,17 @@ type CanonicalValue =
   | readonly CanonicalValue[]
   | { readonly [key: string]: CanonicalValue };
 
+const CANONICAL_TYPE_KEY = "$beignet:idempotency-type";
+
+function canonicalType(
+  type: "bigint" | "date" | "negative-zero" | "omitted",
+  value?: string,
+): CanonicalValue {
+  return {
+    [CANONICAL_TYPE_KEY]: value === undefined ? [type] : [type, value],
+  };
+}
+
 type MemoryRecord = MemoryIdempotencyEntry & {
   replayTtlSec?: number;
 };
@@ -875,11 +886,15 @@ function canonicalize(
     return undefined;
   }
 
-  if (
-    value === null ||
-    typeof value === "string" ||
-    typeof value === "boolean"
-  ) {
+  if (value === null) {
+    return null;
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (typeof value === "boolean") {
     return value;
   }
 
@@ -889,25 +904,54 @@ function canonicalize(
         "Cannot fingerprint non-finite numeric values.",
       );
     }
-    return value;
+    return Object.is(value, -0) ? canonicalType("negative-zero") : value;
   }
 
   if (typeof value === "bigint") {
-    return value.toString();
+    return canonicalType("bigint", value.toString());
   }
 
   if (value instanceof Date) {
-    return value.toISOString();
+    if (!Number.isFinite(value.getTime())) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint an invalid Date value.",
+      );
+    }
+    return canonicalType("date", value.toISOString());
   }
 
   if (Array.isArray(value)) {
-    return value.map(
-      (item, index) =>
-        canonicalize(item, options, [...path, String(index)], seen) ?? null,
-    );
+    if (seen.has(value)) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint circular values.",
+      );
+    }
+    seen.add(value);
+    const result: CanonicalValue = Array.from(value, (item, index) => {
+      const nestedValue = canonicalize(
+        item,
+        options,
+        [...path, String(index)],
+        seen,
+      );
+      return nestedValue === undefined ? canonicalType("omitted") : nestedValue;
+    });
+    seen.delete(value);
+    return result;
   }
 
   if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype) {
+      throw new IdempotencyFingerprintError(
+        "Cannot fingerprint unsupported object values. Use plain objects, arrays, Dates, and JSON primitives.",
+      );
+    }
+    if (Object.hasOwn(value, CANONICAL_TYPE_KEY)) {
+      throw new IdempotencyFingerprintError(
+        `Cannot fingerprint an object containing the reserved key "${CANONICAL_TYPE_KEY}".`,
+      );
+    }
     if (seen.has(value)) {
       throw new IdempotencyFingerprintError(
         "Cannot fingerprint circular values.",
@@ -915,7 +959,7 @@ function canonicalize(
     }
     seen.add(value);
 
-    const result: Record<string, CanonicalValue> = {};
+    const result: Record<string, CanonicalValue> = Object.create(null);
     for (const key of Object.keys(value as Record<string, unknown>).sort()) {
       const nestedValue = canonicalize(
         (value as Record<string, unknown>)[key],
@@ -946,9 +990,13 @@ function bytesToHex(bytes: ArrayBuffer): string {
 /**
  * Create a SHA-256 fingerprint from a canonicalized value.
  *
- * Object keys are sorted, `undefined` and functions are omitted, `Date` values
- * become ISO strings, BigInts become strings, and circular or non-finite values
- * throw. Exact omit paths may be supplied as dotted strings or string arrays.
+ * Object keys are sorted, while non-JSON values carry reserved type tags so
+ * BigInts and Dates cannot collide with same-looking strings. Ordinary JSON
+ * inputs retain their existing canonical representation. `undefined` values
+ * and functions are omitted from objects and represented as omitted array
+ * positions. Circular or unsupported object values, reserved tag keys,
+ * invalid dates, and non-finite numbers throw. Exact omit paths may be supplied
+ * as dotted strings or string arrays.
  */
 export async function createIdempotencyFingerprint(
   value: unknown,
@@ -961,7 +1009,7 @@ export async function createIdempotencyFingerprint(
   }
 
   const canonical = canonicalize(value, options, [], new WeakSet());
-  const json = JSON.stringify(canonical ?? null);
+  const json = JSON.stringify(canonical ?? canonicalType("omitted"));
   const digest = await globalThis.crypto.subtle.digest(
     "SHA-256",
     new TextEncoder().encode(json),

package/src/mail/index.ts

@@ -403,13 +403,17 @@ export function createMemoryMailerProvider(
           onSend,
         },
         (delivery, durationMs) => {
+          const recipientCount =
+            delivery.message.to.length +
+            (delivery.message.cc?.length ?? 0) +
+            (delivery.message.bcc?.length ?? 0);
           instrumentation.custom({
             name: "mail.sent",
             label: "Mail sent",
-            summary: delivery.message.subject,
+            summary: "Mail sent",
             details: {
-              to: delivery.message.to,
-              subject: delivery.message.subject,
+              provider: "memory",
+              recipientCount,
               id: delivery.id,
               durationMs,
             },

package/src/ports/best-effort-work.ts

@@ -0,0 +1,21 @@
+/**
+ * Non-durable work scheduled outside the originating application operation.
+ */
+export type BestEffortWork = () => Promise<void> | void;
+
+/**
+ * Non-durable, best-effort follow-up work.
+ *
+ * Use this for follow-up work that may be lost without changing the outcome
+ * of the originating operation. Required or retryable work belongs in a job
+ * or durable outbox instead.
+ */
+export interface BestEffortWorkPort {
+  /**
+   * Schedule work without waiting for it in the originating operation.
+   *
+   * Adapters should isolate scheduling and callback failures from the caller
+   * and report them through their configured error observer.
+   */
+  defer(work: BestEffortWork): void;
+}

package/src/ports/events.ts

@@ -1,9 +1,13 @@
 import type {
   EventPayloadDef,
   EventPublishOptions,
+  EventSubscription,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
 } from "../events/index.js";
+
+export type { EventSubscription } from "../events/index.js";
+
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
@@ -58,15 +62,16 @@ export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
  * const eventBus = createMemoryEventBus();
  *
  * // Subscribe to an event
- * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {
+ * const subscription = eventBus.subscribe(UserRegistered, (payload) => {
  *   console.log(`User registered: ${payload.email}`);
  * });
+ * await subscription.ready;
  *
  * // Publish an event
  * await eventBus.publish(UserRegistered, { userId: "123", email: "test@example.com" });
  *
  * // Unsubscribe when done
- * unsubscribe();
+ * await subscription.unsubscribe();
  * ```
  */
 export interface EventBusPort {
@@ -80,7 +85,7 @@ export interface EventBusPort {
   ): Promise<void> | void;
 
   /**
-   * Subscribe to a domain event. Returns an unsubscribe function.
+   * Subscribe to a domain event. Returns initial readiness and cleanup.
    */
   subscribe<E extends DomainEventDef>(
     event: E,
@@ -88,7 +93,7 @@ export interface EventBusPort {
       payload: InferEventPayload<E>,
       options?: EventPublishOptions,
     ) => Promise<void> | void,
-  ): () => void;
+  ): EventSubscription;
 }
 
 /**

package/src/ports/index.ts

@@ -8,6 +8,7 @@
  * - `definePorts` – helper to define a typed ports object
  * - `PortsContext` – a generic type that describes ctx objects that carry ports
  * - `EventBusPort` – interface for event bus implementations
+ * - `BestEffortWorkPort` – interface for non-durable follow-up work
  * - `JobDispatcherPort` – interface for job dispatch implementations
  * - `UnitOfWorkPort` – interface for app-owned transaction boundaries
  * - `OutboxPort` – interface for durable event/job delivery storage
@@ -468,6 +469,13 @@ export {
   requireUserId,
   TenantRequiredError,
 } from "./auth.js";
+/**
+ * Best-effort work port exports.
+ */
+export type {
+  BestEffortWork,
+  BestEffortWorkPort,
+} from "./best-effort-work.js";
 /**
  * Ports builder exports.
  */
@@ -498,6 +506,7 @@ export { createFrozenClock, createSystemClock } from "./clock.js";
 export type {
   DomainEventDef,
   EventBusPort,
+  EventSubscription,
   InferEventPayload,
   InferJobPayload,
   JobDef,

package/src/ports/testing.ts

@@ -38,6 +38,7 @@ import {
   createTenant,
   createUserActor,
 } from "./audit.js";
+import type { BestEffortWork, BestEffortWorkPort } from "./best-effort-work.js";
 import type { EventBusPort, JobDef, JobDispatcherPort } from "./events.js";
 import {
   type CreateGateOptions,
@@ -114,6 +115,50 @@ export function createRecordingEventBus(): {
   return { bus, events };
 }
 
+/**
+ * Recording best-effort-work adapter for deterministic tests.
+ *
+ * Calls to `defer(...)` append work without running it. `flush()` runs the
+ * currently pending batch in FIFO order, then rejects with the callback error
+ * or an `AggregateError` after every callback in that batch has been attempted.
+ * Work deferred by a running callback remains pending for the next flush so
+ * one flush stays bounded.
+ */
+export function createRecordingBestEffortWork(): {
+  bestEffortWork: BestEffortWorkPort;
+  pending: BestEffortWork[];
+  flush(): Promise<void>;
+} {
+  const pending: BestEffortWork[] = [];
+
+  return {
+    bestEffortWork: {
+      defer(work) {
+        pending.push(work);
+      },
+    },
+    pending,
+    async flush() {
+      const batch = pending.splice(0);
+      const errors: unknown[] = [];
+      for (const work of batch) {
+        try {
+          await work();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      if (errors.length > 1) {
+        throw new AggregateError(errors, "Best-effort work batch failed.");
+      }
+    },
+  };
+}
+
 /**
  * A job dispatch captured by `createRecordingJobDispatcher(...)`.
  */

package/src/providers/provider.ts

@@ -55,9 +55,11 @@ export type MaybePromise<T> = T | Promise<T>;
 /**
  * Late-bound service context factory exposed to providers.
  *
- * Calling it before all providers have started throws, so providers should
- * only invoke it from runtime entrypoints such as job dispatch, listeners, or
- * scheduled work.
+ * Calling it during provider setup or after provider shutdown throws. Start
+ * and stop hooks may invoke it after every provider has contributed ports and
+ * the server has verified that no deferred port remains unbound. Runtime
+ * entrypoints such as job dispatch, listeners, or scheduled work can close
+ * over it for later use.
  *
  * App-local providers can type the factory by declaring `Context` and
  * `ServiceInput` through the curried `createProvider<Requires, Context,
@@ -222,8 +224,9 @@ export interface ServiceProvider<
    * @param ctx.ports - Ports contributed by previous providers
    * @param ctx.config - Validated config (if config was defined), or undefined
    * @param ctx.createServiceContext - Late-bound service context factory.
-   * Throws until all providers have started, so call it lazily from runtime
-   * entrypoints such as job dispatchers and event listeners.
+   * Throws during setup. Start and stop hooks may invoke it after all provider
+   * ports have been contributed and validated; runtime entrypoints such as job
+   * dispatchers and event listeners may call it lazily afterward.
    */
   setup(ctx: {
     ports: Readonly<Ports>;

package/src/server/hooks/cors.ts

@@ -2,7 +2,11 @@
  * CORS hook utilities for @beignet/core/server
  */
 
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * CORS configuration for `createCorsHooks(...)`.
@@ -55,10 +59,12 @@ function resolveCorsConfig(config: CorsConfig): Required<CorsConfig> {
   return resolved;
 }
 
-function appendVaryOrigin(headers: Record<string, string>): void {
+function appendVaryOrigin(headers: HttpResponseHeaders): void {
   const varyKey =
     Object.keys(headers).find((key) => key.toLowerCase() === "vary") ?? "Vary";
-  const current = headers[varyKey];
+  const currentValue = headers[varyKey];
+  const current =
+    typeof currentValue === "string" ? currentValue : currentValue?.join(", ");
   const values = current?.split(",").map((value) => value.trim().toLowerCase());
   if (values?.includes("origin")) return;
 
@@ -72,7 +78,7 @@ function appendVaryOrigin(headers: Record<string, string>): void {
  * when cookies or authorization headers are allowed cross-origin.
  */
 export function applyCorsHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   req: HttpRequestLike,
   corsConfig: CorsConfig,
 ): void {
@@ -121,7 +127,7 @@ export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
       ) {
         return undefined;
       }
-      const headers: Record<string, string> = {};
+      const headers: HttpResponseHeaders = {};
       applyCorsHeaders(headers, req, corsConfig);
       return {
         status: 204,

package/src/server/hooks/logging.ts

@@ -7,7 +7,11 @@ import {
   resolveTrustedRequest,
   type TrustedRequestInfo,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 import { getRequestIdFromContext } from "./utils.js";
 
 /**
@@ -60,7 +64,7 @@ export interface LoggingConfig<Ctx> {
     ctx?: Ctx;
     req: HttpRequestLike;
     requestInfo: TrustedRequestInfo;
-    res: { status: number; headers: Record<string, string> };
+    res: { status: number; headers: HttpResponseHeaders };
     durationMs: number;
     contract?: HttpContractConfig;
     error?: unknown;

package/src/server/hooks/security.ts

@@ -9,7 +9,11 @@ import {
   type TrustedProxyConfig,
   type TrustedProxyOptions,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * Strict-Transport-Security configuration.
@@ -180,7 +184,7 @@ const DEFAULT_CSRF_HEADER = "x-csrf-token";
 const DEFAULT_CSRF_COOKIE = "beignet.csrf";
 
 function headerKey(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
 ): string | undefined {
   const lowerName = name.toLowerCase();
@@ -188,7 +192,7 @@ function headerKey(
 }
 
 function setHeaderIfMissing(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
   value: string | false | undefined,
 ): void {
@@ -217,7 +221,7 @@ function formatStrictTransportSecurity(
  * provide more specific policies.
  */
 export function applySecurityHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   options: SecurityHeadersOptions = {},
 ): void {
   setHeaderIfMissing(

package/src/server/http.ts

@@ -29,6 +29,14 @@ export interface HttpRequestLike {
    * Request headers.
    */
   headers: Headers;
+  /**
+   * Abort signal for the request lifecycle when the platform exposes one.
+   *
+   * Streaming handlers should pass this to resources that must close when
+   * the client disconnects. Adapters without cancellation support may omit
+   * it.
+   */
+  signal?: AbortSignal;
   /**
    * The platform request when an adapter has one available.
    *
@@ -62,6 +70,19 @@ export interface HttpRequestLike {
   clone?(): HttpRequestLike;
 }
 
+/**
+ * Header values accepted by a framework-neutral Beignet response.
+ *
+ * Use an array when the field must be emitted more than once, such as
+ * `Set-Cookie`. Adapters append every array item as a separate field value.
+ */
+export type HttpResponseHeaderValue = string | readonly string[];
+
+/**
+ * Framework-neutral response headers.
+ */
+export type HttpResponseHeaders = Record<string, HttpResponseHeaderValue>;
+
 /**
  * Framework-neutral response object returned by route handlers and hooks.
  */
@@ -71,9 +92,9 @@ export interface HttpResponseLike {
    */
   status: number;
   /**
-   * Response headers.
+   * Response headers. Array values are emitted as repeated header fields.
    */
-  headers?: Record<string, string>;
+  headers?: HttpResponseHeaders;
   /**
    * JSON-serializable body or an adapter-specific body value.
    */

package/src/server/index.ts

@@ -95,6 +95,10 @@ export {
  * Server context blueprint declaration helper.
  */
 export { defineServerContext } from "./server-context.js";
+/**
+ * Portable Server-Sent Events response helper.
+ */
+export * from "./server-sent-events.js";
 /**
  * Trusted proxy request metadata helpers.
  */

package/src/server/instrumentation.ts

@@ -16,7 +16,12 @@ import {
   type TraceContext,
   type TracingPort,
 } from "../tracing/index.js";
-import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  HttpResponseLike,
+  ServerHook,
+} from "./http.js";
 import {
   clearActiveRequestContext,
   enterActiveRequestContext,
@@ -205,17 +210,20 @@ function requestHeadersToRecord(headers: Headers): Record<string, string> {
 }
 
 function getResponseHeader(
-  headers: Record<string, string> | undefined,
+  headers: HttpResponseHeaders | undefined,
   name: string,
 ): string | undefined {
   if (!headers) return undefined;
   const direct = headers[name];
-  if (direct !== undefined) return direct;
+  if (direct !== undefined) {
+    return typeof direct === "string" ? direct : direct[0];
+  }
   const normalized = name.toLowerCase();
   const entry = Object.entries(headers).find(
     ([key]) => key.toLowerCase() === normalized,
   );
-  return entry?.[1];
+  const value = entry?.[1];
+  return typeof value === "string" ? value : value?.[0];
 }
 
 function getResponseOwner(

package/src/server/request-executor.ts

@@ -82,6 +82,7 @@ import {
   PathDecodeError,
 } from "./route-matching.js";
 import type { TrustedRequestInfo } from "./trusted-proxy.js";
+import { InvalidRequestUrlError } from "./trusted-proxy-internal.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -281,6 +282,19 @@ export function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof InvalidRequestUrlError) {
+        return {
+          ctx,
+          response: errorResponse(
+            400,
+            "INVALID_REQUEST_URL",
+            "Malformed request URL",
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       if (isAppError(currentError)) {
         return {
           ctx,

package/src/server/request-preparation.ts

@@ -41,6 +41,17 @@ type RequestValidationLocation = "query" | "path" | "headers" | "body";
 
 const DEFAULT_REQUEST_BODY_MAX_BYTES = 1024 * 1024;
 
+function cancelRequestBody(
+  source: { cancel(reason?: unknown): Promise<void> },
+  reason: unknown,
+): void {
+  try {
+    void source.cancel(reason).catch(() => {});
+  } catch {
+    // Cancellation is best-effort and must not replace the 413 response.
+  }
+}
+
 class RequestBodyTooLargeError extends Error {
   readonly maxBytes: number;
   readonly actualBytes?: number;
@@ -208,9 +219,16 @@ async function readLimitedRequestText(
   req: HttpRequestLike,
   maxBytes: number,
 ): Promise<string> {
-  assertContentLengthWithinLimit(req.headers, maxBytes);
-
   const body = req.raw?.body;
+  try {
+    assertContentLengthWithinLimit(req.headers, maxBytes);
+  } catch (error) {
+    if (body) {
+      cancelRequestBody(body, error);
+    }
+    throw error;
+  }
+
   if (!body) {
     const text = await req.text();
     const actualBytes = new TextEncoder().encode(text).byteLength;
@@ -231,7 +249,9 @@ async function readLimitedRequestText(
       if (result.done) break;
       received += result.value.byteLength;
       if (received > maxBytes) {
-        throw new RequestBodyTooLargeError(maxBytes, received);
+        const error = new RequestBodyTooLargeError(maxBytes, received);
+        cancelRequestBody(reader, error);
+        throw error;
       }
       text += decoder.decode(result.value, { stream: true });
     }