@beignet/core 0.0.2 → 0.0.3

package/src/jobs/index.ts

@@ -16,6 +16,48 @@ export type MaybePromise<T> = T | Promise<T>;
 export type InferSchemaOutput<T extends StandardSchemaV1> =
   StandardSchemaV1.InferOutput<T>;
 
+/**
+ * Duration accepted by retry helpers. Numbers are milliseconds.
+ */
+export type JobRetryDuration =
+  | number
+  | `${number}ms`
+  | `${number}s`
+  | `${number}m`
+  | `${number}h`;
+
+/**
+ * Retry strategy understood by Beignet job adapters.
+ */
+export type JobRetryStrategy = "none" | "fixed" | "exponential";
+
+/**
+ * Arguments passed to a retry predicate.
+ */
+export interface JobRetryPredicateArgs {
+  /**
+   * Error thrown by the previous attempt.
+   */
+  error: unknown;
+  /**
+   * One-based attempt number that just failed.
+   */
+  attempt: number;
+  /**
+   * Maximum attempts allowed for this delivery.
+   */
+  maxAttempts: number;
+  /**
+   * Job name when the retry decision is for a job.
+   */
+  jobName?: string;
+}
+
+/**
+ * Return whether a failed attempt should be retried.
+ */
+export type JobRetryPredicate = (args: JobRetryPredicateArgs) => boolean;
+
 /**
  * Job definition created by `defineJob(...)`.
  */
@@ -81,12 +123,38 @@ export interface JobHandleArgs<J extends JobDef, Ctx> {
  */
 export interface JobRetryOptions {
   /**
-   * Maximum number of retry attempts a durable job adapter should request.
-   *
-   * Providers may impose their own range limits. For example, the Inngest
-   * adapter validates this as a function-level `retries` value.
+   * Retry strategy. Raw objects without a strategy default to exponential
+   * backoff so existing `{ attempts }` style definitions stay meaningful.
+   */
+  strategy?: JobRetryStrategy;
+  /**
+   * Maximum total attempts, including the first attempt.
    */
   attempts?: number;
+  /**
+   * Delay between attempts for fixed retry policies.
+   */
+  delay?: JobRetryDuration;
+  /**
+   * Initial delay for exponential retry policies.
+   */
+  initialDelay?: JobRetryDuration;
+  /**
+   * Maximum delay for exponential retry policies.
+   */
+  maxDelay?: JobRetryDuration;
+  /**
+   * Exponential multiplier. Defaults to `2`.
+   */
+  factor?: number;
+  /**
+   * Whether adapters that compute delays should add jitter.
+   */
+  jitter?: boolean;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
 }
 
 /**
@@ -117,6 +185,96 @@ export interface DefineJobOptions<
   ): MaybePromise<void>;
 }
 
+/**
+ * Options for a fixed job retry policy.
+ */
+export interface FixedJobRetryOptions {
+  /**
+   * Maximum total attempts, including the first attempt.
+   */
+  attempts: number;
+  /**
+   * Delay between attempts.
+   */
+  delay: JobRetryDuration;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
+}
+
+/**
+ * Options for an exponential job retry policy.
+ */
+export interface ExponentialJobRetryOptions {
+  /**
+   * Maximum total attempts, including the first attempt.
+   */
+  attempts: number;
+  /**
+   * Initial delay. Defaults to `1s`.
+   */
+  initialDelay?: JobRetryDuration;
+  /**
+   * Maximum delay. Defaults to `1m`.
+   */
+  maxDelay?: JobRetryDuration;
+  /**
+   * Exponential multiplier. Defaults to `2`.
+   */
+  factor?: number;
+  /**
+   * Whether computed delays should include jitter.
+   */
+  jitter?: boolean;
+  /**
+   * Optional app-owned retry classifier.
+   */
+  retryIf?: JobRetryPredicate;
+}
+
+/**
+ * Retry helper namespace for job definitions.
+ */
+export const retry = {
+  /**
+   * Disable retries. The first failure is terminal.
+   */
+  none(): JobRetryOptions {
+    return {
+      strategy: "none",
+      attempts: 1,
+    };
+  },
+
+  /**
+   * Retry with the same delay between attempts.
+   */
+  fixed(options: FixedJobRetryOptions): JobRetryOptions {
+    return validateJobRetryOptions({
+      strategy: "fixed",
+      attempts: options.attempts,
+      delay: options.delay,
+      retryIf: options.retryIf,
+    });
+  },
+
+  /**
+   * Retry with exponential backoff.
+   */
+  exponential(options: ExponentialJobRetryOptions): JobRetryOptions {
+    return validateJobRetryOptions({
+      strategy: "exponential",
+      attempts: options.attempts,
+      initialDelay: options.initialDelay,
+      maxDelay: options.maxDelay,
+      factor: options.factor,
+      jitter: options.jitter,
+      retryIf: options.retryIf,
+    });
+  },
+} as const;
+
 /**
  * Options for the inline job dispatcher.
  */
@@ -207,6 +365,165 @@ function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
     .join("; ");
 }
 
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function assertPositiveNumber(name: string, value: number): void {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive number`);
+  }
+}
+
+function durationToMs(name: string, value: JobRetryDuration): number {
+  if (typeof value === "number") {
+    assertPositiveInteger(name, value);
+    return value;
+  }
+
+  const match = /^(\d+)(ms|s|m|h)$/.exec(value);
+  if (!match) {
+    throw new Error(
+      `${name} must be a positive millisecond value or duration string like "500ms", "30s", "5m", or "1h".`,
+    );
+  }
+
+  const amount = Number(match[1]);
+  assertPositiveInteger(name, amount);
+
+  switch (match[2]) {
+    case "ms":
+      return amount;
+    case "s":
+      return amount * 1000;
+    case "m":
+      return amount * 60_000;
+    case "h":
+      return amount * 3_600_000;
+    default:
+      throw new Error(`${name} has an unsupported duration unit.`);
+  }
+}
+
+function validateJobRetryOptions(options: JobRetryOptions): JobRetryOptions {
+  const strategy = options.strategy ?? "exponential";
+
+  if (!["none", "fixed", "exponential"].includes(strategy)) {
+    throw new Error("retry.strategy must be none, fixed, or exponential");
+  }
+
+  const attempts = options.attempts ?? (strategy === "none" ? 1 : undefined);
+  if (attempts === undefined) {
+    throw new Error("retry.attempts is required");
+  }
+  assertPositiveInteger("retry.attempts", attempts);
+
+  if (strategy === "none" && attempts !== 1) {
+    throw new Error("retry.none() must use exactly one attempt");
+  }
+
+  if (strategy === "fixed") {
+    if (options.delay === undefined) {
+      throw new Error("retry.delay is required for fixed retry policies");
+    }
+    durationToMs("retry.delay", options.delay);
+  }
+
+  if (strategy === "exponential") {
+    if (options.initialDelay !== undefined) {
+      durationToMs("retry.initialDelay", options.initialDelay);
+    }
+    if (options.maxDelay !== undefined) {
+      durationToMs("retry.maxDelay", options.maxDelay);
+    }
+    if (options.factor !== undefined) {
+      assertPositiveNumber("retry.factor", options.factor);
+    }
+  }
+
+  return {
+    ...options,
+    strategy,
+    attempts,
+  };
+}
+
+/**
+ * Return the maximum total attempts configured by a retry policy.
+ */
+export function getJobRetryMaxAttempts(
+  options: JobRetryOptions | undefined,
+): number | undefined {
+  return options ? validateJobRetryOptions(options).attempts : undefined;
+}
+
+/**
+ * Return whether a failed job attempt should be retried.
+ */
+export function shouldRetryJob(
+  options: JobRetryOptions | undefined,
+  args: JobRetryPredicateArgs,
+): boolean {
+  if (!options) return args.attempt < args.maxAttempts;
+
+  const retryOptions = validateJobRetryOptions(options);
+  const maxAttempts = Math.min(
+    args.maxAttempts,
+    retryOptions.attempts ?? args.maxAttempts,
+  );
+  if (retryOptions.strategy === "none") return false;
+  if (args.attempt >= maxAttempts) return false;
+
+  return retryOptions.retryIf?.({ ...args, maxAttempts }) ?? true;
+}
+
+/**
+ * Compute the next retry delay in milliseconds for a failed job attempt.
+ */
+export function getJobRetryDelayMs(
+  options: JobRetryOptions | undefined,
+  args: Pick<JobRetryPredicateArgs, "attempt" | "error" | "jobName">,
+): number {
+  const retryOptions = options
+    ? validateJobRetryOptions(options)
+    : retry.exponential({ attempts: 3 });
+
+  let delayMs: number;
+  if (retryOptions.strategy === "fixed") {
+    delayMs = durationToMs("retry.delay", retryOptions.delay ?? "1s");
+  } else if (retryOptions.strategy === "none") {
+    delayMs = 0;
+  } else {
+    const initialDelayMs = durationToMs(
+      "retry.initialDelay",
+      retryOptions.initialDelay ?? "1s",
+    );
+    const maxDelayMs = durationToMs(
+      "retry.maxDelay",
+      retryOptions.maxDelay ?? "1m",
+    );
+    const factor = retryOptions.factor ?? 2;
+    delayMs = Math.min(
+      maxDelayMs,
+      initialDelayMs * factor ** Math.max(0, args.attempt - 1),
+    );
+  }
+
+  if (retryOptions.jitter && delayMs > 0) {
+    delayMs = Math.ceil(delayMs * (0.5 + Math.random()));
+    if (retryOptions.strategy === "exponential") {
+      delayMs = Math.min(
+        delayMs,
+        durationToMs("retry.maxDelay", retryOptions.maxDelay ?? "1m"),
+      );
+    }
+  }
+
+  return delayMs;
+}
+
 async function parsePayload<Schema extends StandardSchemaV1>(
   schema: Schema,
   input: unknown,
@@ -253,12 +570,16 @@ export function defineJob<
   name: Name,
   options: DefineJobOptions<Name, Payload, Ctx>,
 ): JobDef<Name, Payload, Ctx> {
+  const retryOptions = options.retry
+    ? validateJobRetryOptions(options.retry)
+    : undefined;
+
   return {
     kind: "job",
     name,
     payload: options.payload,
     description: options.description,
-    retry: options.retry,
+    retry: retryOptions,
     handle: options.handle as JobDef<Name, Payload, Ctx>["handle"],
   };
 }

package/src/outbox/index.ts

@@ -10,12 +10,23 @@ import {
   type InferEventPayload,
   parseEventPayload,
 } from "../events";
-import { type InferJobPayload, type JobDef, parseJobPayload } from "../jobs";
+import {
+  getJobRetryDelayMs,
+  getJobRetryMaxAttempts,
+  type InferJobPayload,
+  type JobDef,
+  parseJobPayload,
+  shouldRetryJob,
+} from "../jobs";
 import type { JobDispatcherPort } from "../ports/events";
 import type {
   BufferedDomainEventRecorder,
   DomainEventRecorderPort,
 } from "../ports/unit-of-work";
+import {
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "../providers";
 
 /**
  * Value or promise of that value.
@@ -401,6 +412,10 @@ export interface DrainOutboxOptions {
         error: unknown;
         now: Date;
       }) => number);
+  /**
+   * Optional instrumentation target for retry and dead-letter visibility.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
   /**
    * Observer called when delivery fails. Observer failures are ignored so the
    * original delivery failure still controls retry/dead-letter behavior.
@@ -852,7 +867,7 @@ export async function enqueueJob<J extends JobDef>(
     name: job.name,
     payload: toOutboxJsonValue(parsed),
     availableAt: options.availableAt,
-    maxAttempts: options.maxAttempts,
+    maxAttempts: options.maxAttempts ?? getJobRetryMaxAttempts(job.retry),
   });
 }
 
@@ -906,9 +921,38 @@ function resolveRetryDelayMs(
     return options.retryDelayMs;
   }
 
+  if (message.kind === "job") {
+    const job = options.registry.jobs.get(message.name);
+    if (job?.retry) {
+      return getJobRetryDelayMs(job.retry, {
+        attempt: message.attempts,
+        error,
+        jobName: message.name,
+      });
+    }
+  }
+
   return Math.min(60_000, 1000 * 2 ** Math.max(0, message.attempts - 1));
 }
 
+function shouldRetryOutboxMessage(
+  options: DrainOutboxOptions,
+  message: ClaimedOutboxMessage,
+  error: unknown,
+): boolean {
+  if (message.kind !== "job") {
+    return message.attempts < message.maxAttempts;
+  }
+
+  const job = options.registry.jobs.get(message.name);
+  return shouldRetryJob(job?.retry, {
+    attempt: message.attempts,
+    error,
+    jobName: message.name,
+    maxAttempts: message.maxAttempts,
+  });
+}
+
 async function deliverOutboxMessage(
   options: DrainOutboxOptions,
   message: ClaimedOutboxMessage,
@@ -962,6 +1006,13 @@ export async function drainOutbox(
 ): Promise<DrainOutboxResult> {
   const batchSize = options.batchSize ?? 100;
   assertPositiveInteger("batchSize", batchSize);
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "outbox",
+      watcher: "jobs",
+    },
+  );
 
   const now = options.now ?? new Date();
   const messages = await options.outbox.claimBatch({
@@ -992,7 +1043,8 @@ export async function drainOutbox(
         // Preserve the delivery failure path so the message is retried or
         // dead-lettered even if the observer fails.
       }
-      const deadLetter = message.attempts >= message.maxAttempts;
+      const shouldRetry = shouldRetryOutboxMessage(options, message, error);
+      const deadLetter = !shouldRetry;
       const retryDelayMs = deadLetter
         ? 0
         : resolveRetryDelayMs(options, message, error, now);
@@ -1008,8 +1060,36 @@ export async function drainOutbox(
       });
 
       if (deadLetter) {
+        if (message.kind === "job") {
+          instrumentation.record({
+            type: "job",
+            jobName: message.name,
+            status: "deadLettered",
+            details: {
+              attempt: message.attempts,
+              maxAttempts: message.maxAttempts,
+              messageId: message.id,
+              error: serializeOutboxError(error),
+            },
+          });
+        }
         result.deadLettered += 1;
       } else {
+        if (message.kind === "job") {
+          instrumentation.record({
+            type: "job",
+            jobName: message.name,
+            status: "retryScheduled",
+            details: {
+              attempt: message.attempts,
+              maxAttempts: message.maxAttempts,
+              messageId: message.id,
+              retryDelayMs,
+              retryAt: new Date(now.getTime() + retryDelayMs).toISOString(),
+              error: serializeOutboxError(error),
+            },
+          });
+        }
         result.retried += 1;
       }
     }

package/src/providers/instrumentation.ts

@@ -159,7 +159,13 @@ export interface JobProviderInstrumentationEvent
   /**
    * Job lifecycle status.
    */
-  status: "scheduled" | "started" | "completed" | "failed";
+  status:
+    | "scheduled"
+    | "started"
+    | "completed"
+    | "failed"
+    | "retryScheduled"
+    | "deadLettered";
 }
 
 /**