@bumail/queue 0.2.0 → 0.3.0

package/docs/troubleshooting.md

@@ -34,9 +34,12 @@ parts shown as … vary.
 
 - [`QueueError: The lease on … was lost before its outcome was recorded; another worker will try it again`](#queueerror-the-lease-on--was-lost-before-its-outcome-was-recorded-another-worker-will-try-it-again)
 - [`QueueError: The lease on … was lost while it was delivered`](#queueerror-the-lease-on--was-lost-while-it-was-delivered)
+- [`QueueError: The lease on … expired before its outcome was recorded, and the item is gone: lost to another worker that finished it, the message then sent twice, or cancelled`](#queueerror-the-lease-on--expired-before-its-outcome-was-recorded-and-the-item-is-gone-lost-to-another-worker-that-finished-it-the-message-then-sent-twice-or-cancelled)
+- [`QueueError: The lease on … was lost while it was delivered, and the item is gone: finished by the worker that took it, the message then sent twice, or cancelled`](#queueerror-the-lease-on--was-lost-while-it-was-delivered-and-the-item-is-gone-finished-by-the-worker-that-took-it-the-message-then-sent-twice-or-cancelled)
 - [`SmtpError: sendMail(): …` (`INVALID_OPTION`), with recipients deferred as `4.3.5`](#smtperror-sendmail--invalid_option-with-recipients-deferred-as-435)
 - [`SQLiteError: database is locked`, or another store error, during a delivery](#sqliteerror-database-is-locked-or-another-store-error-during-a-delivery)
 - [`PostgresError: …`, or a connection error, during a delivery](#postgreserror--or-a-connection-error-during-a-delivery)
+- [`RedisError: …` during a delivery: `Connection closed`, `OOM command not allowed …`, `READONLY …`](#rediserror--during-a-delivery-connection-closed-oom-command-not-allowed--readonly-)
 
 **The `bun:sqlite` store** (`@bumail/queue/sqlite`)
 
@@ -55,6 +58,16 @@ parts shown as … vary.
 - [`QueueError: The PostgreSQL queue cannot be set up: …`](#queueerror-the-postgresql-queue-cannot-be-set-up-)
 - [`QueueError: The database is at schema version …, newer than this store's …`](#queueerror-the-database-is-at-schema-version--newer-than-this-stores-), and [`QueueError: The queue store is closed`](#queueerror-the-queue-store-is-closed), as for `bun:sqlite`
 
+**The Redis store** (`@bumail/queue/redis`)
+
+- [`QueueError: A Redis queue store needs client, a Bun.RedisClient, or url, a redis:// URL`](#queueerror-a-redis-queue-store-needs-client-a-bunredisclient-or-url-a-redis-url)
+- [`QueueError: A Redis queue store takes client or url, not both`](#queueerror-a-redis-queue-store-takes-client-or-url-not-both)
+- [`QueueError: keyPrefix must be lowercase letters, digits, '_', ':', '.' and '-', starting with a letter, at most 40 characters, not …`](#queueerror-keyprefix-must-be-lowercase-letters-digits-_---and---starting-with-a-letter-at-most-40-characters-not-)
+- [`QueueError: The URL in url cannot be opened: …`](#queueerror-the-url-in-url-cannot-be-opened-)
+- [`QueueError: The Redis queue cannot be set up: …`](#queueerror-the-redis-queue-cannot-be-set-up-)
+- [`QueueError: The key …schema does not hold a layout version: is the prefix another application's?`](#queueerror-the-key-schema-does-not-hold-a-layout-version-is-the-prefix-another-applications)
+- [`QueueError: The database is at schema version …, newer than this store's …`](#queueerror-the-database-is-at-schema-version--newer-than-this-stores-), and [`QueueError: The queue store is closed`](#queueerror-the-queue-store-is-closed), as for `bun:sqlite`
+
 **Listing** (`list`)
 
 - [`QueueError: limit must be an integer from 1 to 1000, not …`](#queueerror-limit-must-be-an-integer-from-1-to-1000-not-)
@@ -63,6 +76,10 @@ parts shown as … vary.
 **A store's own checks** (a store of your own, called directly)
 
 - [`QueueError: … must be a finite number`, `owner must be a non-empty string`, and the others](#a-stores-own-checks)
+- [`QueueError: A reply is an object with a text`](#queueerror-a-reply-is-an-object-with-a-text)
+- [`QueueError: reply.status must be a string`](#queueerror-replystatus-must-be-a-string)
+- [`QueueError: reply.host must be a string`](#queueerror-replyhost-must-be-a-string)
+- [`QueueError: … holds a NUL or a lone surrogate, which a store cannot keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep)
 
 **Delivery**
 
@@ -238,8 +255,9 @@ or `… must be a number from … to …, not …`. A number option out of its r
 
 ### `QueueError: owner must be a non-empty string`
 
-**Code:** `INVALID`, also as `owner holds a NUL or a lone surrogate,
-which a store cannot keep`. Leave `owner` out for a random one, or give
+**Code:** `INVALID`, also as
+[`owner holds a NUL or a lone surrogate, which a store cannot keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep).
+Leave `owner` out for a random one, or give
 each worker its own name.
 
 ## The `error` event
@@ -256,8 +274,54 @@ the process stalled longer than that, or the store could not be reached.
 
 ### `QueueError: The lease on … was lost while it was delivered`
 
-**Code:** `LEASE_LOST`. A renewal found the lease taken: the same cause as
-above, seen sooner.
+**Code:** `LEASE_LOST`. A renewal was refused while the item was still in
+the store, held by another worker or by none (another worker took it and
+let go of it): the same cause as above, seen sooner. A renewal that finds the item gone
+says nothing: the outcome, once the sessions end, tells a cancel from a
+lease lost (below).
+
+### `QueueError: The lease on … expired before its outcome was recorded, and the item is gone: lost to another worker that finished it, the message then sent twice, or cancelled`
+
+**Code:** `LEASE_LOST`.
+**When:** a delivery ran past its lease's expiry — no renewal reached the
+store in time — and, when it tried to record its outcome, the item was no
+longer in the store. No `delivered`, `deferred` or `failed` event and no
+DSN come from this attempt.
+**Why:** past its expiry, another worker may claim the item, deliver it
+and drop it; but a `cancel` drops it too, and the store keeps no record of
+which happened. The worker cannot tell them apart, so it says both rather
+than report outcomes nobody recorded. When another worker took it, the
+recipients both reached got the message twice; that worker's events tell
+what it delivered.
+**Fix:** as for the lease lost above: a longer `leaseMs`, or find what
+stalled the process — an event loop blocked, a store out of reach. A
+cancel under a lease that still held is told as before: its outcomes on
+the events, with no error and no DSN.
+
+When the instances' clocks are out of step, one whose clock runs ahead
+can claim the item while this worker's own clock says the lease still
+holds. If it finishes and drops the item between two of this worker's
+renewals, no renewal saw it taken and the expiry has not passed by this
+clock: the attempt reads as a cancel, its outcomes told on the events
+with no error. Keep the machines on NTP; the 10-minute `leaseMs` leaves
+room for seconds of skew.
+
+### `QueueError: The lease on … was lost while it was delivered, and the item is gone: finished by the worker that took it, the message then sent twice, or cancelled`
+
+**Code:** `LEASE_LOST`, after
+[`The lease on … was lost while it was delivered`](#queueerror-the-lease-on--was-lost-while-it-was-delivered).
+**When:** a renewal was refused while the item was still in the store,
+held by another worker or by none, and when this worker tried to record
+its outcome the item was gone. No outcome event and no DSN come from this
+attempt.
+**Why:** another worker claimed the item once this one's lease had
+expired by its own clock — this worker stalled, or the instances' clocks
+disagree (an instance whose clock runs ahead sees leases expire early) —
+and has most likely finished and dropped it, the recipients both reached
+getting the message twice. A `cancel` after the renewal drops it too, and
+the store keeps no record of which happened, so the message names both.
+**Fix:** a longer `leaseMs`, find what stalled the process, and keep the
+machines on NTP.
 
 ### `SmtpError: sendMail(): …` (`INVALID_OPTION`), with recipients deferred as `4.3.5`
 
@@ -298,6 +362,31 @@ its lease expires — its recipients may then get the message twice.
 too many connections, give each instance's client a smaller `max` (see
 the guide's Pool size) or raise `max_connections`.
 
+### `RedisError: …` during a delivery: `Connection closed`, `OOM command not allowed …`, `READONLY …`
+
+**When:** the `error` event, with the item's `id`, while it is delivered,
+on `@bumail/queue/redis`. A call of yours — `enqueue`, `list`, `get`,
+`retryNow`, `cancel` — rejects with the same `RedisError` for the same
+reasons: an `enqueue` refused with `OOM …` kept nothing.
+**Why:** a lease renewal failed. `Connection closed`: Redis restarted,
+or the connection dropped, while the command was on its way; a command
+sent while the client is reconnecting waits instead. `Max reconnection
+attempts reached` or `Connection has failed`: Redis is out of reach, and
+`Bun.RedisClient` gave up reconnecting (20 tries by default). `OOM
+command not allowed when used memory > 'maxmemory'`: Redis is full and
+refuses writes. `READONLY You can't write against a read only replica`:
+the client reaches a replica, or a primary that was demoted by a
+failover. As on PostgreSQL, the next renewal tries again, only a lease
+taken by another instance stops them, a claim that fails rejects
+`deliverDue()` or is told on `error` under `start()`, and an outcome
+that cannot be recorded leaves the item to be claimed again once its
+lease expires — its recipients may then get the message twice.
+**Fix:** check Redis is up and that the URL names the primary (through
+your provider's endpoint or Sentinel's, which follows a failover). For
+`OOM`, give Redis more `maxmemory`, or drain the queue; keep
+`maxmemory-policy noeviction` (the guide's [Redis](guide.md#redis)), or
+Redis drops queue items to make room instead of refusing.
+
 ## The `bun:sqlite` store
 
 ### `QueueError: A SQLite queue store needs a directory`
@@ -315,7 +404,9 @@ should read the queue.
 ### `QueueError: The database is at schema version …, newer than this store's …`
 
 **Code:** `INVALID`. A newer version of the package wrote the database
-(`queue.sqlite`, or on PostgreSQL the prefix's tables): upgrade this one.
+(`queue.sqlite`, on PostgreSQL the prefix's tables, on Redis the
+prefix's keys, whose layout version is `<prefix>schema`): upgrade this
+one.
 
 ### `QueueError: busyTimeout must be an integer of at least 0, not …`
 
@@ -324,8 +415,8 @@ should read the queue.
 ### `QueueError: The queue store is closed`
 
 **Code:** `CLOSED`. The store was used after `close()`: call
-`queue.stop()` first, then `store.close()`. The PostgreSQL store says the
-same.
+`queue.stop()` first, then `store.close()`. The PostgreSQL and Redis
+stores say the same.
 
 ## The PostgreSQL store
 
@@ -387,6 +478,75 @@ their narrower role (the guide's [Migrations](guide.md#migrations)); or
 give the role `CREATE` on the schema. The next call tries again: nothing is left half made,
 since a migration is one transaction.
 
+## The Redis store
+
+### `QueueError: A Redis queue store needs client, a Bun.RedisClient, or url, a redis:// URL`
+
+**Code:** `INVALID`.
+**When:** `RedisQueueStore.open` with neither `client` nor `url`, a
+`url` that is not a URL of a scheme `Bun.RedisClient` takes (`redis://`,
+`rediss://`, `valkey://`, `valkeys://`, `redis+tls://`, `redis+unix://`,
+`redis+tls+unix://`), or a `client` without `send`, `getBuffer` and
+`close`. The message never repeats the URL, which may hold a password.
+**Fix:**
+
+```ts
+RedisQueueStore.open({ url: 'rediss://bumail:secret@cache.internal:6380/0' });
+// or a client of yours, configured as you need:
+RedisQueueStore.open({ client: new Bun.RedisClient(url, { connectionTimeout: 5000 }) });
+```
+
+### `QueueError: A Redis queue store takes client or url, not both`
+
+**Code:** `INVALID`. Give one: `client` for a client you configure and
+close, `url` for one the store opens and closes.
+
+### `QueueError: keyPrefix must be lowercase letters, digits, '_', ':', '.' and '-', starting with a letter, at most 40 characters, not …`
+
+**Code:** `INVALID`.
+**Why:** the prefix starts every key the store writes. Anything Redis or
+a `SCAN MATCH` reads specially is refused: `{` (a Cluster hash tag), `*`,
+`?`, `[` and `\` (glob characters), spaces and control characters.
+**Fix:** `keyPrefix: 'mail:queue:'`. Give each queue in one Redis
+database its own prefix.
+
+### `QueueError: The URL in url cannot be opened: …`
+
+**Code:** `INVALID`.
+**When:** `RedisQueueStore.open` with a URL `Bun.RedisClient` refuses
+before connecting, such as a database that is not a number (`Invalid
+database number in Redis URL: "…"`). The URL is never repeated, and the
+password is masked should the reason name it.
+**Fix:** correct the URL: the database is the path, `/0` to `/15` on a
+default Redis.
+
+### `QueueError: The Redis queue cannot be set up: …`
+
+**Code:** `INVALID`.
+**When:** the first call on a store, which reads the layout version of
+its keys (`<prefix>schema`), writing it on a new queue. The rest of the
+message is Redis's or Bun's: `Max reconnection attempts reached` (out of
+reach), `WRONGPASS invalid username-password pair or user is disabled.`,
+`ERR DB index is out of range`, `NOPERM …` (an ACL user without
+`EVALSHA`, `EVAL` or the keys).
+**Why:** the server is out of reach, the credentials or the database are
+wrong, or the user may not run scripts. With `Bun.RedisClient`'s
+defaults an unreachable server takes about half a minute of reconnecting
+before the call fails.
+**Fix:** check the URL and that Redis answers. An ACL user needs the
+commands the store sends and those its scripts call, on the keys under
+its prefix, and nothing else (the guide's [Redis](guide.md#redis) has
+the `ACL SETUSER` line). The next call tries again.
+
+### `QueueError: The key …schema does not hold a layout version: is the prefix another application's?`
+
+**Code:** `INVALID`.
+**When:** the first call on a store whose `<prefix>schema` key holds
+something other than a whole number of at least 1.
+**Why:** the store keeps its layout version there; anything else means
+another application, or a hand, wrote under the same prefix.
+**Fix:** give the queue a `keyPrefix` of its own. Nothing was written.
+
 ## Listing
 
 ### `QueueError: limit must be an integer from 1 to 1000, not …`
@@ -425,15 +585,71 @@ never gives it. Each message names what is wrong:
 - `QueueError: delayNotified must be true or false`
 - `QueueError: recipients must be an array of { address, status:
   delivered, deferred or failed }`
-- `QueueError: A reply is an object with a text`, `reply.status must be
-  a string`, `reply.host must be a string`
-- `QueueError: … holds a NUL or a lone surrogate, which a store cannot
-  keep` (`from`, `A recipient`, `owner`, `reply.text`, `reply.status`,
-  `reply.host`): every store refuses them, since PostgreSQL cannot keep
-  them; the queue's own replies never hold one
+- [`QueueError: A reply is an object with a text`](#queueerror-a-reply-is-an-object-with-a-text),
+  [`reply.status must be a string`](#queueerror-replystatus-must-be-a-string),
+  [`reply.host must be a string`](#queueerror-replyhost-must-be-a-string)
+- [`QueueError: … holds a NUL or a lone surrogate, which a store cannot
+  keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep)
 
 A list's `offset` and `limit` are checked as under [Listing](#listing).
 
+### `QueueError: A reply is an object with a text`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a recipient whose `reply` is
+not an object, or has no string `text`.
+**Why:** a reply is a `Diagnostic`, `{ code?, status?, text, host? }`:
+`text` is what a DSN and the events show, so every store needs it. The
+queue's own outcomes always have one.
+**Fix:** give the text, even for a reply with no code:
+
+```ts
+await store.complete(id, owner, {
+	...result,
+	recipients: [{ address, status: 'deferred', reply: { status: '4.4.1', text: 'No answer' } }],
+});
+```
+
+### `QueueError: reply.status must be a string`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a `reply.status` that is
+neither left out nor a string — often the reply code given as a number.
+**Why:** `status` is the enhanced status code, `x.y.z` (RFC 3463), kept
+as text; the reply code goes in `code`.
+**Fix:** `reply: { code: 451, status: '4.3.0', text: 'Try later' }`, or
+leave `status` out.
+
+### `QueueError: reply.host must be a string`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a `reply.host` that is neither
+left out nor a string, such as an address object from a socket.
+**Why:** `host` is the name or address the attempt was for, kept as text.
+**Fix:** give it as text — `host: 'mx1.example.com'` or
+`host: '192.0.2.1'` — or leave it out.
+
+### `QueueError: … holds a NUL or a lone surrogate, which a store cannot keep`
+
+**Code:** `INVALID`. The … is `from`, `A recipient`, `owner`,
+`reply.text`, `reply.status` or `reply.host`.
+**When:** `add`, `complete`, or any call that takes an `owner`, called
+directly with a text holding U+0000 or half of a surrogate pair — a string cut in the
+middle of an emoji, say. `createQueue` refuses such an `owner` the same
+way.
+**Why:** PostgreSQL cannot keep a NUL in text, and no UTF-8 encoding can
+carry a lone surrogate (`Bun.RedisClient` would write one as U+FFFD
+without a word), so every store refuses them alike — whichever
+store you give it, the same text is kept or refused. The queue's own
+replies never hold one: it cuts a reply's text only between whole
+characters.
+**Fix:** drop the NULs and cut text on whole characters before you give
+it to the store:
+
+```ts
+const clean = text.replaceAll('\0', '').toWellFormed();
+```
+
 ## Delivery
 
 ### A recipient stays `deferred` with `4.4.1` or `4.4.2`

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@bumail/queue",
-	"version": "0.2.0",
-	"description": "The outbound mail queue of a mail server: every recipient's state, retries with back-off, delivery status notifications (RFC 3464), leases for several workers, and a memory, a bun:sqlite and a PostgreSQL (Bun.sql) store, delivering through @bumail/smtp/client",
+	"version": "0.3.0",
+	"description": "The outbound mail queue of a mail server: every recipient's state, retries with back-off, delivery status notifications (RFC 3464), leases for several workers, and a memory, a bun:sqlite, a PostgreSQL (Bun.sql) and a Redis (Bun.redis) store, delivering through @bumail/smtp/client",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -34,6 +34,11 @@
 			"import": "./dist/postgres/index.js",
 			"default": "./dist/postgres/index.js"
 		},
+		"./redis": {
+			"types": "./dist/redis/index.d.ts",
+			"import": "./dist/redis/index.js",
+			"default": "./dist/redis/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"repository": {
@@ -55,7 +60,8 @@
 			"src/index.ts",
 			"src/memory/index.ts",
 			"src/sqlite/index.ts",
-			"src/postgres/index.ts"
+			"src/postgres/index.ts",
+			"src/redis/index.ts"
 		]
 	},
 	"devDependencies": {