@beignet/core 0.0.13 → 0.0.15

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

@@ -0,0 +1,249 @@
+/**
+ * Error reporting hook utilities for @beignet/core/server
+ */
+
+import type { HttpContractConfig } from "../../contracts/index.js";
+import type {
+  ErrorReporterPort,
+  ErrorReportOptions,
+} from "../../error-reporting/index.js";
+import { isAppError, SchemaValidationError } from "../../errors/index.js";
+import {
+  IdempotencyConflictError,
+  IdempotencyInProgressError,
+} from "../../idempotency/index.js";
+import {
+  AuthUnauthorizedError,
+  EntitlementRequiredError,
+  GateAuthorizationError,
+  TenantRequiredError,
+} from "../../ports/index.js";
+import type {
+  HttpRequestLike,
+  ServerCaughtErrorHook,
+  ServerHook,
+} from "../types.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Minimal context shape used by `createErrorReportingHooks(...)`.
+ */
+export type ErrorReportingContext = {
+  ports?: {
+    errorReporter?: ErrorReporterPort;
+  };
+  requestId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  traceparent?: string;
+  actor?: {
+    type?: string;
+    id?: string;
+  };
+  tenant?: {
+    id?: string;
+  };
+};
+
+/**
+ * Arguments passed to error reporting hook callbacks.
+ */
+export type ErrorReportingHookArgs<Ctx> = Parameters<
+  ServerCaughtErrorHook<Ctx>
+>[0];
+
+/**
+ * Error reporter resolver accepted by `createErrorReportingHooks(...)`.
+ */
+export type ErrorReporterResolver<Ctx> = (
+  args: ErrorReportingHookArgs<Ctx>,
+) => MaybePromise<ErrorReporterPort | undefined>;
+
+/**
+ * Options accepted by `createErrorReportingHooks(...)`.
+ */
+export interface ErrorReportingHooksOptions<Ctx> {
+  /**
+   * Reporter to use instead of `ctx.ports.errorReporter`.
+   */
+  reporter?: ErrorReporterPort | ErrorReporterResolver<Ctx>;
+  /**
+   * Decide whether a caught error should be captured. The default reports
+   * unexpected failures and skips expected catalog/auth/validation outcomes.
+   */
+  shouldReport?: (args: ErrorReportingHookArgs<Ctx>) => MaybePromise<boolean>;
+  /**
+   * Additional capture options. These are merged over Beignet's request,
+   * actor, tenant, contract, and trace metadata.
+   */
+  reportOptions?:
+    | ErrorReportOptions
+    | ((args: ErrorReportingHookArgs<Ctx>) => MaybePromise<ErrorReportOptions>);
+  /**
+   * Observer for reporter failures. Reporter failures are otherwise ignored so
+   * error reporting cannot change the HTTP response.
+   */
+  onReporterError?: (args: {
+    error: unknown;
+    reportingError: unknown;
+    ctx?: Ctx;
+    req: HttpRequestLike;
+    contract: HttpContractConfig;
+  }) => MaybePromise<void>;
+}
+
+/**
+ * Create server hooks that capture unexpected HTTP request failures through
+ * `ctx.ports.errorReporter`.
+ *
+ * The hook observes `onCaughtError`, never maps responses, and ignores capture
+ * failures by default so reporting cannot affect request handling.
+ */
+export function createErrorReportingHooks<
+  Ctx extends ErrorReportingContext = ErrorReportingContext,
+>(config: ErrorReportingHooksOptions<Ctx> = {}): ServerHook<Ctx> {
+  return {
+    name: "error-reporting",
+    async onCaughtError(args) {
+      const shouldReport = config.shouldReport
+        ? await config.shouldReport(args)
+        : shouldReportServerError(args.err);
+      if (!shouldReport) return;
+
+      const reporter = await resolveReporter(config.reporter, args);
+      if (!reporter) return;
+
+      const baseOptions = createDefaultReportOptions(args);
+      const customOptions =
+        typeof config.reportOptions === "function"
+          ? await config.reportOptions(args)
+          : config.reportOptions;
+
+      try {
+        await reporter.captureException(
+          args.err,
+          mergeReportOptions(baseOptions, customOptions),
+        );
+      } catch (reportingError) {
+        try {
+          await config.onReporterError?.({
+            error: args.err,
+            reportingError,
+            ctx: args.ctx,
+            req: args.req,
+            contract: args.contract,
+          });
+        } catch {
+          // Reporter failure observers must not affect request handling.
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Default filter for HTTP error reporting.
+ */
+export function shouldReportServerError(error: unknown): boolean {
+  if (isAppError(error)) return false;
+  if (error instanceof AuthUnauthorizedError) return false;
+  if (error instanceof TenantRequiredError) return false;
+  if (error instanceof IdempotencyConflictError) return false;
+  if (error instanceof IdempotencyInProgressError) return false;
+  if (error instanceof GateAuthorizationError) return false;
+  if (error instanceof EntitlementRequiredError) return false;
+  if (error instanceof SchemaValidationError) return false;
+  return true;
+}
+
+async function resolveReporter<Ctx extends ErrorReportingContext>(
+  reporter: ErrorReportingHooksOptions<Ctx>["reporter"],
+  args: ErrorReportingHookArgs<Ctx>,
+): Promise<ErrorReporterPort | undefined> {
+  if (typeof reporter === "function") {
+    return reporter(args);
+  }
+
+  if (reporter) {
+    return reporter;
+  }
+
+  return args.ctx?.ports?.errorReporter;
+}
+
+function createDefaultReportOptions<Ctx extends ErrorReportingContext>(
+  args: ErrorReportingHookArgs<Ctx>,
+): ErrorReportOptions {
+  const ctx = args.ctx;
+  const url = safeUrl(args.req.url);
+  const actor = ctx?.actor;
+  const tenant = ctx?.tenant;
+
+  return {
+    level: "error",
+    mechanism: "beignet.server",
+    handled: false,
+    requestId: ctx?.requestId,
+    traceId: ctx?.traceId,
+    spanId: ctx?.spanId,
+    parentSpanId: ctx?.parentSpanId,
+    traceparent: ctx?.traceparent,
+    user: actor?.type === "user" && actor.id ? { id: actor.id } : undefined,
+    tags: {
+      "beignet.kind": "http",
+      "http.method": args.req.method,
+      "http.route": args.contract.path,
+      "http.contract": args.contract.name,
+    },
+    contexts: {
+      request: {
+        method: args.req.method,
+        path: url?.pathname ?? args.contract.path,
+        route: args.contract.path,
+        contract: args.contract.name,
+      },
+      actor:
+        actor?.type || actor?.id
+          ? {
+              type: actor.type,
+              id: actor.id,
+            }
+          : undefined,
+      tenant: tenant?.id ? { id: tenant.id } : undefined,
+    },
+  };
+}
+
+function mergeReportOptions(
+  base: ErrorReportOptions,
+  custom: ErrorReportOptions | undefined,
+): ErrorReportOptions {
+  if (!custom) return base;
+
+  return {
+    ...base,
+    ...custom,
+    tags: {
+      ...base.tags,
+      ...custom.tags,
+    },
+    contexts: {
+      ...base.contexts,
+      ...custom.contexts,
+    },
+    extra: {
+      ...base.extra,
+      ...custom.extra,
+    },
+  };
+}
+
+function safeUrl(value: string): URL | undefined {
+  try {
+    return new URL(value);
+  } catch {
+    return undefined;
+  }
+}

package/src/server/hooks/index.ts

@@ -16,6 +16,14 @@ export {
   type CorsConfig,
   createCorsHooks,
 } from "./cors.js";
+export {
+  createErrorReportingHooks,
+  type ErrorReporterResolver,
+  type ErrorReportingContext,
+  type ErrorReportingHookArgs,
+  type ErrorReportingHooksOptions,
+  shouldReportServerError,
+} from "./error-reporting.js";
 export {
   defaultMapErrorToResponse,
   type ErrorMappingConfig,

package/src/server/server.ts

@@ -27,6 +27,7 @@ import {
 import type { AnyPorts } from "../ports/index.js";
 import {
   AuthUnauthorizedError,
+  EntitlementRequiredError,
   GateAuthorizationError,
   isUnboundPort,
   TenantRequiredError,
@@ -1158,6 +1159,20 @@ function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof EntitlementRequiredError) {
+        return {
+          ctx,
+          response: errorResponse(
+            currentError.status,
+            currentError.code,
+            currentError.message,
+            currentError.details,
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       for (const hook of hooks) {
         if (!hook.mapUnhandledError) continue;
         try {
@@ -2381,6 +2396,11 @@ export function contractsFromRoutes<
  * ```
  */
 export function defineRouteGroup<Ctx>(): RouteGroupBuilder<Ctx>;
+/**
+ * @deprecated Prefer `defineRouteGroup<Ctx>()({ ... })`. TypeScript cannot
+ * infer the route tuple generic when callers provide only `Ctx`, so the direct
+ * form preserves context checking but erases per-route contract output checks.
+ */
 export function defineRouteGroup<
   Ctx,
   // biome-ignore lint/suspicious/noExplicitAny: route contract types are erased at this level

package/src/server/use-case-route.ts

@@ -223,8 +223,8 @@ export type UseCaseRouteDef<
 /**
  * Structural check that a use case accepts the context this route provides.
  *
- * Enforced through `run` parameter contravariance so it applies even where
- * contract types are erased, such as `defineRouteGroup<Ctx>({ ... })`.
+ * Enforced through `run` parameter contravariance so it applies even at loose
+ * collection boundaries where contract types are erased.
  */
 export type UseCaseAcceptsCtx<Ctx> = {
   run: (args: { ctx: Ctx; input: never }) => Promise<unknown>;

package/src/testing/index.ts

@@ -1,13 +1,23 @@
+import {
+  createMemoryErrorReporter,
+  type MemoryErrorReporterPort,
+} from "../error-reporting/index.js";
+import { createMemoryFlags, type MemoryFlagsPort } from "../flags/index.js";
 import {
   createMemoryIdempotencyStore,
   type MemoryIdempotencyStore,
 } from "../idempotency/index.js";
+import { createMemoryLocks, type MemoryLocksPort } from "../locks/index.js";
 import { createMemoryMailer, type MemoryMailerPort } from "../mail/index.js";
 import {
   createMemoryNotificationPort,
   type MemoryNotificationPort,
 } from "../notifications/index.js";
 import { createMemoryOutbox, type MemoryOutboxPort } from "../outbox/index.js";
+import {
+  createMemoryPayments,
+  type MemoryPaymentsPort,
+} from "../payments/index.js";
 import {
   type ActivityActor,
   type ActivityTenant,
@@ -54,6 +64,7 @@ import type {
   AnyServiceProvider,
   ProviderSetupResult,
 } from "../providers/provider.js";
+import { createMemorySearch, type MemorySearchPort } from "../search/index.js";
 import { createAmbientAuditLog } from "../server/audit-context.js";
 import {
   clearActiveRequestContext,
@@ -89,11 +100,19 @@ export interface CommonTestPorts<TxPorts = AnyPorts> {
    * Recording event bus.
    */
   eventBus: EventBusPort;
+  /**
+   * In-memory error reporter.
+   */
+  errorReporter: MemoryErrorReporterPort;
   /**
    * Authorization gate. Apps with real policies should provide their own gate
    * through `overrides`.
    */
   gate: GatePort<unknown, []>;
+  /**
+   * In-memory feature flags.
+   */
+  flags: MemoryFlagsPort;
   /**
    * In-memory idempotency store.
    */
@@ -110,6 +129,10 @@ export interface CommonTestPorts<TxPorts = AnyPorts> {
    * No-op logger.
    */
   logger: LoggerPort;
+  /**
+   * In-memory lease-backed locks.
+   */
+  locks: MemoryLocksPort;
   /**
    * In-memory mailer.
    */
@@ -122,6 +145,14 @@ export interface CommonTestPorts<TxPorts = AnyPorts> {
    * In-memory outbox.
    */
   outbox: MemoryOutboxPort;
+  /**
+   * In-memory payments port.
+   */
+  payments: MemoryPaymentsPort;
+  /**
+   * In-memory search port.
+   */
+  search: MemorySearchPort;
   /**
    * In-memory rate limiter.
    */
@@ -159,6 +190,10 @@ export interface TestPortsFixture<
    * Recorded events published through `eventBus`.
    */
   events: RecordedEvent[];
+  /**
+   * Memory error reporter, exposed for assertions.
+   */
+  errorReporter: MemoryErrorReporterPort;
   /**
    * Recording job dispatcher port.
    */
@@ -179,6 +214,10 @@ export interface TestPortsFixture<
    * Memory outbox, exposed for durable workflow assertions.
    */
   outbox: MemoryOutboxPort;
+  /**
+   * Memory payments port.
+   */
+  payments: MemoryPaymentsPort;
   /**
    * Memory storage port.
    */
@@ -191,6 +230,10 @@ export interface TestPortsFixture<
    * Test cache port.
    */
   cache: CachePort;
+  /**
+   * Test feature flags port.
+   */
+  flags: MemoryFlagsPort;
   /**
    * Test rate-limit port.
    */
@@ -199,6 +242,14 @@ export interface TestPortsFixture<
    * Test logger port.
    */
   logger: LoggerPort;
+  /**
+   * Test locks port.
+   */
+  locks: MemoryLocksPort;
+  /**
+   * Test search port.
+   */
+  search: MemorySearchPort;
   /**
    * Test clock port.
    */
@@ -323,14 +374,22 @@ export function createTestPorts<
   const cache = createMemoryCache();
   const clock = options.clock ?? createFrozenClock();
   const { bus: eventBus, events } = createRecordingEventBus();
+  const errorReporter = createMemoryErrorReporter();
+  const flags = createMemoryFlags();
   const { jobs, dispatchedJobs } = createRecordingJobDispatcher();
   const idempotency = createMemoryIdempotencyStore();
   const ids = options.ids ?? createUuidIdGenerator();
   const logger = createNoopLogger();
+  const locks = createMemoryLocks({
+    now: () => clock.now(),
+    sleep: createClockAwareSleep(clock),
+  });
   const mailer = createMemoryMailer();
   const notifications = createMemoryNotificationPort();
   const outbox = createMemoryOutbox();
+  const payments = createMemoryPayments();
   const rateLimit = createMemoryRateLimiter();
+  const search = createMemorySearch();
   const storage = createMemoryStorage();
 
   const defaultPorts = {
@@ -338,15 +397,20 @@ export function createTestPorts<
     cache,
     clock,
     eventBus,
+    errorReporter,
+    flags,
     gate: createGate({ policies: [] }),
     idempotency,
     ids,
     jobs,
     logger,
+    locks,
     mailer,
     notifications,
     outbox,
+    payments,
     rateLimit,
+    search,
     storage,
   };
   const overrides = completeTestPortOverrides(options.overrides);
@@ -409,16 +473,21 @@ export function createTestPorts<
     audit,
     eventBus,
     events,
+    errorReporter,
     jobs,
     dispatchedJobs,
     mailer,
     notifications,
     outbox,
+    payments,
     storage,
     idempotency,
     cache,
+    flags,
     rateLimit,
     logger,
+    locks,
+    search,
     clock,
     ids,
     uow,
@@ -432,6 +501,19 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+function createClockAwareSleep(
+  clock: ClockPort,
+): (ms: number) => Promise<void> {
+  const maybeFrozenClock = clock as Partial<{ advance(ms: number): void }>;
+  if (typeof maybeFrozenClock.advance === "function") {
+    return async (ms) => {
+      maybeFrozenClock.advance?.(ms);
+    };
+  }
+
+  return (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function createMissingTestPortMember(
   portKey: string,
   member: string,
@@ -799,7 +881,7 @@ export interface TestContextFixture<Ctx, Ports extends AnyPorts>
 
 /**
  * Create a one-call test context fixture for jobs, listeners, schedules,
- * notifications, tasks, and use-case tests.
+ * notifications, payments, tasks, and use-case tests.
  *
  * The fixture builds common memory ports through `createTestPorts(...)`,
  * assembles an app context with actor, tenant, request ID, trace ID, auth,