Skip to content

feat: job outcome and cancel for varmq - #22

Merged
fahimfaisaal merged 10 commits into
mainfrom
feat/outcome-cancel
Nov 9, 2026
Merged

fahimfaisaal merged 10 commits into
mainfrom
feat/outcome-cancel

Conversation

@fahimfaisaal

@fahimfaisaal fahimfaisaal commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

Job outcome and job cancel for varmq durable handles (varmq spec/redis-storage.md 1.6.0 §6.13, 1.7.0 §6.14). Without them, varmq handles on sqliteq report ErrDetached / ErrCancelUnsupported. Pairs with goptics/varmq#179 (merged; pins contract v0.6.0, varmq main 6bc553d); redisq equivalent goptics/redisq#33.

What

Queue and PriorityQueue implement contract.OutcomeWatcher, ResultAcknowledgeable, JobCanceller, CancelNotifier, CancelAcknowledgeable (compile-time asserts).

  • Sidecar tables per queue: <name>__sqliteq_jobs (outcome per Job ID) and <name>__sqliteq_cancelled (marks, 24 h each), both AUTOINCREMENT seq.
  • Finish (Acknowledge / Reject / AcknowledgeResult / AcknowledgeCancelled) writes outcome + clears mark in its tx. Reject reason now stored as outcome error.
  • Pops gate on live marks: marked waiting job dropped, outcome cancelled, cap 1000 drops per tx. Batch pop at cap reports 1 left; single pops go on.
  • EnqueueOnce that stores an id clears old record + mark (AFTER INSERT trigger). Purge clears both.
  • Watches and OnCancel poll by seq cursor (new rows only, 50 ms), one goroutine per queue object, only while watches or hooks exist. Same goroutine sweeps retention + expired marks each minute.
  • OnCancel hooks carry own start seq, picked after the read: hook added mid-poll gets its marks, stopped hook none. Outcome reaches only watches started before the read (re-add safe).

SQLite vs Redis spec

  • No pub/sub: polling. varmq adds OnCancel per worker, so consumer queue objects poll marks for life (light SELECT ~20/s).
  • Job ID = job_id column, else item JSON id parsed in Go.
  • Retention: spec defaults, trimmed on 1st and every 100th record in finish tx, plus minute sweep. Count trim spares records < 1 min, so a burst can't trim one before a poll reads it.
  • Expired marks pruned in CancelJob and the sweep.
  • Non-ack Dequeue gated too. Kept rows (WithRemoveOnComplete(false)) get status cancelled.
  • No workflow exception at pop (no sqliteq workflow store yet).
  • Txs BEGIN IMMEDIATE. Finish always in a tx, also rounds of one. One EXISTS read per pop.

Blast Radius: sqliteq API, go.mod

  • Requires Go 1.27 (varmq dep). CI + README bumped.
  • Plain users: each finish now a tx; each pop one extra read; JSON items with id get outcome records.
  • Queues.Close (last ref) now closes its queue handles.
  • Queue names must not contain __sqliteq_ (both layouts): sidecar names use it.

Review

Six parallel reviews (Matt Pocock code-review, code-reviewer, feature-dev reviewer, security audit, Go concurrency, test engineer). Fixed in 7cc1fd6 / e009366: lost watches under a finish burst (reproduced: 2787 of 4000), hook races, re-add delivery, drop cap overrun, sweep, reserved names, test gaps. Not fixed: varmq batchAckSource.fetch drops remaining when n == 0 (varmq side); case-insensitive id key (matches varmq decode); varmq root is a pseudo-version of main 6bc553d (contract is tagged v0.6.0), tag before release.

Tests

go test -race -count=3 ./... green, go vet clean. New tests in queue_test.go / priority_queue_test.go: outcome via ack/reject/result, invalid JSON, ended-before-watch, two queue objects on one file, cancel waiting/running/ended, re-add, Purge, OnCancel, retention, drop cap, batched group-commit finishes, Close with live watch/hook, 3000-watch burst, sidecars on v0.2 file, undecodable envelopes as plain jobs, varmq end to end (NewResultQueue.Add -> Result() across queue objects, remote Cancel waiting + running).

Go 1.27 (varmq root needs it). contract pinned too: varmq's replace
is not inherited.
OutcomeWatcher, ResultAcknowledgeable, JobCanceller, CancelNotifier,
CancelAcknowledgeable on Queue and PriorityQueue (spec 6.13, 6.14).

Sidecar tables <name>__sqliteq_jobs (outcome per Job ID, retention)
and <name>__sqliteq_cancelled (marks, AUTOINCREMENT seq). Job ID =
job_id, else item JSON id. Finish writes outcome + clears mark in its
tx. Pops gate on live marks, drop with outcome cancelled, cap 1000.
EnqueueOnce re-add clears both via AFTER INSERT trigger. Purge clears
both. No pub/sub: one poll goroutine per queue object, 50 ms, only
while watches or hooks exist. Txs begin IMMEDIATE.
A poll from before an OnCancel reset no longer advances lastSeq past
the new hook's marks. A batch pop stopped at maxDrops reports one item
left so the caller pops again. Go 1.27 under Breaking.
go.mod needs 1.27 now. Note that a multi-statement op opens its own
tx in a round of one.
@codecov

codecov Bot commented Nov 8, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.77670% with 38 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
outcome.go 92.57% 15 Missing ⚠️
queue.go 88.54% 15 Missing ⚠️
cancel.go 89.18% 8 Missing ⚠️

📢 Thoughts on this report? Let us know!

- Outcome poll reads records by seq cursor (AUTOINCREMENT), not a
  500-id sample: a burst of finishes no longer loses watches.
- Count trim spares records under 1 min old; first record of a queue
  object trims; poll sweeps retention + expired marks each minute.
  Index on marks expires_at.
- OnCancel: per-hook from seq, hooks picked after the read: a hook
  added mid-poll gets its marks, stopped or closed ones get none. A
  failed first read gives a no-op hook, not a 24 h replay.
- deliver reaches only watches started before the read (re-add).
- Drop cap per tx: claims never pass it; single pops go on past it.
- Queue names must not contain __sqliteq_.
Batched finishes (shared and fallback round), Close with live watch
and hook, hooks during a poll and stale marks, repeat cancel, gated
Dequeue to empty, kept-row ends, deliver generation, 3000-watch burst,
reserved names, sidecars on a v0.2 file, retention floor and first
record trim. Closed-queue watch check no longer vacuous.
Codecov: sweep was uncovered; DequeueWithAckId and Dequeue loop again
past maxDrops, now tested.
varmq#179 merged; contract tagged.
Bad JSON, non-string or empty id: handed out by a gated pop, finishes
as usual, no record.
@fahimfaisaal
fahimfaisaal merged commit 53c6a00 into main Nov 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant