@beignet/core 0.0.32 → 0.0.34

package/src/outbox/index.ts

@@ -269,6 +269,116 @@ export interface OutboxMarkFailedInput {
   now?: Date;
 }
 
+/**
+ * Default maximum messages returned from outbox admin list calls.
+ */
+export const DEFAULT_OUTBOX_ADMIN_LIST_LIMIT = 50;
+
+/**
+ * Shared filters for outbox admin read operations.
+ */
+export interface OutboxMessageQuery {
+  /**
+   * Status or statuses to include.
+   */
+  status?: OutboxMessageStatus | readonly OutboxMessageStatus[];
+  /**
+   * Message kind to include.
+   */
+  kind?: OutboxMessageKind;
+  /**
+   * Event or job name to include.
+   */
+  name?: string;
+  /**
+   * Include messages last updated before this timestamp.
+   */
+  updatedBefore?: Date;
+  /**
+   * Include delivered messages delivered before this timestamp.
+   */
+  deliveredBefore?: Date;
+}
+
+/**
+ * Options for listing outbox messages through the admin port.
+ */
+export interface OutboxListMessagesOptions extends OutboxMessageQuery {
+  /**
+   * Maximum messages to return. Defaults to
+   * `DEFAULT_OUTBOX_ADMIN_LIST_LIMIT`.
+   */
+  limit?: number;
+}
+
+/**
+ * Options for counting outbox messages through the admin port.
+ */
+export interface OutboxCountMessagesOptions extends OutboxMessageQuery {}
+
+/**
+ * Input for returning a dead-lettered message to the pending queue.
+ */
+export interface OutboxRequeueMessageInput {
+  /**
+   * Dead-lettered message ID.
+   */
+  id: string;
+  /**
+   * Earliest time the message may be claimed again. Defaults to `now`.
+   */
+  availableAt?: Date;
+  /**
+   * Reset attempts to zero before requeueing. Defaults to preserving the
+   * attempt count so operators can decide whether to grant a fresh retry
+   * budget.
+   */
+  resetAttempts?: boolean;
+  /**
+   * Requeue timestamp.
+   */
+  now?: Date;
+}
+
+/**
+ * Input for purging dead-lettered messages.
+ */
+export interface OutboxPurgeDeadLetteredInput {
+  /**
+   * Only purge messages last updated before this timestamp. Omit only when the
+   * caller intentionally wants to purge all dead-lettered messages.
+   */
+  before?: Date;
+  /**
+   * Maximum messages to purge.
+   */
+  limit?: number;
+}
+
+/**
+ * Input for pruning delivered messages.
+ */
+export interface OutboxPruneDeliveredInput {
+  /**
+   * Prune delivered messages delivered before this timestamp.
+   */
+  before: Date;
+  /**
+   * Maximum messages to prune.
+   */
+  limit?: number;
+}
+
+/**
+ * Result for outbox admin delete operations.
+ */
+export interface OutboxDeleteResult {
+  /**
+   * Number of rows deleted.
+   */
+  deleted: number;
+}
+
 /**
  * App-facing outbox storage port.
  *
@@ -294,10 +404,48 @@ export interface OutboxPort {
   markFailed(input: OutboxMarkFailedInput): Promise<void>;
 }
 
+/**
+ * Operational outbox admin port.
+ *
+ * Keep this separate from `OutboxPort` so request and drain contexts can expose
+ * only the hot-path delivery operations. Wire this port into maintenance
+ * contexts for CLI commands, runbooks, and devtools.
+ */
+export interface OutboxAdminPort {
+  /**
+   * List messages ordered by newest update first.
+   */
+  listMessages(
+    options?: OutboxListMessagesOptions,
+  ): Promise<readonly OutboxMessage[]>;
+  /**
+   * Count messages matching admin filters.
+   */
+  countMessages(options?: OutboxCountMessagesOptions): Promise<number>;
+  /**
+   * Fetch one message by ID.
+   */
+  getMessage(id: string): Promise<OutboxMessage | null>;
+  /**
+   * Return a dead-lettered message to pending state.
+   */
+  requeueMessage(input: OutboxRequeueMessageInput): Promise<OutboxMessage>;
+  /**
+   * Delete dead-lettered messages.
+   */
+  purgeDeadLettered(
+    input?: OutboxPurgeDeadLetteredInput,
+  ): Promise<OutboxDeleteResult>;
+  /**
+   * Delete delivered messages older than a retention cutoff.
+   */
+  pruneDelivered(input: OutboxPruneDeliveredInput): Promise<OutboxDeleteResult>;
+}
+
 /**
  * In-memory outbox for tests and local examples.
  */
-export interface MemoryOutboxPort extends OutboxPort {
+export interface MemoryOutboxPort extends OutboxPort, OutboxAdminPort {
   /**
    * Current message snapshots.
    */
@@ -504,6 +652,22 @@ export class OutboxClaimError extends Error {
   }
 }
 
+/**
+ * Error thrown when an outbox admin operation cannot be completed safely.
+ */
+export class OutboxAdminError extends Error {
+  /**
+   * Message ID involved in the admin error, when applicable.
+   */
+  readonly id?: string;
+
+  constructor(args: { message: string; id?: string }) {
+    super(args.message);
+    this.name = "OutboxAdminError";
+    this.id = args.id;
+  }
+}
+
 function assertNonEmptyString(name: string, value: string): void {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`${name} must be a non-empty string`);
@@ -516,6 +680,12 @@ function assertPositiveInteger(name: string, value: number): void {
   }
 }
 
+function assertValidDate(name: string, value: Date): void {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error(`${name} must be a valid Date`);
+  }
+}
+
 function cloneDate(value: Date): Date {
   return new Date(value.getTime());
 }
@@ -645,6 +815,75 @@ function copyMessage(message: OutboxMessage): OutboxMessage {
   };
 }
 
+function normalizeStatusFilter(
+  status: OutboxMessageQuery["status"],
+): ReadonlySet<OutboxMessageStatus> | undefined {
+  if (status === undefined) return undefined;
+  return new Set(Array.isArray(status) ? status : [status]);
+}
+
+function messageMatchesQuery(
+  message: OutboxMessage,
+  query: OutboxMessageQuery = {},
+): boolean {
+  const statuses = normalizeStatusFilter(query.status);
+  if (statuses && !statuses.has(message.status)) return false;
+  if (query.kind !== undefined && message.kind !== query.kind) return false;
+  if (query.name !== undefined && message.name !== query.name) return false;
+  if (
+    query.updatedBefore !== undefined &&
+    message.updatedAt.getTime() >= query.updatedBefore.getTime()
+  ) {
+    return false;
+  }
+  if (
+    query.deliveredBefore !== undefined &&
+    (message.deliveredAt === null ||
+      message.deliveredAt.getTime() >= query.deliveredBefore.getTime())
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function compareMessagesForAdminList(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const updated = right.updatedAt.getTime() - left.updatedAt.getTime();
+  if (updated !== 0) return updated;
+  const created = right.createdAt.getTime() - left.createdAt.getTime();
+  if (created !== 0) return created;
+  return right.id.localeCompare(left.id);
+}
+
+function compareMessagesForAdminCleanup(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const updated = left.updatedAt.getTime() - right.updatedAt.getTime();
+  if (updated !== 0) return updated;
+  const created = left.createdAt.getTime() - right.createdAt.getTime();
+  if (created !== 0) return created;
+  return left.id.localeCompare(right.id);
+}
+
+function compareDeliveredMessagesForPrune(
+  left: OutboxMessage,
+  right: OutboxMessage,
+): number {
+  const delivered =
+    (left.deliveredAt?.getTime() ?? 0) - (right.deliveredAt?.getTime() ?? 0);
+  if (delivered !== 0) return delivered;
+  return compareMessagesForAdminCleanup(left, right);
+}
+
+function resolveAdminListLimit(limit: number | undefined): number {
+  const resolved = limit ?? DEFAULT_OUTBOX_ADMIN_LIST_LIMIT;
+  assertPositiveInteger("limit", resolved);
+  return resolved;
+}
+
 function toClaimedMessage(message: OutboxMessage): ClaimedOutboxMessage {
   if (
     message.status !== "claimed" ||
@@ -764,6 +1003,120 @@ export function createMemoryOutbox(
       return [...messages.values()].map(copyMessage);
     },
 
+    async listMessages(options = {}) {
+      const limit = resolveAdminListLimit(options.limit);
+      if (options.updatedBefore) {
+        assertValidDate("updatedBefore", options.updatedBefore);
+      }
+      if (options.deliveredBefore) {
+        assertValidDate("deliveredBefore", options.deliveredBefore);
+      }
+
+      return [...messages.values()]
+        .filter((message) => messageMatchesQuery(message, options))
+        .sort(compareMessagesForAdminList)
+        .slice(0, limit)
+        .map(copyMessage);
+    },
+
+    async countMessages(options = {}) {
+      if (options.updatedBefore) {
+        assertValidDate("updatedBefore", options.updatedBefore);
+      }
+      if (options.deliveredBefore) {
+        assertValidDate("deliveredBefore", options.deliveredBefore);
+      }
+
+      return [...messages.values()].filter((message) =>
+        messageMatchesQuery(message, options),
+      ).length;
+    },
+
+    async getMessage(id) {
+      assertNonEmptyString("id", id);
+      const message = messages.get(id);
+      return message ? copyMessage(message) : null;
+    },
+
+    async requeueMessage(input) {
+      assertNonEmptyString("id", input.id);
+      const message = messages.get(input.id);
+      if (!message) {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" does not exist.`,
+        });
+      }
+      if (message.status !== "deadLettered") {
+        throw new OutboxAdminError({
+          id: input.id,
+          message: `Outbox message "${input.id}" is not dead-lettered.`,
+        });
+      }
+
+      const now = input.now ?? storeNow();
+      const availableAt = input.availableAt ?? now;
+      assertValidDate("now", now);
+      assertValidDate("availableAt", availableAt);
+
+      message.status = "pending";
+      message.availableAt = cloneDate(availableAt);
+      message.claimToken = null;
+      message.claimedAt = null;
+      message.lockedUntil = null;
+      if (input.resetAttempts) message.attempts = 0;
+      message.updatedAt = cloneDate(now);
+
+      return copyMessage(message);
+    },
+
+    async purgeDeadLettered(input = {}) {
+      const limit =
+        input.limit === undefined
+          ? undefined
+          : resolveAdminListLimit(input.limit);
+      if (input.before) assertValidDate("before", input.before);
+
+      const candidates = [...messages.values()]
+        .filter(
+          (message) =>
+            message.status === "deadLettered" &&
+            (input.before === undefined ||
+              message.updatedAt.getTime() < input.before.getTime()),
+        )
+        .sort(compareMessagesForAdminCleanup)
+        .slice(0, limit);
+
+      for (const message of candidates) {
+        messages.delete(message.id);
+      }
+
+      return { deleted: candidates.length };
+    },
+
+    async pruneDelivered(input) {
+      assertValidDate("before", input.before);
+      const limit =
+        input.limit === undefined
+          ? undefined
+          : resolveAdminListLimit(input.limit);
+      const candidates = [...messages.values()]
+        .filter(
+          (message) =>
+            message.status === "delivered" &&
+            message.deliveredAt !== null &&
+            message.deliveredAt.getTime() < input.before.getTime(),
+        )
+        .sort(compareDeliveredMessagesForPrune)
+        .slice(0, limit);
+
+      for (const message of candidates) {
+        messages.delete(message.id);
+      }
+
+      return { deleted: candidates.length };
+    },
+
     async enqueue(input) {
       const message = createOutboxMessage(input, {
         createId: createStoreId,
@@ -1058,7 +1411,10 @@ async function deliverOutboxMessage(
     }
   )[SINGLE_ATTEMPT_DISPATCH];
   if (singleAttempt) {
-    await singleAttempt(job, payload);
+    await singleAttempt(job, payload, {
+      attempt: message.attempts,
+      maxAttempts: message.maxAttempts,
+    });
     return;
   }
 

package/src/ports/events.ts

@@ -51,9 +51,9 @@ export type InferJobPayload<J extends JobDef> = InferContractJobPayload<J>;
  *
  * @example
  * ```ts
- * import { createInMemoryEventBus } from "@beignet/provider-event-bus-memory";
+ * import { createMemoryEventBus } from "@beignet/provider-event-bus-memory";
  *
- * const eventBus = createInMemoryEventBus();
+ * const eventBus = createMemoryEventBus();
  *
  * // Subscribe to an event
  * const unsubscribe = eventBus.subscribe(UserRegistered, (payload) => {

package/src/ports/index.ts

@@ -224,7 +224,6 @@ export {
   createMemoryFlags,
   createStaticFlags,
   defineFlag,
-  defineFlagRegistry,
   defineFlags,
   evaluateFlag,
   getFlagDetails,
@@ -281,14 +280,22 @@ export type {
  */
 export type {
   ClaimedOutboxMessage,
+  OutboxAdminPort,
   OutboxClaimBatchOptions,
+  OutboxCountMessagesOptions,
+  OutboxDeleteResult,
   OutboxEnqueueInput,
+  OutboxListMessagesOptions,
   OutboxMarkDeliveredInput,
   OutboxMarkFailedInput,
   OutboxMessage,
   OutboxMessageKind,
+  OutboxMessageQuery,
   OutboxMessageStatus,
   OutboxPort,
+  OutboxPruneDeliveredInput,
+  OutboxPurgeDeadLetteredInput,
+  OutboxRequeueMessageInput,
 } from "../outbox/index.js";
 /**
  * Payments port exports.
@@ -359,6 +366,15 @@ export {
   SearchOptionsError,
   searchDocuments,
 } from "../search/index.js";
+/**
+ * Tenant scope exports.
+ */
+export type { TenantScope } from "../tenancy/index.js";
+export {
+  createTenantScope,
+  requireTenantScope,
+  tenantScopeId,
+} from "../tenancy/index.js";
 /**
  * Webhook exports.
  *

package/src/providers/instrumentation.ts

@@ -39,6 +39,10 @@ export interface BaseProviderInstrumentationEvent {
    * W3C traceparent header value, when available.
    */
   traceparent?: string;
+  /**
+   * W3C tracestate value associated with the current operation.
+   */
+  tracestate?: string;
   /**
    * Watcher category used by devtools and instrumentation sinks.
    */

package/src/providers/provider.ts

@@ -170,7 +170,7 @@ export interface ServiceProviderMetadata {
  *
  * @example
  * ```ts
- * const redisCacheProvider = createProvider({
+ * const cacheProvider = createProvider({
  *   name: "cache-redis",
  *   config: {
  *     schema: z.object({ URL: z.string().url() }),

package/src/schedules/index.ts

@@ -1,4 +1,6 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { runWithResolvedTracingContext } from "../tracing/execution.js";
+import type { TracingPort } from "../tracing/index.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -134,9 +136,7 @@ export interface ScheduleHandleArgs<S extends ScheduleDef, Ctx> {
    * Parsed schedule payload.
    */
   payload: InferSchedulePayload<S>;
-  /**
-   * Handler context.
-   */
+  /** Handler context. */
   ctx: Ctx;
   /**
    * Run metadata.
@@ -219,10 +219,10 @@ export type ScheduleRunArgs<
   Ctx,
   Payload = unknown,
 > = ScheduleRunOptions<Payload> & {
-  /**
-   * Handler context.
-   */
-  ctx: Ctx;
+  /** Handler context or factory resolved inside the schedule span. */
+  ctx: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
 };
 
 /**
@@ -374,6 +374,8 @@ export interface InlineScheduleRunnerOptions<Ctx> {
    * Static schedule context or factory evaluated for each run.
    */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /** Runtime tracing port used before a lazy context factory runs. */
+  tracing?: TracingPort;
   /**
    * Clock used when run timestamps are not provided.
    */
@@ -575,14 +577,33 @@ function createRunContext(
   };
 }
 
-async function resolveCtx<Ctx>(
-  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
-): Promise<Ctx> {
-  if (typeof ctx === "function") {
-    return (ctx as () => MaybePromise<Ctx>)();
-  }
+function scheduleTraceOperation(
+  schedule: ScheduleDef,
+  options: ScheduleRunOptions<unknown>,
+) {
+  const attributes = {
+    "beignet.schedule.name": schedule.name,
+    ...(options.attempt === undefined
+      ? {}
+      : { "beignet.schedule.attempt": options.attempt }),
+    ...(options.source === undefined
+      ? {}
+      : { "beignet.schedule.source": options.source }),
+  } as const;
+  const metricAttributes = {
+    "beignet.schedule.name": schedule.name,
+    ...(options.attempt === undefined
+      ? {}
+      : { "beignet.schedule.attempt": options.attempt }),
+  } as const;
 
-  return ctx as Ctx;
+  return {
+    name: `beignet.schedule ${schedule.name}`,
+    type: "schedule" as const,
+    kind: "consumer" as const,
+    attributes,
+    metricAttributes,
+  };
 }
 
 async function resolveSchedulePayload<S extends ScheduleDef>(
@@ -739,14 +760,21 @@ export async function runSchedule<
   schedule: S,
   args: ScheduleRunArgs<Ctx, InferSchedulePayload<S>>,
 ): Promise<void> {
-  const run = createRunContext(args, () => new Date());
-  const payload = await resolveSchedulePayload(schedule, args, run);
-
-  await schedule.handle({
-    schedule,
-    payload,
+  await runWithResolvedTracingContext({
+    tracing: args.tracing,
     ctx: args.ctx,
-    run,
+    operation: scheduleTraceOperation(schedule, args),
+    run: async (ctx) => {
+      const run = createRunContext(args, () => new Date());
+      const payload = await resolveSchedulePayload(schedule, args, run);
+
+      await schedule.handle({
+        schedule,
+        payload,
+        ctx,
+        run,
+      });
+    },
   });
 }
 
@@ -780,11 +808,17 @@ export function createInlineScheduleRunner<Ctx>(
           options.onHookError,
           lifecycleArgs,
         );
-        await schedule.handle({
-          schedule,
-          payload,
-          ctx: await resolveCtx(options.ctx),
-          run,
+        await runWithResolvedTracingContext({
+          tracing: options.tracing,
+          ctx: options.ctx as Ctx | (() => MaybePromise<Ctx>),
+          operation: scheduleTraceOperation(schedule, runOptions),
+          run: (ctx) =>
+            schedule.handle({
+              schedule,
+              payload: payload as InferSchedulePayload<S>,
+              ctx,
+              run,
+            }),
         });
         await recordScheduleEvent(options, schedule, "completed", run, {
           payload,

package/src/server/hooks/index.ts

@@ -46,6 +46,16 @@ export {
   type RateLimitIpSource,
   type RateLimitOptions,
 } from "./rate-limit.js";
+export {
+  applySecurityHeaders,
+  type CsrfFailureReason,
+  type CsrfHooksOptions,
+  type CsrfTokenOptions,
+  createCsrfHooks,
+  createSecurityHeadersHooks,
+  type SecurityHeadersOptions,
+  type StrictTransportSecurityOptions,
+} from "./security.js";
 
 /**
  * Flatten hook arrays into a single hook list.