effect-mq 0.3.2 → 0.4.0

package/src/MemoryJobStore.ts

@@ -55,6 +55,7 @@ interface MemJob {
   timeoutMs: number | undefined
   cancelRequested: boolean
   readonly dedupeKey: string | undefined
+  trace: JobRecord["trace"]
   runAt: number
   readonly enqueuedAt: number
   processedAt: number | undefined
@@ -85,6 +86,7 @@ const snapshot = (job: MemJob): JobRecord => ({
   timeoutMs: job.timeoutMs,
   cancelRequested: job.cancelRequested,
   dedupeKey: job.dedupeKey,
+  trace: job.trace,
   runAt: job.runAt,
   enqueuedAt: job.enqueuedAt,
   processedAt: job.processedAt,
@@ -278,9 +280,63 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
     }
   }
 
-  const service: Service = JobStore.of({
-    enqueue: (request: EnqueueRequest) =>
-      Effect.gen(function*() {
+  const cancelJob = (id: JobId) =>
+    Effect.gen(function*() {
+      const now = yield* Clock.currentTimeMillis
+      const job = jobs.get(id)
+      if (job === undefined) {
+        return yield* new JobNotFoundError({ jobId: id })
+      }
+      switch (job.state) {
+        case "waiting":
+        case "delayed": {
+          markCancelled(job, now)
+          return
+        }
+        case "active": {
+          job.cancelRequested = true
+          return
+        }
+        default: {
+          return yield* new JobNotCancellableError({ jobId: id, state: job.state })
+        }
+      }
+    })
+
+  const insertJobRecord = (id: JobId, request: EnqueueRequest, now: number) => {
+    jobs.set(id, {
+      id,
+      name: request.name,
+      queue: request.queue,
+      payload: request.payload,
+      metadata: request.metadata,
+      state: request.delayMs > 0 ? "delayed" : "waiting",
+      priority: request.priority,
+      attemptsMax: request.attemptsMax,
+      attemptsMade: 0,
+      stalledCount: 0,
+      backoff: request.backoff,
+      keep: request.keep,
+      timeoutMs: request.timeoutMs,
+      cancelRequested: false,
+      dedupeKey: request.dedupe?.key,
+      trace: request.trace,
+      runAt: now + Math.max(0, request.delayMs),
+      enqueuedAt: now,
+      processedAt: undefined,
+      finishedAt: undefined,
+      exit: undefined,
+      failedReason: undefined,
+      attempts: [],
+      seq: ++seq,
+      lockToken: undefined,
+      lockExpiresAt: undefined
+    })
+    signalWake(request.queue)
+  }
+
+  const enqueueOne = (request: EnqueueRequest) =>
+    Effect.gen(function*() {
         const now = yield* Clock.currentTimeMillis
         if (request.id !== undefined && jobs.has(request.id)) {
           return { id: request.id, duplicate: true }
@@ -302,6 +358,7 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
               keyed.backoff = request.backoff
               keyed.keep = request.keep
               keyed.timeoutMs = request.timeoutMs
+              keyed.trace = request.trace
               keyed.runAt = now + Math.max(0, request.delayMs)
               // A landed replace re-arms the ttl window.
               if (request.dedupe.ttlMs !== undefined) {
@@ -349,42 +406,20 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
             }
           }
         }
-        jobs.set(id, {
-          id,
-          name: request.name,
-          queue: request.queue,
-          payload: request.payload,
-          metadata: request.metadata,
-          state: request.delayMs > 0 ? "delayed" : "waiting",
-          priority: request.priority,
-          attemptsMax: request.attemptsMax,
-          attemptsMade: 0,
-          stalledCount: 0,
-          backoff: request.backoff,
-          keep: request.keep,
-          timeoutMs: request.timeoutMs,
-          cancelRequested: false,
-          dedupeKey: request.dedupe?.key,
-          runAt: now + Math.max(0, request.delayMs),
-          enqueuedAt: now,
-          processedAt: undefined,
-          finishedAt: undefined,
-          exit: undefined,
-          failedReason: undefined,
-          attempts: [],
-          seq: ++seq,
-          lockToken: undefined,
-          lockExpiresAt: undefined
-        })
+        insertJobRecord(id, request, now)
         if (request.dedupe !== undefined) {
           dedupes.set(dedupeMapKey(request.name, request.dedupe.key), {
             jobId: id,
             expiresAt: request.dedupe.ttlMs !== undefined ? now + request.dedupe.ttlMs : undefined
           })
         }
-        signalWake(request.queue)
         return { id, duplicate: false }
-      }),
+      })
+
+  const service: Service = JobStore.of({
+    enqueue: enqueueOne,
+
+    enqueueMany: (requests) => Effect.forEach(requests, enqueueOne),
 
     claim: (options) =>
       Effect.gen(function*() {
@@ -652,27 +687,18 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
         signalWake(job.queue)
       }),
 
-    cancel: (id) =>
-      Effect.gen(function*() {
-        const now = yield* Clock.currentTimeMillis
-        const job = jobs.get(id)
-        if (job === undefined) {
-          return yield* new JobNotFoundError({ jobId: id })
-        }
-        switch (job.state) {
-          case "waiting":
-          case "delayed": {
-            markCancelled(job, now)
-            return
-          }
-          case "active": {
-            job.cancelRequested = true
-            return
-          }
-          default: {
-            return yield* new JobNotCancellableError({ jobId: id, state: job.state })
-          }
-        }
+    cancel: cancelJob,
+
+    cancelByDedupe: (name, key) =>
+      Effect.suspend(() => {
+        const entry = dedupes.get(dedupeMapKey(name, key))
+        if (entry === undefined) return Effect.succeed(false)
+        return cancelJob(entry.jobId).pipe(
+          Effect.as(true),
+          // Idempotent: a vanished or already-terminal keyed job is "nothing
+          // pending", not an error.
+          Effect.catchTag(["JobNotFoundError", "JobNotCancellableError"], () => Effect.succeed(false))
+        )
       }),
 
     promote: (id) =>
@@ -747,6 +773,29 @@ const makeStoreUnsafe = (options?: MemoryJobStoreOptions | undefined): MemorySto
         }
       }),
 
+    tickSchedule: (key, expectedRunAt, nextRunAt, request) =>
+      Effect.gen(function*() {
+        const id = request.id
+        if (id === undefined) {
+          return yield* new JobStoreError({
+            message: "tickSchedule requires an explicit request.id"
+          })
+        }
+        const now = yield* Clock.currentTimeMillis
+        // One synchronous block: CAS, insert, and advance commit together —
+        // no yield point can interleave another sweeper between them.
+        const schedule = schedules.get(key)
+        if (schedule === undefined || schedule.nextRunAt !== expectedRunAt) {
+          return false
+        }
+        schedules.set(key, { ...schedule, nextRunAt })
+        // Slot already materialized (pre-0.4 crash between enqueue and
+        // advance): the schedule still advances, but nothing new fired.
+        if (jobs.has(id)) return false
+        insertJobRecord(id, request, now)
+        return true
+      }),
+
     counts: (queue) =>
       Effect.sync(() => {
         const counts = {

package/src/Worker.ts

@@ -124,6 +124,24 @@ export interface WorkerOptions<StoreId = JobStore> {
    * sampling costs one store query per queue per tick).
    */
   readonly queueMetricsInterval?: Duration.Input | undefined
+  /**
+   * Name for the span wrapping each handler run (default
+   * `` `${context.name}.run` ``). The span carries `effectMqJobId`,
+   * `effectMqQueue`, and `effectMqAttempt` attributes and — when the
+   * producer enqueued inside a span — joins the producing trace as its
+   * child.
+   */
+  readonly handlerSpanName?: ((context: JobContext) => string) | undefined
+  /**
+   * How the handler span attaches to the producer's persisted trace:
+   * - `"auto"` (default): immediate enqueues CONTINUE the producer trace
+   *   (parent-child); explicitly delayed/`at`-scheduled ones start their own
+   *   trace with a causal LINK back (long-delayed parent-child traces render
+   *   badly and defeat tail sampling).
+   * - `"parent"` / `"link"`: force one mode for every job.
+   * - `"none"`: spans and attributes only, no cross-trace edge.
+   */
+  readonly traceLinking?: "auto" | "parent" | "link" | "none" | undefined
   /** Identifier used in lock tokens (default: random). */
   readonly id?: string | undefined
 }
@@ -335,9 +353,43 @@ export const make = <StoreId = JobStore>(
           // it as a defect so it flows through normal retry accounting.
           // timeoutOrElse (not timeout + a catch on TimeoutError) so a
           // handler's OWN typed TimeoutError failure stays a typed failure.
+          // Each run gets a span (configurable name) tagged with the job
+          // id, parented on the PRODUCER's persisted span context when
+          // present — so producer -> handler traces connect across
+          // processes.
+          const linking = options?.traceLinking ?? "auto"
+          const attach = record.trace === undefined
+            ? "none"
+            : linking === "auto"
+            ? (record.trace.delayed ? "link" : "parent")
+            : linking
+          const producerSpan = record.trace === undefined ? undefined : Tracer.externalSpan({
+            traceId: record.trace.traceId,
+            spanId: record.trace.spanId,
+            sampled: record.trace.sampled
+          })
+          const withRunSpan = entry.run(record.payload, context).pipe(
+            Effect.withSpan(
+              options?.handlerSpanName?.(context) ?? `${record.name}.run`,
+              {
+                attributes: {
+                  effectMqJobId: record.id,
+                  effectMqQueue: record.queue,
+                  effectMqAttempt: context.attempt
+                },
+                links: attach === "link" && producerSpan !== undefined
+                  ? [{ span: producerSpan, attributes: {} }]
+                  : undefined
+              },
+              { captureStackTrace: false }
+            )
+          )
+          const spanned = attach === "parent" && producerSpan !== undefined
+            ? withRunSpan.pipe(Effect.withParentSpan(producerSpan))
+            : withRunSpan
           const handlerEffect = record.timeoutMs === undefined
-            ? entry.run(record.payload, context)
-            : entry.run(record.payload, context).pipe(
+            ? spanned
+            : spanned.pipe(
               Effect.timeoutOrElse({
                 duration: record.timeoutMs,
                 orElse: () =>
@@ -581,10 +633,10 @@ export const make = <StoreId = JobStore>(
       Effect.forever
     )
 
-    // Tick one due repeatable-job schedule. The enqueue id is deterministic
-    // per (schedule, slot), so concurrent sweepers across workers dedup
-    // naturally; advanceSchedule is conditional, so double-advances are
-    // no-ops.
+    // Tick one due repeatable-job schedule. tickSchedule is a single atomic
+    // op (CAS on nextRunAt + insert + advance), so concurrent sweepers fire
+    // each slot exactly once — even when the previous slot's job row has
+    // already been pruned by retention.
     const sweepSchedule = (schedule: ScheduleRecord) =>
       Effect.gen(function*() {
         const now = yield* Clock.currentTimeMillis
@@ -595,7 +647,7 @@ export const make = <StoreId = JobStore>(
             `effect-mq: schedule "${schedule.key}" has an invalid cron/every configuration; skipping`
           )
         }
-        const tick = yield* retryStore(store.enqueue({
+        const fired = yield* retryStore(store.tickSchedule(schedule.key, slot, next, {
           id: JobId(`sched/${schedule.key}/${slot}`),
           name: schedule.jobName,
           queue: schedule.queue,
@@ -607,15 +659,15 @@ export const make = <StoreId = JobStore>(
           keep: schedule.keep,
           timeoutMs: schedule.timeoutMs,
           dedupe: undefined,
+          trace: undefined,
           delayMs: 0
         }))
-        if (!tick.duplicate) {
+        if (fired) {
           yield* Metric.update(
             Metrics.scheduleTicks.pipe(Metric.withAttributes({ name: schedule.jobName })),
             1
           )
         }
-        yield* retryStore(store.advanceSchedule(schedule.key, slot, next))
       })
 
     // Each due schedule is swept in isolation so one poison row (bad cron,