effect-mq 0.1.0 → 0.2.0

package/src/Job.ts

@@ -30,18 +30,35 @@
  *
  * @since 0.1.0
  */
-import { type Context, Duration, Effect, type Exit, Layer, Option, Schedule, Schema } from "effect"
+import { Clock, type Context, Duration, Effect, type Exit, Layer, Option, Schedule, Schema } from "effect"
 import {
   type BackoffPolicy,
+  JobCancelledError,
   JobId,
+  type JobNotCancellableError,
   JobNotFoundError,
+  type JobNotPromotableError,
   type JobNotRetryableError,
   type JobState,
   JobStore,
   type KeepPolicy,
+  nextOccurrence,
   QueueName,
-  type Service as StoreService
+  ScheduleKey,
+  type ScheduleRecord,
+  type Service as StoreService,
+  unrecoverable
 } from "./JobStore.ts"
+
+export {
+  /**
+   * Mark an error value as unrecoverable: the worker skips the remaining
+   * retry budget and fails the job immediately. Returns the error unchanged.
+   *
+   * @since 0.2.0
+   */
+  unrecoverable
+}
 import { type JobContext, type RegisterOptions, Worker } from "./Worker.ts"
 
 const TypeId = "~effect-mq/Job" as const
@@ -94,6 +111,11 @@ export interface JobOptions {
   readonly backoff?: BackoffInput | undefined
   /** Retention for terminal records. Default: keep forever. */
   readonly keep?: KeepInput | undefined
+  /**
+   * Per-run execution time limit; the worker interrupts the handler fiber
+   * past it and the run counts as a failed attempt (retried per backoff).
+   */
+  readonly timeout?: Duration.Input | undefined
 }
 
 /**
@@ -118,6 +140,28 @@ interface ResolvedDefaults {
   readonly attempts: number
   readonly backoff: BackoffPolicy | undefined
   readonly keep: KeepPolicy | undefined
+  readonly timeoutMs: number | undefined
+}
+
+/**
+ * Options for `Job.schedule`. Exactly one of `cron` (with optional IANA `tz`)
+ * or `every` must be set. `cron` schedules first fire at the next matching
+ * occurrence; `every` schedules first fire one interval from now.
+ *
+ * @since 0.2.0
+ */
+export interface ScheduleOptions<PayloadInput> {
+  readonly cron?: string | undefined
+  readonly tz?: string | undefined
+  readonly every?: Duration.Input | undefined
+  readonly payload: PayloadInput
+  /** Queryable business context, merged over the definition's `metadata`. */
+  readonly metadata?: Readonly<Record<string, string>> | undefined
+  readonly priority?: number | undefined
+  readonly attempts?: number | undefined
+  readonly backoff?: BackoffInput | undefined
+  readonly keep?: KeepInput | undefined
+  readonly timeout?: Duration.Input | undefined
 }
 
 /**
@@ -144,8 +188,8 @@ export interface JobAttempt<A, E> {
   readonly attempt: number
   readonly startedAt: number | undefined
   readonly finishedAt: number
-  readonly outcome: "completed" | "retried" | "failed" | "stalled"
-  /** Absent for `stalled` entries. */
+  readonly outcome: "completed" | "retried" | "failed" | "stalled" | "cancelled"
+  /** Absent for `stalled` and `cancelled` entries. */
   readonly exit: Option.Option<Exit.Exit<A, E>>
 }
 
@@ -185,6 +229,7 @@ export interface Job<
   >
   readonly idempotencyKey: ((payload: Payload["Type"]) => string) | undefined
   readonly metadata: ((payload: Payload["Type"]) => Readonly<Record<string, string>>) | undefined
+  readonly retryable: ((error: Error["Type"]) => boolean) | undefined
   readonly defaults: ResolvedDefaults
 
   /**
@@ -248,6 +293,43 @@ export interface Job<
     jobId: JobId
   ) => Effect.Effect<void, JobNotFoundError | JobNotRetryableError, StoreId>
 
+  /**
+   * Cancel a job: waiting/delayed become terminal (`cancelled`) immediately;
+   * a running job's handler fiber is interrupted by its worker on the next
+   * heartbeat (latency ≤ `lockRenewInterval`).
+   */
+  readonly cancel: (
+    jobId: JobId
+  ) => Effect.Effect<void, JobNotFoundError | JobNotCancellableError, StoreId>
+
+  /** Run a delayed job now. */
+  readonly promote: (
+    jobId: JobId
+  ) => Effect.Effect<void, JobNotFoundError | JobNotPromotableError, StoreId>
+
+  /**
+   * Create or replace a durable repeatable schedule for this job. Ticks
+   * enqueue with a slot-deterministic id, so schedules are exactly-once per
+   * occurrence across all workers (assuming history retention windows
+   * comfortably exceed the sweep interval — a pruned tick job cannot dedup a
+   * pathologically stale sweeper). Missed occurrences (downtime) collapse
+   * into a single catch-up run.
+   *
+   * Re-registering with an *unchanged* cadence (same `cron`/`tz`/`every`) is
+   * a no-op for the next occurrence — deploy-time re-registration neither
+   * re-anchors `every` grids nor drops a pending catch-up run. Changing the
+   * cadence resets the next occurrence.
+   */
+  readonly schedule: (
+    key: string,
+    options: ScheduleOptions<Payload["~type.make.in"]>
+  ) => Effect.Effect<ScheduleKey, never, StoreId | Payload["EncodingServices"]>
+
+  /** Remove a schedule created by `schedule`. False when it did not exist. */
+  readonly unschedule: (
+    key: string
+  ) => Effect.Effect<boolean, never, StoreId>
+
   /**
    * Attach the handler that processes this job, as a layer to provide on top
    * of `Worker.layer` (bound to the same store).
@@ -333,6 +415,9 @@ const Proto = {
               keep: options?.keep !== undefined
                 ? normalizeKeep(options.keep)
                 : this.defaults.keep,
+              timeoutMs: options?.timeout !== undefined
+                ? Duration.toMillis(options.timeout)
+                : this.defaults.timeoutMs,
               delayMs: options?.delay !== undefined
                 ? Duration.toMillis(options.delay)
                 : this.defaults.delayMs
@@ -418,6 +503,9 @@ const Proto = {
           return yield* Effect.die(new JobNotFoundError({ jobId }))
         }
         const { exit, failedReason, state } = status.value
+        if (state === "cancelled") {
+          return yield* Effect.die(new JobCancelledError({ jobId }))
+        }
         if (state === "completed" || state === "failed") {
           if (Option.isSome(exit)) {
             return yield* exit.value
@@ -458,6 +546,84 @@ const Proto = {
       )
   },
 
+  cancel(this: AnyWithProps, jobId: JobId) {
+    return Effect.flatMap(this.store, (store) =>
+      store.cancel(jobId).pipe(
+        Effect.catchTag("JobStoreError", (error) => Effect.die(error))
+      )).pipe(
+        Effect.withSpan(`${this._tag}.cancel`, { attributes: { jobId } }, { captureStackTrace: false })
+      )
+  },
+
+  promote(this: AnyWithProps, jobId: JobId) {
+    return Effect.flatMap(this.store, (store) =>
+      store.promote(jobId).pipe(
+        Effect.catchTag("JobStoreError", (error) => Effect.die(error))
+      )).pipe(
+        Effect.withSpan(`${this._tag}.promote`, { attributes: { jobId } }, { captureStackTrace: false })
+      )
+  },
+
+  schedule(this: AnyWithProps, key: string, options: ScheduleOptions<never>) {
+    const self = this
+    return Effect.gen(function*() {
+      const hasCron = options.cron !== undefined
+      const hasEvery = options.every !== undefined
+      if (hasCron === hasEvery) {
+        return yield* Effect.die(
+          new Error(`effect-mq: schedule "${key}" must set exactly one of \`cron\` or \`every\``)
+        )
+      }
+      const everyMs = options.every !== undefined ? Duration.toMillis(options.every) : undefined
+      const now = yield* Clock.currentTimeMillis
+      const nextRunAt = nextOccurrence(
+        { cron: options.cron, tz: options.tz, everyMs },
+        now,
+        now
+      )
+      if (nextRunAt === undefined) {
+        return yield* Effect.die(
+          new Error(`effect-mq: schedule "${key}" has an invalid cron expression: "${options.cron}"`)
+        )
+      }
+      const payload = self.payloadSchema.make(options.payload)
+      const encoded = yield* Schema.encodeEffect(self.payloadJsonSchema)(payload).pipe(Effect.orDie)
+      const scheduleKey = ScheduleKey(`${self._tag}/${key}`)
+      const record: ScheduleRecord = {
+        key: scheduleKey,
+        jobName: self._tag,
+        queue: self.queue,
+        cron: options.cron,
+        tz: options.tz,
+        everyMs,
+        payload: encoded,
+        metadata: { ...self.metadata?.(payload), ...options.metadata },
+        priority: options.priority ?? self.defaults.priority,
+        attemptsMax: Math.max(1, options.attempts ?? self.defaults.attempts),
+        backoff: options.backoff !== undefined
+          ? normalizeBackoff(options.backoff)
+          : self.defaults.backoff,
+        keep: options.keep !== undefined ? normalizeKeep(options.keep) : self.defaults.keep,
+        timeoutMs: options.timeout !== undefined
+          ? Duration.toMillis(options.timeout)
+          : self.defaults.timeoutMs,
+        nextRunAt
+      }
+      const store = yield* self.store
+      yield* store.upsertSchedule(record).pipe(Effect.orDie)
+      return scheduleKey
+    }).pipe(
+      Effect.withSpan(`${this._tag}.schedule`, { attributes: { key } }, { captureStackTrace: false })
+    )
+  },
+
+  unschedule(this: AnyWithProps, key: string) {
+    return Effect.flatMap(this.store, (store) =>
+      store.removeSchedule(ScheduleKey(`${this._tag}/${key}`)).pipe(Effect.orDie)).pipe(
+        Effect.withSpan(`${this._tag}.unschedule`, { attributes: { key } }, { captureStackTrace: false })
+      )
+  },
+
   toLayer(
     this: AnyWithProps,
     handler: (payload: any, context: JobContext) => Effect.Effect<any, any, any>,
@@ -476,6 +642,10 @@ const boundMethods = [
   "awaitResult",
   "execute",
   "retry",
+  "cancel",
+  "promote",
+  "schedule",
+  "unschedule",
   "toLayer"
 ] as const
 
@@ -490,6 +660,7 @@ const makeProto = (options: {
   readonly exitSchema: Schema.Top
   readonly idempotencyKey: ((payload: any) => string) | undefined
   readonly metadata: ((payload: any) => Readonly<Record<string, string>>) | undefined
+  readonly retryable: ((error: any) => boolean) | undefined
   readonly defaults: ResolvedDefaults
 }): any => {
   function JobDefinition() {}
@@ -550,6 +721,15 @@ export const make = <
           : Payload["Type"]
       ) => Readonly<Record<string, string>>)
       | undefined
+    /**
+     * When present, a typed handler failure for which this returns false
+     * skips the remaining retry budget (see also `Job.unrecoverable`).
+     */
+    readonly retryable?:
+      | ((
+        error: Error["Type"]
+      ) => boolean)
+      | undefined
     /** The queue this job runs on. Default `"default"`. */
     readonly queue?: string | undefined
     /**
@@ -593,6 +773,7 @@ export const make = <
     exitSchema,
     idempotencyKey: options.idempotencyKey,
     metadata: options.metadata,
+    retryable: options.retryable,
     defaults: {
       delayMs: options.defaults?.delay !== undefined
         ? Duration.toMillis(options.defaults.delay)
@@ -600,7 +781,10 @@ export const make = <
       priority: options.defaults?.priority ?? 0,
       attempts: Math.max(1, options.defaults?.attempts ?? 1),
       backoff: normalizeBackoff(options.defaults?.backoff),
-      keep: normalizeKeep(options.defaults?.keep)
+      keep: normalizeKeep(options.defaults?.keep),
+      timeoutMs: options.defaults?.timeout !== undefined
+        ? Duration.toMillis(options.defaults.timeout)
+        : undefined
     }
   })
 }

package/src/JobStore.ts

@@ -16,7 +16,7 @@
  *
  * @since 0.1.0
  */
-import { Brand, Context, Data, type Effect, type Option, Predicate } from "effect"
+import { Brand, Context, Cron, Data, type Effect, type Option, Predicate, Result } from "effect"
 
 /**
  * The identifier of an enqueued job. Produced by `enqueue` (either
@@ -47,6 +47,20 @@ export type QueueName = Brand.Branded<string, "effect-mq/QueueName">
  */
 export const QueueName: Brand.Constructor<QueueName> = Brand.nominal<QueueName>()
 
+/**
+ * The identifier of a repeatable-job schedule.
+ *
+ * @since 0.2.0
+ */
+export type ScheduleKey = Brand.Branded<string, "effect-mq/ScheduleKey">
+
+/**
+ * Brand a raw string as a `ScheduleKey`.
+ *
+ * @since 0.2.0
+ */
+export const ScheduleKey: Brand.Constructor<ScheduleKey> = Brand.nominal<ScheduleKey>()
+
 /**
  * The lifecycle states of a job.
  *
@@ -57,7 +71,13 @@ export const QueueName: Brand.Constructor<QueueName> = Brand.nominal<QueueName>(
  *
  * @since 0.1.0
  */
-export type JobState = "waiting" | "delayed" | "active" | "completed" | "failed"
+export type JobState =
+  | "waiting"
+  | "delayed"
+  | "active"
+  | "completed"
+  | "failed"
+  | "cancelled"
 
 /**
  * Retry backoff policy, persisted on the job record so any worker can route
@@ -103,7 +123,7 @@ export interface AttemptRecord {
   readonly startedAt: number | undefined
   /** Ack/recovery time of this run (epoch millis). */
   readonly finishedAt: number
-  readonly outcome: "completed" | "retried" | "failed" | "stalled"
+  readonly outcome: "completed" | "retried" | "failed" | "stalled" | "cancelled"
   /** Schema-encoded `Exit`; undefined for `stalled`. */
   readonly exit: unknown
 }
@@ -131,6 +151,13 @@ export interface JobRecord {
   readonly stalledCount: number
   readonly backoff: BackoffPolicy | undefined
   readonly keep: KeepPolicy | undefined
+  /** Per-run execution time limit; the worker interrupts the handler past it. */
+  readonly timeoutMs: number | undefined
+  /**
+   * Set by `cancel` on an active job; the owning worker interrupts the
+   * handler on its next heartbeat and acks `Cancelled`.
+   */
+  readonly cancelRequested: boolean
   /** Epoch millis before which the job must not be claimed. */
   readonly runAt: number
   readonly enqueuedAt: number
@@ -160,9 +187,27 @@ export interface EnqueueRequest {
   readonly attemptsMax: number
   readonly backoff: BackoffPolicy | undefined
   readonly keep: KeepPolicy | undefined
+  readonly timeoutMs: number | undefined
   readonly delayMs: number
 }
 
+/**
+ * Generator for store-assigned job ids, used when `EnqueueRequest.id` is
+ * undefined (custom ids and idempotency keys always win, and schedule tick
+ * ids stay slot-deterministic). May be effectful (e.g. draw from Effect's
+ * `Random`). The store retries a bounded number of times when a generated id
+ * collides with an existing job, then fails the enqueue with
+ * `JobStoreError` — generators must have enough entropy that collisions are
+ * pathological, not routine.
+ *
+ * @example `({ name }) => \`${name}_${ulid()}\``
+ *
+ * @since 0.2.0
+ */
+export type IdGenerator = (
+  request: EnqueueRequest
+) => string | Effect.Effect<string>
+
 /**
  * @since 0.1.0
  */
@@ -213,6 +258,7 @@ export type AckOutcome =
   | { readonly _tag: "Complete"; readonly exit: unknown }
   | { readonly _tag: "Retry"; readonly delayMs: number; readonly exit: unknown }
   | { readonly _tag: "Fail"; readonly exit: unknown }
+  | { readonly _tag: "Cancelled" }
 
 /**
  * Filters and pagination for `list`. Results are ordered newest-first
@@ -241,6 +287,45 @@ export interface ListResult {
   readonly cursor: string | undefined
 }
 
+/**
+ * A repeatable-job schedule as persisted by the store. Exactly one of `cron`
+ * (with optional IANA `tz`) or `everyMs` is set. The payload is stored
+ * schema-encoded, like job payloads. `nextRunAt` is maintained by the worker
+ * sweep via `advanceSchedule`; ticks enqueue with the deterministic id
+ * `sched/<key>/<slot>`, so concurrent sweepers dedup naturally.
+ *
+ * @since 0.2.0
+ */
+export interface ScheduleRecord {
+  readonly key: ScheduleKey
+  readonly jobName: string
+  readonly queue: QueueName
+  readonly cron: string | undefined
+  readonly tz: string | undefined
+  readonly everyMs: number | undefined
+  readonly payload: unknown
+  readonly metadata: Readonly<Record<string, string>>
+  readonly priority: number
+  readonly attemptsMax: number
+  readonly backoff: BackoffPolicy | undefined
+  readonly keep: KeepPolicy | undefined
+  readonly timeoutMs: number | undefined
+  /** Epoch millis of the next occurrence to enqueue. */
+  readonly nextRunAt: number
+}
+
+/**
+ * Result of a heartbeat: locks that could not be extended (lost to stall
+ * recovery or another worker) and active jobs with a pending cancel request
+ * (the worker must interrupt them and ack `Cancelled`).
+ *
+ * @since 0.2.0
+ */
+export interface ExtendLocksResult {
+  readonly lost: ReadonlyArray<JobId>
+  readonly cancelRequested: ReadonlyArray<JobId>
+}
+
 /**
  * A transient or fatal driver error (connection loss, serialization, etc.).
  *
@@ -260,6 +345,73 @@ export class JobStoreError extends Data.TaggedError("JobStoreError")<{
 export const isJobStoreError = (u: unknown): u is JobStoreError =>
   Predicate.hasProperty(u, "_tag") && u._tag === "JobStoreError"
 
+// Identity-based marking (WeakSet, works on frozen error instances) so the
+// error keeps its declared type and schema round-trip untouched.
+const unrecoverableRegistry = new WeakSet<object>()
+
+/**
+ * Mark an error value as unrecoverable: when a handler fails with it, the
+ * worker skips the remaining retry budget and fails the job immediately. The
+ * error itself is returned unchanged, so typed error channels and schemas
+ * are unaffected. Also exported as `Job.unrecoverable`.
+ *
+ * Marking is identity-based, so it only works for object errors — a
+ * primitive (string/number) failure is returned unmarked and retries
+ * normally; use the definition-level `retryable` predicate for those.
+ *
+ * @since 0.2.0
+ */
+export const unrecoverable = <E>(error: E): E => {
+  if (Object(error) === error) {
+    // SAFETY: `Object(x) === x` is true exactly for object values, which is
+    // what WeakSet membership requires.
+    unrecoverableRegistry.add(error as object)
+  }
+  return error
+}
+
+/**
+ * Whether `unrecoverable` marked this value.
+ *
+ * @internal
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- boundary classifier over arbitrary error values
+export const isMarkedUnrecoverable = (u: unknown): boolean =>
+  // SAFETY: `Object(u) === u` short-circuits to false for primitives, so the
+  // assertion only ever passes object values to the WeakSet.
+  Object(u) === u && unrecoverableRegistry.has(u as object)
+
+/**
+ * The next occurrence of a schedule strictly after `now`. `fromSlot` anchors
+ * `everyMs` schedules (occurrences stay on the `slot + k * every` grid).
+ * Returns undefined for an invalid cron expression.
+ *
+ * @internal
+ */
+export const nextOccurrence = (
+  schedule: Pick<ScheduleRecord, "cron" | "tz" | "everyMs">,
+  fromSlot: number,
+  now: number
+): number | undefined => {
+  if (schedule.cron !== undefined) {
+    const parsed = Cron.parse(schedule.cron, schedule.tz)
+    if (Result.isFailure(parsed)) return undefined
+    // Cron.next throws for parseable-but-unsatisfiable expressions (e.g.
+    // "0 0 30 2 *"); treat those as invalid rather than defecting the sweep.
+    try {
+      return Cron.next(parsed.success, new Date(Math.max(fromSlot, now))).getTime()
+    } catch {
+      return undefined
+    }
+  }
+  if (schedule.everyMs !== undefined && schedule.everyMs > 0) {
+    const behind = Math.max(0, now - fromSlot)
+    const steps = Math.floor(behind / schedule.everyMs) + 1
+    return fromSlot + steps * schedule.everyMs
+  }
+  return undefined
+}
+
 
 /**
  * The presented lock token no longer owns the job (it stalled and was
@@ -288,6 +440,35 @@ export class JobNotRetryableError extends Data.TaggedError("JobNotRetryableError
   readonly state: JobState
 }> {}
 
+/**
+ * `cancel` was called on a job that is already terminal.
+ *
+ * @since 0.2.0
+ */
+export class JobNotCancellableError extends Data.TaggedError("JobNotCancellableError")<{
+  readonly jobId: JobId
+  readonly state: JobState
+}> {}
+
+/**
+ * `promote` was called on a job that is not in the `delayed` state.
+ *
+ * @since 0.2.0
+ */
+export class JobNotPromotableError extends Data.TaggedError("JobNotPromotableError")<{
+  readonly jobId: JobId
+  readonly state: JobState
+}> {}
+
+/**
+ * Raised (as a defect) by `awaitResult` when the awaited job was cancelled.
+ *
+ * @since 0.2.0
+ */
+export class JobCancelledError extends Data.TaggedError("JobCancelledError")<{
+  readonly jobId: JobId
+}> {}
+
 /**
  * The service shape every store implements.
  *
@@ -339,7 +520,7 @@ export interface Service {
   readonly extendLocks: (
     locks: ReadonlyArray<{ readonly id: JobId; readonly token: string }>,
     durationMs: number
-  ) => Effect.Effect<ReadonlyArray<JobId>, JobStoreError>
+  ) => Effect.Effect<ExtendLocksResult, JobStoreError>
 
   /**
    * Sweep active jobs whose lock has expired. Each recovered job gets
@@ -391,6 +572,73 @@ export interface Service {
     JobStoreError | JobNotFoundError | JobNotRetryableError
   >
 
+  /**
+   * Cancel a job. Waiting/delayed jobs become terminal (`cancelled`)
+   * immediately; active jobs get `cancelRequested` set, and the owning
+   * worker interrupts the handler on its next heartbeat. Terminal jobs fail
+   * with `JobNotCancellableError`.
+   */
+  readonly cancel: (
+    id: JobId
+  ) => Effect.Effect<
+    void,
+    JobStoreError | JobNotFoundError | JobNotCancellableError
+  >
+
+  /** Move a delayed job to `waiting` now. */
+  readonly promote: (
+    id: JobId
+  ) => Effect.Effect<
+    void,
+    JobStoreError | JobNotFoundError | JobNotPromotableError
+  >
+
+  /**
+   * Durably pause a queue: claims return `Empty` until `resume` (delayed
+   * jobs still promote to `waiting`, they just aren't handed out). Affects
+   * every worker on the store.
+   */
+  readonly pause: (queue: QueueName) => Effect.Effect<void, JobStoreError>
+
+  /** Undo `pause` and wake idle workers. */
+  readonly resume: (queue: QueueName) => Effect.Effect<void, JobStoreError>
+
+  readonly pausedQueues: () => Effect.Effect<
+    ReadonlyArray<QueueName>,
+    JobStoreError
+  >
+
+  /** Create or replace a repeatable-job schedule (keyed by `schedule.key`). */
+  readonly upsertSchedule: (
+    schedule: ScheduleRecord
+  ) => Effect.Effect<void, JobStoreError>
+
+  /** Remove a schedule. Returns false when the key does not exist. */
+  readonly removeSchedule: (
+    key: ScheduleKey
+  ) => Effect.Effect<boolean, JobStoreError>
+
+  readonly listSchedules: (options?: {
+    readonly jobName?: string | undefined
+    readonly queue?: QueueName | undefined
+  }) => Effect.Effect<ReadonlyArray<ScheduleRecord>, JobStoreError>
+
+  /** Schedules whose `nextRunAt` is due (per the Effect `Clock`). */
+  readonly dueSchedules: () => Effect.Effect<
+    ReadonlyArray<ScheduleRecord>,
+    JobStoreError
+  >
+
+  /**
+   * Advance a schedule's `nextRunAt` from `expectedRunAt` to `nextRunAt`
+   * (conditional, so concurrent sweepers cannot regress it).
+   */
+  readonly advanceSchedule: (
+    key: ScheduleKey,
+    expectedRunAt: number,
+    nextRunAt: number
+  ) => Effect.Effect<void, JobStoreError>
+
   readonly counts: (
     queue?: QueueName
   ) => Effect.Effect<Record<JobState, number>, JobStoreError>