effect-mq 0.3.2 → 0.4.0

package/src/redis/RedisJobStore.ts

@@ -84,6 +84,7 @@ const toRecord = (hash: ReadonlyMap<string, string>): JobStore.JobRecord => ({
   timeoutMs: optionalNumber(hash.get("timeoutMs")),
   cancelRequested: hash.get("cancelRequested") === "1",
   dedupeKey: optionalString(hash.get("dedupeKey")),
+  trace: optionalJson<JobStore.TraceContext>(hash.get("trace")),
   runAt: Number(hash.get("runAt") ?? 0),
   enqueuedAt: Number(hash.get("enqueuedAt") ?? 0),
   processedAt: optionalNumber(hash.get("processedAt")),
@@ -154,6 +155,8 @@ export const make = (
     const evalListSchedules = redis.eval(scripts.listSchedules)
     const evalDueSchedules = redis.eval(scripts.dueSchedules)
     const evalAdvanceSchedule = redis.eval(scripts.advanceSchedule)
+    const evalTickSchedule = redis.eval(scripts.tickSchedule)
+    const evalEnqueueMany = redis.eval(scripts.enqueueMany)
     const evalSweepState = redis.eval(scripts.sweepState)
     const evalSweepDedupes = redis.eval(scripts.sweepDedupes)
 
@@ -277,53 +280,198 @@ export const make = (
         request.dedupe?.key ?? "",
         request.dedupe?.ttlMs === undefined ? "" : String(request.dedupe.ttlMs),
         request.dedupe?.extend === true ? "1" : "0",
-        request.dedupe?.replace === true ? "1" : "0"
+        request.dedupe?.replace === true ? "1" : "0",
+        request.trace === undefined ? "" : JSON.stringify(request.trace)
       )
 
-    const store: JobStore.Service = {
-      enqueue: (request) =>
-        Effect.gen(function*() {
+    // Shared by cancel and cancelByDedupe.
+    const cancelJob = (id: JobStore.JobId) =>
+      Effect.gen(function*() {
+        const now = yield* Clock.currentTimeMillis
+        const reply: { error?: string; state?: JobStore.JobState } = JSON.parse(
+          yield* evalCancel(prefix, id, now).pipe(Effect.mapError(storeError("cancel failed")))
+        )
+        if (reply.error === "notfound") return yield* new JobStore.JobNotFoundError({ jobId: id })
+        if (reply.error === "state") {
+          return yield* new JobStore.JobNotCancellableError({ jobId: id, state: reply.state ?? "completed" })
+        }
+      })
+
+    const enqueueJob = (request: JobStore.EnqueueRequest) =>
+      Effect.gen(function*() {
+        const now = yield* Clock.currentTimeMillis
+        const generate = options?.idGenerator
+        for (let i = 0; i < 5; i++) {
+          const mode = request.id !== undefined
+            ? "user" as const
+            : generate !== undefined
+            ? "generated" as const
+            : "auto" as const
+          const candidate = mode === "user"
+            ? request.id ?? ""
+            : mode === "generated" && generate !== undefined
+            ? yield* generateCandidate(request, generate)
+            : ""
+          const reply: {
+            id?: string
+            duplicate?: boolean
+            wake?: boolean
+            collision?: boolean
+            error?: string
+            queue?: string
+          } = JSON.parse(yield* enqueueOnce(request, mode, candidate, now))
+          if (reply.collision === true) continue
+          if (reply.error !== undefined || reply.id === undefined) {
+            return yield* new JobStore.JobStoreError({
+              message: "enqueue failed: could not generate a unique job id"
+            })
+          }
+          if (reply.wake === true) {
+            // A replace-while-delayed reply names the keyed job's queue.
+            yield* wakeUp(reply.queue !== undefined ? JobStore.QueueName(reply.queue) : request.queue)
+          }
+          return { id: JobStore.JobId(reply.id), duplicate: reply.duplicate === true }
+        }
+        return yield* new JobStore.JobStoreError({
+          message: "enqueue failed: could not generate a unique job id"
+        })
+      }).pipe(
+        Effect.mapError((error) =>
+          error instanceof JobStore.JobStoreError ? error : storeError("enqueue failed")(error)
+        )
+      )
+
+    // One EVALSHA per chunk of plain (non-dedup) items. Ids resolve in-script
+    // ("auto") or client-side (user/generated); a generated id that collides
+    // re-draws and retries in the next round, like the single-enqueue path.
+    const insertBatch = (requests: ReadonlyArray<JobStore.EnqueueRequest>) =>
+      Effect.gen(function*() {
+        const generate = options?.idGenerator
+        const results: Array<JobStore.EnqueueResult | undefined> = requests.map(() => undefined)
+        let pending = requests.map((request, index) => ({ request, index }))
+        for (let round = 0; round < 5 && pending.length > 0; round++) {
           const now = yield* Clock.currentTimeMillis
-          const generate = options?.idGenerator
-          for (let i = 0; i < 5; i++) {
-            const mode = request.id !== undefined
-              ? "user" as const
-              : generate !== undefined
-              ? "generated" as const
-              : "auto" as const
-            const candidate = mode === "user"
-              ? request.id ?? ""
-              : mode === "generated" && generate !== undefined
-              ? yield* generateCandidate(request, generate)
-              : ""
-            const reply: {
-              id?: string
-              duplicate?: boolean
-              wake?: boolean
-              collision?: boolean
-              error?: string
-              queue?: string
-            } = JSON.parse(yield* enqueueOnce(request, mode, candidate, now))
-            if (reply.collision === true) continue
-            if (reply.error !== undefined || reply.id === undefined) {
+          const stillPending: typeof pending = []
+          for (let start = 0; start < pending.length; start += 500) {
+            const chunk = pending.slice(start, start + 500)
+            const itemArgs: Array<string> = []
+            for (const { request } of chunk) {
+              const mode = request.id !== undefined
+                ? "user"
+                : generate !== undefined
+                ? "generated"
+                : "auto"
+              const candidate = request.id !== undefined
+                ? request.id
+                : generate !== undefined
+                ? yield* generateCandidate(request, generate)
+                : ""
+              itemArgs.push(
+                mode,
+                candidate,
+                request.name,
+                request.queue,
+                JSON.stringify(request.payload ?? null),
+                JSON.stringify(request.metadata),
+                String(request.priority),
+                String(request.attemptsMax),
+                request.backoff === undefined ? "" : JSON.stringify(request.backoff),
+                request.keep === undefined ? "" : JSON.stringify(request.keep),
+                request.timeoutMs === undefined ? "" : String(request.timeoutMs),
+                request.trace === undefined ? "" : JSON.stringify(request.trace),
+                String(Math.max(0, request.delayMs))
+              )
+            }
+            const replies: Array<{ id?: string; duplicate?: boolean; collision?: boolean; error?: string }> = JSON
+              .parse(yield* evalEnqueueMany(prefix, now, chunk.length, itemArgs))
+            const freshQueues = new Set<JobStore.QueueName>()
+            let failed = false
+            for (let i = 0; i < chunk.length; i++) {
+              const reply = replies[i]
+              const item = chunk[i]
+              if (item === undefined) continue
+              if (reply === undefined || reply.error !== undefined) {
+                failed = true
+                continue
+              }
+              if (reply.collision === true) {
+                // Generated-id collision: re-draw and re-insert next round.
+                // NOTE this lands the item after its batch-mates in FIFO
+                // order — acceptable for a pathological collision, and
+                // documented on the contract.
+                stillPending.push(item)
+                continue
+              }
+              if (reply.id === undefined) {
+                failed = true
+                continue
+              }
+              results[item.index] = { id: JobStore.JobId(reply.id), duplicate: reply.duplicate === true }
+              if (reply.duplicate !== true) {
+                freshQueues.add(item.request.queue)
+              }
+            }
+            // The script is not transactional across items: inserts that
+            // landed before a failing item are durable, so wake their queues
+            // BEFORE surfacing the error.
+            for (const queue of freshQueues) {
+              yield* wakeUp(queue)
+            }
+            if (failed) {
               return yield* new JobStore.JobStoreError({
-                message: "enqueue failed: could not generate a unique job id"
+                message: "enqueueMany failed: could not generate a unique job id"
               })
             }
-            if (reply.wake === true) {
-              // A replace-while-delayed reply names the keyed job's queue.
-              yield* wakeUp(reply.queue !== undefined ? JobStore.QueueName(reply.queue) : request.queue)
+          }
+          pending = stillPending
+        }
+        const resolved: Array<JobStore.EnqueueResult> = []
+        for (const result of results) {
+          if (result === undefined) {
+            return yield* new JobStore.JobStoreError({
+              message: "enqueueMany failed: could not generate a unique job id"
+            })
+          }
+          resolved.push(result)
+        }
+        return resolved
+      }).pipe(
+        Effect.mapError((error) =>
+          error instanceof JobStore.JobStoreError ? error : storeError("enqueueMany failed")(error)
+        )
+      )
+
+    const store: JobStore.Service = {
+      enqueue: enqueueJob,
+
+      enqueueMany: (requests) =>
+        Effect.gen(function*() {
+          const results: Array<JobStore.EnqueueResult> = []
+          let batch: Array<JobStore.EnqueueRequest> = []
+          const flush = () =>
+            Effect.gen(function*() {
+              if (batch.length === 0) return
+              const items = batch
+              batch = []
+              // No spread: a six-figure batch would blow the engine's
+              // argument-count limit after the rows already committed.
+              for (const result of yield* insertBatch(items)) {
+                results.push(result)
+              }
+            })
+          for (const request of requests) {
+            // Dedup items run through the single-enqueue decision tree in
+            // order; runs of plain items between them batch into one script.
+            if (request.dedupe !== undefined) {
+              yield* flush()
+              results.push(yield* enqueueJob(request))
+            } else {
+              batch.push(request)
             }
-            return { id: JobStore.JobId(reply.id), duplicate: reply.duplicate === true }
           }
-          return yield* new JobStore.JobStoreError({
-            message: "enqueue failed: could not generate a unique job id"
-          })
-        }).pipe(
-          Effect.mapError((error) =>
-            error instanceof JobStore.JobStoreError ? error : storeError("enqueue failed")(error)
-          )
-        ),
+          yield* flush()
+          return results
+        }),
 
       claim: (claimOptions) =>
         // Snapshot BEFORE the script runs: a wake that fires while the claim
@@ -531,16 +679,20 @@ export const make = (
           Effect.map((raw) => raw !== "0")
         ),
 
-      cancel: (id) =>
+      cancel: (id) => cancelJob(id),
+
+      cancelByDedupe: (name, key) =>
         Effect.gen(function*() {
-          const now = yield* Clock.currentTimeMillis
-          const reply: { error?: string; state?: JobStore.JobState } = JSON.parse(
-            yield* evalCancel(prefix, id, now).pipe(Effect.mapError(storeError("cancel failed")))
+          const jobId = yield* redis.send("HGET", `${prefix}:dedupe:${name}\u0000${key}`, "jobId").pipe(
+            Effect.mapError(storeError("cancelByDedupe failed"))
+          )
+          if (jobId === null || jobId === undefined || jobId === "") return false
+          return yield* cancelJob(JobStore.JobId(String(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))
           )
-          if (reply.error === "notfound") return yield* new JobStore.JobNotFoundError({ jobId: id })
-          if (reply.error === "state") {
-            return yield* new JobStore.JobNotCancellableError({ jobId: id, state: reply.state ?? "completed" })
-          }
         }),
 
       promote: (id) =>
@@ -622,6 +774,43 @@ export const make = (
           return flat.map((pairs) => toSchedule(foldPairs(pairs)))
         }).pipe(Effect.mapError(storeError("dueSchedules failed"))),
 
+      tickSchedule: (key, expectedRunAt, nextRunAt, request) =>
+        Effect.gen(function*() {
+          if (request.id === undefined) {
+            return yield* new JobStore.JobStoreError({
+              message: "tickSchedule requires an explicit request.id"
+            })
+          }
+          const now = yield* Clock.currentTimeMillis
+          const fired = (yield* evalTickSchedule(
+            prefix,
+            key,
+            expectedRunAt,
+            nextRunAt,
+            request.id,
+            request.name,
+            request.queue,
+            JSON.stringify(request.payload ?? null),
+            JSON.stringify(request.metadata),
+            request.priority,
+            request.attemptsMax,
+            request.backoff === undefined ? "" : JSON.stringify(request.backoff),
+            request.keep === undefined ? "" : JSON.stringify(request.keep),
+            request.timeoutMs === undefined ? "" : String(request.timeoutMs),
+            request.trace === undefined ? "" : JSON.stringify(request.trace),
+            Math.max(0, request.delayMs),
+            now
+          )) === "1"
+          if (fired) {
+            yield* wakeUp(request.queue)
+          }
+          return fired
+        }).pipe(
+          Effect.mapError((error) =>
+            error instanceof JobStore.JobStoreError ? error : storeError("tickSchedule failed")(error)
+          )
+        ),
+
       advanceSchedule: (key, expectedRunAt, nextRunAt) =>
         evalAdvanceSchedule(prefix, key, expectedRunAt, nextRunAt).pipe(
           Effect.mapError(storeError("advanceSchedule failed")),

package/src/redis/scripts.ts

@@ -159,6 +159,30 @@ local function finishCancelled(id, queue, name, startedAt, now, nowStr)
   releaseDedupe(name, redis.call("HGET", jk, "dedupeKey"), id, now)
   applyKeep(name, "cancelled", redis.call("HGET", jk, "keep"), now)
 end
+-- Insert one fresh job row plus every index entry. String params are stored
+-- verbatim (payload/metadata/backoff/keep/trace are pre-encoded JSON, "" =
+-- absent); priority/delayMs/now numeric-coercible.
+local function insertJobRow(id, name, queue, payloadJson, metadataJson, priority,
+    attemptsMax, backoffJson, keepJson, timeoutMs, dedupeKey, traceJson, delayMs, now, nowStr)
+  local seq = redis.call("INCR", prefix .. ":seq")
+  local state = delayMs > 0 and "delayed" or "waiting"
+  local runAt = now + delayMs
+  redis.call("HSET", jobKey(id),
+    "id", id, "name", name, "queue", queue,
+    "payload", payloadJson, "metadata", metadataJson, "state", state,
+    "priority", priority, "attemptsMax", attemptsMax, "attemptsMade", "0", "stalledCount", "0",
+    "backoff", backoffJson, "keep", keepJson, "timeoutMs", timeoutMs,
+    "cancelRequested", "0", "dedupeKey", dedupeKey, "trace", traceJson, "runAt", fmt(runAt), "enqueuedAt", nowStr,
+    "processedAt", "", "finishedAt", "", "exit", "", "failedReason", "",
+    "lockToken", "", "lockExpiresAt", "", "seq", fmt(seq))
+  redis.call("ZADD", prefix .. ":all", now, id)
+  if state == "waiting" then
+    addWaiting(queue, tonumber(priority), seq, id)
+  else
+    redis.call("ZADD", delayedKey(queue), runAt, id)
+  end
+  countsAdd(queue, state, 1)
+end
 `
 
 /**
@@ -186,7 +210,8 @@ export const enqueue = Redis.script(
     dedupeKey: string,
     dedupeTtlMs: string,
     dedupeExtend: string,
-    dedupeReplace: string
+    dedupeReplace: string,
+    traceJson: string
   ) => [
     prefix,
     idMode,
@@ -205,7 +230,8 @@ export const enqueue = Redis.script(
     dedupeKey,
     dedupeTtlMs,
     dedupeExtend,
-    dedupeReplace
+    dedupeReplace,
+    traceJson
   ],
   {
     numberOfKeys: 0,
@@ -244,7 +270,7 @@ if dKey ~= "" then
       local newRunAt = now + delayMs
       redis.call("HSET", kjk, "payload", ARGV[6], "metadata", ARGV[7], "priority", ARGV[8],
         "attemptsMax", ARGV[9], "backoff", ARGV[10], "keep", ARGV[11], "timeoutMs", ARGV[12],
-        "runAt", fmt(newRunAt))
+        "trace", ARGV[19], "runAt", fmt(newRunAt))
       local keyedQueue = redis.call("HGET", kjk, "queue")
       redis.call("ZADD", delayedKey(keyedQueue), newRunAt, entryJob)
       -- A landed replace re-arms the ttl window.
@@ -278,24 +304,8 @@ if idMode == "auto" then
   end
   if id == "" then return '{"error":"id"}' end
 end
-local seq = redis.call("INCR", prefix .. ":seq")
-local state = delayMs > 0 and "delayed" or "waiting"
-local runAt = now + delayMs
-redis.call("HSET", jobKey(id),
-  "id", id, "name", ARGV[4], "queue", queue,
-  "payload", ARGV[6], "metadata", ARGV[7], "state", state,
-  "priority", ARGV[8], "attemptsMax", ARGV[9], "attemptsMade", "0", "stalledCount", "0",
-  "backoff", ARGV[10], "keep", ARGV[11], "timeoutMs", ARGV[12],
-  "cancelRequested", "0", "dedupeKey", dKey, "runAt", fmt(runAt), "enqueuedAt", nowStr,
-  "processedAt", "", "finishedAt", "", "exit", "", "failedReason", "",
-  "lockToken", "", "lockExpiresAt", "", "seq", fmt(seq))
-redis.call("ZADD", prefix .. ":all", now, id)
-if state == "waiting" then
-  addWaiting(queue, tonumber(ARGV[8]), seq, id)
-else
-  redis.call("ZADD", delayedKey(queue), runAt, id)
-end
-countsAdd(queue, state, 1)
+insertJobRow(id, ARGV[4], queue, ARGV[6], ARGV[7], ARGV[8], ARGV[9], ARGV[10], ARGV[11],
+  ARGV[12], dKey, ARGV[19], delayMs, now, nowStr)
 if dKey ~= "" then
   local sk = dedupeStoreKey(name, dKey)
   redis.call("DEL", sk)
@@ -940,6 +950,128 @@ return "1"
   }
 ).withReturnType<string>()
 
+/**
+ * tickSchedule(prefix, key, expectedRunAt, nextRunAt, id, name, queue,
+ *   payloadJson, metadataJson, priority, attemptsMax, backoffJson, keepJson,
+ *   timeoutMs, traceJson, delayMs, now) -> "1" fired | "0"
+ * Atomic occurrence claim: the nextRunAt CAS and the tick job's insert run
+ * in one script, so a stale sweeper can never re-fire a slot — even after
+ * retention pruned the previous slot's job row.
+ */
+export const tickSchedule = Redis.script(
+  (
+    prefix: string,
+    key: string,
+    expectedRunAt: number,
+    nextRunAt: number,
+    id: string,
+    name: string,
+    queue: string,
+    payloadJson: string,
+    metadataJson: string,
+    priority: number,
+    attemptsMax: number,
+    backoffJson: string,
+    keepJson: string,
+    timeoutMs: string,
+    traceJson: string,
+    delayMs: number,
+    now: number
+  ) => [
+    prefix,
+    key,
+    expectedRunAt,
+    nextRunAt,
+    id,
+    name,
+    queue,
+    payloadJson,
+    metadataJson,
+    priority,
+    attemptsMax,
+    backoffJson,
+    keepJson,
+    timeoutMs,
+    traceJson,
+    delayMs,
+    now
+  ],
+  {
+    numberOfKeys: 0,
+    lua: `${HELPERS}
+local key = ARGV[2]
+local sk = prefix .. ":schedule:" .. key
+local current = redis.call("HGET", sk, "nextRunAt")
+if current == false or tonumber(current) ~= tonumber(ARGV[3]) then return "0" end
+redis.call("HSET", sk, "nextRunAt", fmt(tonumber(ARGV[4])))
+redis.call("ZADD", prefix .. ":schedules", tonumber(ARGV[4]), key)
+local id = ARGV[5]
+-- Pre-existing slot row (pre-0.4 crash between enqueue and advance): the
+-- schedule still advances, but nothing new fires.
+if redis.call("EXISTS", jobKey(id)) == 1 then return "0" end
+insertJobRow(id, ARGV[6], ARGV[7], ARGV[8], ARGV[9], ARGV[10], ARGV[11], ARGV[12], ARGV[13],
+  ARGV[14], "", ARGV[15], tonumber(ARGV[16]), tonumber(ARGV[17]), ARGV[17])
+return "1"
+`
+  }
+).withReturnType<string>()
+
+/**
+ * enqueueMany(prefix, now, count, ...items) -> JSON array of per-item results
+ * ({id, duplicate} | {collision} | {error}). Items are 13-ARGV strides:
+ * idMode, id, name, queue, payloadJson, metadataJson, priority, attemptsMax,
+ * backoffJson, keepJson, timeoutMs, traceJson, delayMs. Plain (non-dedup)
+ * items only — the caller routes dedup items through \`enqueue\`.
+ */
+export const enqueueMany = Redis.script(
+  (prefix: string, now: number, count: number, items: ReadonlyArray<string>) => [prefix, now, count, ...items],
+  {
+    numberOfKeys: 0,
+    lua: `${HELPERS}
+local now = tonumber(ARGV[2])
+local nowStr = ARGV[2]
+local count = tonumber(ARGV[3])
+local out = {}
+for i = 0, count - 1 do
+  local base = 3 + i * 13
+  local idMode = ARGV[base + 1]
+  local id = ARGV[base + 2]
+  local result
+  if idMode ~= "auto" and redis.call("EXISTS", jobKey(id)) == 1 then
+    -- Sequential in-script processing makes intra-batch repeats of one user
+    -- id resolve exactly like separate enqueues: first inserts, rest dedup.
+    if idMode == "user" then
+      result = '{"id":' .. cjson.encode(id) .. ',"duplicate":true}'
+    else
+      result = '{"collision":true}'
+    end
+  else
+    if idMode == "auto" then
+      id = ""
+      for a = 1, 5 do
+        local candidate = "j-" .. fmt(redis.call("INCR", prefix .. ":seq"))
+        if redis.call("EXISTS", jobKey(candidate)) == 0 then
+          id = candidate
+          break
+        end
+      end
+    end
+    if id == "" then
+      result = '{"error":"id"}'
+    else
+      insertJobRow(id, ARGV[base + 3], ARGV[base + 4], ARGV[base + 5], ARGV[base + 6],
+        ARGV[base + 7], ARGV[base + 8], ARGV[base + 9], ARGV[base + 10], ARGV[base + 11],
+        "", ARGV[base + 12], tonumber(ARGV[base + 13]), now, nowStr)
+      result = '{"id":' .. cjson.encode(id) .. ',"duplicate":false}'
+    end
+  end
+  out[#out + 1] = result
+end
+return "[" .. table.concat(out, ",") .. "]"
+`
+  }
+).withReturnType<string>()
+
 /**
  * sweepState(prefix, state, ttlMs, limit, offset, now) -> {scanned, deleted}
  * One bounded page over a terminal state's finished zset, deleting rows past