@bumail/queue 0.3.0 → 0.4.0

package/docs/guide.md

@@ -98,6 +98,7 @@ recipient's outcome is recorded with the reply that decided it.
 | `sendMail` refuses the route's options (`INVALID_OPTION`) | `deferred`, as `4.3.5` | tried again later, and an `error` event: the configuration is yours to fix |
 | a recipient a store holds that `sendMail` would refuse | `failed`, as `5.1.3` | final, alone; a DSN |
 | a sender a store holds that `sendMail` would refuse | `failed`, as `5.1.7` | final, every recipient, with no session; a DSN to that sender, which itself fails as `5.1.3` |
+| a message the store lost ([below](#a-message-the-store-lost)) | `failed`, as `5.3.0` | final, every pending recipient, with no session; a DSN without the original, and a `MESSAGE_UNREADABLE` error |
 
 An error is read by its `name` (`SmtpError`) and `code`, not by its
 class: an app with a second copy of `@bumail/smtp` installed, or a
@@ -160,6 +161,40 @@ seconds (RFC 5321 §4.5.3.2's by default) and the whole session's (1800
 seconds, DNS included). `createQueue` checks each one: above 0, and at
 most 2147483 seconds, the longest a timer waits.
 
+### A message the store lost
+
+An item whose message the store no longer gives — a Redis key evicted
+or deleted, a row removed by hand — cannot be sent. Rather than leave it
+leased, claimed again at every lease and holding its `limits.maxItems`
+place, the attempt fails every recipient still pending, at once:
+
+- the failures are recorded, and the attempt counts; then
+- the `error` event gets a `QueueError` of code `MESSAGE_UNREADABLE`,
+  `The message of … is unreadable: the store holds the item but not its
+  message, so every pending recipient failed`, with the item's `id`;
+- each recipient's `failed` event follows, its `reply` `{ status:
+  '5.3.0', text: 'Message unreadable: the queue store holds the item but
+  not its message' }`, with no `code`, since no server answered;
+- the failure DSN goes to the sender as usual — never about a message
+  from `<>` — with no third part, since there is nothing to return;
+- the item leaves the queue. Recipients already delivered keep their
+  state, and are not told again.
+
+In that order: the record, the `error`, the `failed` events, the `dsn`
+event. Nothing is told before the record: when the lease was lost
+meanwhile, the attempt reports `LEASE_LOST` only, and the worker that
+holds the item next tells the failures; when `complete` throws, the
+`error` event gets that error alone; when the item was cancelled
+meanwhile, its lease still held, nothing is told at all — no session
+ran, and nothing was recorded. An item that is gone along with its
+message (cancelled, or finished by another worker) is left alone, as
+before.
+
+A store keeps an item from being claimed before its message can be read
+— the message written first, or both in one step — so a message missing
+at a claim is always damage, never an add still under way. Every store
+here adds both in one step.
+
 ## Retries
 
 ```ts
@@ -196,7 +231,9 @@ final, and the item's `attempts` counts them.
 The queue writes DSNs (RFC 3464) as a `multipart/report`
 (`report-type=delivery-status`, RFC 6522) of three parts: text for a
 person, the `message/delivery-status` fields a program reads, and the
-original's header fields.
+original's header fields. The third is left out, as RFC 6522 §3
+allows, for [a message the store lost](#a-message-the-store-lost): the
+text then says it could not be read.
 
 ```
 Reporting-MTA: dns; mail.example.net
@@ -309,11 +346,19 @@ off(); // stops listening
 | `deferred` | the same, and `nextAttemptAt` |
 | `failed` | the same as `delivered` |
 | `dsn` | `{ kind: 'delayed' \| 'failed', id, of, to, recipients }`: `id` is the DSN's own item, `of` the item it reports on |
-| `error` | `{ error, id? }`: a store that failed (a lease renewal included), a DSN that could not be enqueued, a lease lost, a route `sendMail` refused (`INVALID_OPTION`) |
-
-Events come once the outcome is recorded. A listener that throws is
-ignored. `reply.code` is absent when no server answered: a connection
-error, a timeout, the DNS.
+| `error` | `{ error, id? }`: a store that failed (a lease renewal included), a DSN that could not be enqueued, a lease lost (`LEASE_LOST`), a message the store lost (`MESSAGE_UNREADABLE`), a route `sendMail` refused (`INVALID_OPTION`) |
+
+Events about an outcome come once it is recorded, in this order: a
+`MESSAGE_UNREADABLE` error when the store lost the message, each
+recipient's `delivered`, `deferred` or `failed`, then the `dsn` events.
+An item cancelled while it was delivered, its lease still held, has
+what its sessions did told, with no DSN, though nothing is recorded;
+for a message the store lost, no session ran, and nothing is told.
+Other errors are told as they happen: a route `sendMail` refused during
+its session, a lease lost or a store that failed in place of the
+outcome, and a DSN that could not be enqueued, during the `dsn` step.
+A listener that throws is ignored. `reply.code` is absent
+when no server answered: a connection error, a timeout, the DNS.
 
 ## Admin
 
@@ -413,8 +458,23 @@ a store on the same database, and they share one queue.
 - It is typed by its shape, `PostgresClient` (`unsafe`, `begin` and
   `close`), so the declarations need nothing of `@types/bun`; a `Bun.SQL`
   client fits it.
+- **Writes run at `READ COMMITTED`**, whatever the client's sessions
+  default to: each transaction that writes — a claim, a renewal, an
+  outcome, an add, a reschedule, a cancel, a migration — starts with
+  `SET TRANSACTION ISOLATION LEVEL READ COMMITTED, READ WRITE`. A client
+  shared with code that sets `default_transaction_isolation` to
+  `repeatable read` or `serializable` (`new Bun.SQL({ url, connection: {
+  default_transaction_isolation: 'serializable' } })`) still serves the
+  queue: the claim's `FOR UPDATE SKIP LOCKED` and the `maxItems` lock
+  need that level, and under a stricter one concurrent writes would fail
+  with SQLSTATE 40001. Reads are one statement each, at the client's
+  level.
 - **Nothing connects at `open`**: a wrong option is refused there, and a
-  database out of reach on the first call.
+  database out of reach on the first call. A URL is never repeated in an
+  error, and the password — the URL's, or a given `Bun.SQL`'s — is
+  masked should the database's reason name it: always where it stands
+  in a URL (`:…@`), and alone, elsewhere, when it is 4 characters or
+  more (masking a shorter one everywhere would garble the reason).
 
 ### The schema
 
@@ -431,7 +491,10 @@ They are the `bun:sqlite` store's tables, column for column. The prefix
 is lowercase letters, digits and underscores, starting with a letter or
 an underscore, 40 characters at most: it is written into the statements,
 never bound. Give each queue its own prefix to keep several in one
-database. A `bytea` holds 1 GB at most, far above `limits.maxMessageSize`
+database, and never share a prefix with another package's or
+application's tables: the store cannot tell another `<prefix>schema` or
+`<prefix>messages` from its own, and would read that version as the
+queue's. A `bytea` holds 1 GB at most, far above `limits.maxMessageSize`
 (25 MiB by default).
 
 ### Migrations
@@ -490,8 +553,9 @@ RETURNING …
 
 ### Pool size
 
-Each call holds a connection for one statement, `complete` and an add
-with `limits.maxItems` for one short transaction. A worker has at most
+A read holds a connection for one statement, and each write for one
+short transaction: the isolation level, then its statement or two, then
+the commit. A worker has at most
 `concurrency` items (20) in flight, each mostly waiting on a remote SMTP
 server, not the database: `Bun.SQL`'s default pool of 10 connections is
 enough for one, and a call waits for a free connection rather than fail.
@@ -543,6 +607,9 @@ exactly once, against `redis:7`.
   and a claim or an outcome is told on `error` (see Troubleshooting).
 - One client is one connection, pipelined: every call of one store goes
   through it, so there is no pool to size.
+- A URL is never repeated in an error, and its password is masked should
+  Redis's or Bun's reason name it, as on PostgreSQL. A given client's
+  password is not known to the store, and not masked.
 
 ### The keys
 
@@ -626,7 +693,9 @@ instance between its steps.
   `noeviction` it refuses the write (`OOM command not allowed`), and
   `enqueue` rejects with that `RedisError`. An item whose hash is gone
   all the same (evicted, or deleted by hand) is dropped by the next
-  claim that meets it, its message with it, and never leased. Bound the queue with `limits.maxItems` and
+  claim that meets it, its message with it, and never leased. An item
+  whose message alone is gone fails its pending recipients at once
+  ([a message the store lost](#a-message-the-store-lost)). Bound the queue with `limits.maxItems` and
   `limits.maxMessageSize`, and size `maxmemory` for both.
 - **An ACL user** needs the commands the store sends and the ones its
   scripts call, on its prefix's keys (`~<keyPrefix>*`; here the
@@ -716,8 +785,15 @@ points at it, and `mxPort` its port.
 A store implements `QueueStore`, throws `QueueError` with the contract's
 codes, and keeps its promises:
 
+- `add` never makes an item claimable before its message is readable:
+  write the message first, or both in one step.
 - `claim` is atomic: two claimers, in any process, never get the same
   item; an item whose lease expired is claimable again.
+- `readMessage` gives `undefined` once the item is gone, and also when
+  the store still holds the item but has lost its message: the queue
+  then fails the item's pending recipients as `5.3.0`
+  ([a message the store lost](#a-message-the-store-lost)), so never
+  throw for a missing message.
 - `complete` applies the outcome, the schedule and the count, and lets go
   of the lease, in one step and only for the lease's owner; a final
   status is never changed; an item whose every recipient is final is

package/docs/roadmap.md

@@ -7,7 +7,7 @@ only number on it.
 ## Now
 
 Nothing in progress: the MongoDB store, first under Next, is the next
-one taken. The Redis store is merged (see Shipped).
+one taken. The Redis store shipped in 0.3.0 (see Shipped).
 
 ## Next
 
@@ -65,6 +65,25 @@ Then:
 
 ### Unreleased — merged, not yet published
 
+- **The PostgreSQL store's writes run at `READ COMMITTED`** — whatever
+  the client's sessions default to, so a client shared with code that
+  defaults to `repeatable read` or `serializable` serves the queue:
+  concurrent claims, outcomes, adds with `maxItems` and migrations no
+  longer fail with SQLSTATE 40001, and `maxItems` holds under them.
+- **A message the store lost no longer loops** — an item whose message
+  is gone (a Redis key evicted or deleted, a row removed by hand) fails
+  its pending recipients at once as `5.3.0`, `Message unreadable`, says
+  so on the `error` event (`MESSAGE_UNREADABLE`), sends its failure DSN
+  without the original and leaves the queue, rather than be claimed
+  again at every lease, forever, holding its `maxItems` place.
+- **A set-up error never shows the password** — `The PostgreSQL queue
+  cannot be set up` and `The Redis queue cannot be set up` mask it
+  should the database's reason repeat it; and a password under 4
+  characters is masked only where a URL holds it, so the rest of the
+  reason stays readable.
+
+### 0.3.0
+
 - **A Redis store**, `@bumail/queue/redis`, on Bun's own `Bun.redis`,
   for instances of a server on several machines sharing one queue:
   `RedisQueueStore.open({ client })` takes a `Bun.RedisClient`, or

package/docs/troubleshooting.md

@@ -36,10 +36,12 @@ parts shown as … vary.
 - [`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)
+- [`QueueError: The message of … is unreadable: the store holds the item but not its message, so every pending recipient failed`](#queueerror-the-message-of--is-unreadable-the-store-holds-the-item-but-not-its-message-so-every-pending-recipient-failed)
 - [`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-)
+- [`PostgresError: could not serialize access due to concurrent update` (SQLSTATE `40001`)](#postgreserror-could-not-serialize-access-due-to-concurrent-update-sqlstate-40001)
 
 **The `bun:sqlite` store** (`@bumail/queue/sqlite`)
 
@@ -87,6 +89,7 @@ parts shown as … vary.
 - [Every delivery fails at once with `5.7.1`, or with a reply naming your IP or EHLO name](#every-delivery-fails-at-once-with-571-or-with-a-reply-naming-your-ip-or-ehlo-name)
 - [A recipient fails with `5.1.3`, `The address is not one SMTP can carry`](#a-recipient-fails-with-513-the-address-is-not-one-smtp-can-carry)
 - [Every recipient fails with `5.1.7`, `The sender's address is not one SMTP can carry`](#every-recipient-fails-with-517-the-senders-address-is-not-one-smtp-can-carry)
+- [Every pending recipient fails with `5.3.0`, `Message unreadable: the queue store holds the item but not its message`](#every-pending-recipient-fails-with-530-message-unreadable-the-queue-store-holds-the-item-but-not-its-message)
 - [`retryNow` returns `false` for an item that is in the queue](#retrynow-returns-false-for-an-item-that-is-in-the-queue)
 
 ## Enqueuing
@@ -323,6 +326,29 @@ 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.
 
+### `QueueError: The message of … is unreadable: the store holds the item but not its message, so every pending recipient failed`
+
+**Code:** `MESSAGE_UNREADABLE`, with the item's `id`.
+**When:** a worker claimed an item, the store gave no message for it
+while it still held the item, and the failures were then recorded: it
+comes after the record, before the `failed` events. With the lease lost
+before the record, only `LEASE_LOST` is told, and the next worker tells
+this; with the item cancelled meanwhile, nothing is.
+**Why:** the message is gone and the item is not: on Redis, its
+`<prefix>message:<id>` key evicted under a `maxmemory-policy` other than
+`noeviction`, or deleted; on any store, a message row or key removed by
+hand, or a store of your own that loses it. Nothing can be sent, so
+every recipient still pending fails as `5.3.0` (see
+[below](#every-pending-recipient-fails-with-530-message-unreadable-the-queue-store-holds-the-item-but-not-its-message)),
+the failure DSN goes to the sender without the original, and the item
+leaves the queue. Before this, such an item stayed leased and was
+claimed again at every lease, forever, with no event.
+**Fix:** find what removed the message. On Redis, set
+`maxmemory-policy noeviction` and size `maxmemory` for the queue (the
+guide's [Redis](guide.md#redis)); never delete a queue's keys or rows by
+hand, `cancel(id)` drops an item with its message. The sender has the
+DSN and may send again.
+
 ### `SmtpError: sendMail(): …` (`INVALID_OPTION`), with recipients deferred as `4.3.5`
 
 **When:** `sendMail` refused the options of a session — the route, the
@@ -387,6 +413,26 @@ your provider's endpoint or Sentinel's, which follows a failover). For
 `maxmemory-policy noeviction` (the guide's [Redis](guide.md#redis)), or
 Redis drops queue items to make room instead of refusing.
 
+### `PostgresError: could not serialize access due to concurrent update` (SQLSTATE `40001`)
+
+**When:** on `@bumail/queue/postgres` 0.3.0 or earlier — a claim, an
+outcome, an `enqueue` with `limits.maxItems` or a migration rejecting, or
+told on `error`, with `could not serialize access due to concurrent
+update` or `… due to read/write dependencies among transactions`, while
+several workers run — or `limits.maxItems` letting more items in than
+its limit.
+**Why:** the client's sessions default to `repeatable read` or
+`serializable` (`connection: { default_transaction_isolation }`, or the
+role's or database's own default). The claim's `FOR UPDATE SKIP LOCKED`
+and the `maxItems` advisory lock need `READ COMMITTED`: under a stricter
+level, a row another worker changed since the transaction's snapshot
+fails, and the count taken after the lock reads a snapshot from before
+it.
+**Fix:** upgrade: every transaction the store writes in now starts with
+`SET TRANSACTION ISOLATION LEVEL READ COMMITTED`, whatever the client's
+default. The error from a transaction of your own on the same client is
+yours to retry.
+
 ## The `bun:sqlite` store
 
 ### `QueueError: A SQLite queue store needs a directory`
@@ -447,7 +493,8 @@ PostgresQueueStore.open({ sql: new Bun.SQL({ url, max: 10 }) });
 **Why:** the prefix is written into every statement, never bound as a
 value, so anything that is not a plain name is refused — and 40
 characters keep the longest name built on it within PostgreSQL's 63.
-**Fix:** `tablePrefix: 'mail_queue_'`. To put the tables in another
+**Fix:** `tablePrefix: 'mail_queue_'`, a prefix of the queue's own: never
+one another package's or application's tables use. To put the tables in another
 schema, set the connection's `search_path` rather than a dotted prefix.
 
 ### `QueueError: The URL in sql cannot be opened: …`
@@ -457,7 +504,10 @@ schema, set the connection's `search_path` rather than a dotted prefix.
 connecting, such as a `sslmode` it does not know. The rest is Bun's
 reason (`The argument 'sslmode' must be one of: disable, allow, prefer,
 require, verify-ca, verify-full. Received '…'`); the URL is never
-repeated, and the password is masked should the reason name it.
+repeated, and the password is masked should the reason name it: always
+where a URL holds it (`:…@`), and alone, elsewhere, when it is 4
+characters or more — masking `x` everywhere would turn "execute" into
+"e…ecute".
 **Fix:** correct the parameter: `?sslmode=require`, or `verify-full` to
 check the server's certificate.
 
@@ -467,7 +517,10 @@ check the server's certificate.
 **When:** the first call on a store, or `migrate()`, when the tables
 cannot be made or brought up to date. The rest of the message is the
 database's: `Failed to connect`, `password authentication failed for
-user "…"`, `permission denied for schema public`.
+user "…"`, `permission denied for schema public`. The password — the
+URL's, or a given `Bun.SQL`'s — is masked should the reason name it, as
+for `The URL in sql cannot be opened`: a `…` where you expect a role or
+a database name is one that equals the password.
 **Why:** the database is out of reach, the credentials are wrong, or the
 tables are missing or behind and the role may not create them: a role
 without `CREATE` can use tables that are current, never make them.
@@ -516,7 +569,8 @@ database its own prefix.
 **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.
+password is masked should the reason name it, as on PostgreSQL: always
+in a URL, and alone from 4 characters.
 **Fix:** correct the URL: the database is the path, `/0` to `/15` on a
 default Redis.
 
@@ -528,7 +582,8 @@ 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).
+`EVALSHA`, `EVAL` or the keys). The URL's password is masked should the
+reason repeat it; a given client's is not known to the store.
 **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
@@ -697,6 +752,22 @@ other.
 `@bumail/smtp/client`'s `isMailbox` (or let it be `''`) before a store of
 your own keeps it.
 
+### Every pending recipient fails with `5.3.0`, `Message unreadable: the queue store holds the item but not its message`
+
+**When:** the store held the item but gave no message for it, and the
+failures were recorded: the `error` event says
+[`The message of … is unreadable`](#queueerror-the-message-of--is-unreadable-the-store-holds-the-item-but-not-its-message-so-every-pending-recipient-failed)
+for the same item, just before these `failed` events. An item cancelled
+before the record tells no `5.3.0` failure; with the lease lost, this
+attempt tells none and the next worker tells them.
+**Why:** no session can send a message that cannot be read, and an
+attempt left without an outcome would be claimed again at every lease,
+forever, keeping its `maxItems` place. Recipients already delivered keep
+their state; the others fail in one attempt, with one failure DSN —
+none for a message from `<>` — that returns nothing of the original.
+**Fix:** as for that error: find what removed the message, and on Redis
+keep `maxmemory-policy noeviction`.
+
 ### `retryNow` returns `false` for an item that is in the queue
 
 **Why:** a worker is delivering it: its lease is held. That attempt's

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@bumail/queue",
-	"version": "0.3.0",
+	"version": "0.4.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",

package/dist/chunks/index-y3n1w2az.js

@@ -1,18 +0,0 @@
-// src/masked.ts
-function masked(text, raw) {
-  let decoded = raw;
-  try {
-    decoded = decodeURIComponent(raw);
-  } catch {}
-  let out = text;
-  for (const password of [raw, decoded]) {
-    if (password !== "")
-      out = out.replaceAll(password, "…");
-  }
-  return out;
-}
-
-export { masked };
-
-//# debugId=64BFD310901EABF064756E2164756E21
-//# sourceMappingURL=index-y3n1w2az.js.map

package/dist/chunks/index-y3n1w2az.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/masked.ts"],
-  "sourcesContent": [
-    "/**\n * `text` with a URL's password masked, as written in the URL and decoded,\n * if it decodes: what a store opening a URL repeats of the client's\n * reason, which may name it.\n */\nexport function masked(text: string, raw: string): string {\n\tlet decoded = raw;\n\ttry {\n\t\tdecoded = decodeURIComponent(raw);\n\t} catch {\n\t\t// Not percent-encoding a client reads either: the raw form is what it would repeat.\n\t}\n\tlet out = text;\n\tfor (const password of [raw, decoded]) {\n\t\tif (password !== '') out = out.replaceAll(password, '…');\n\t}\n\treturn out;\n}\n"
-  ],
-  "mappings": ";AAKO,SAAS,MAAM,CAAC,MAAc,KAAqB;AAAA,EACzD,IAAI,UAAU;AAAA,EACd,IAAI;AAAA,IACH,UAAU,mBAAmB,GAAG;AAAA,IAC/B,MAAM;AAAA,EAGR,IAAI,MAAM;AAAA,EACV,WAAW,YAAY,CAAC,KAAK,OAAO,GAAG;AAAA,IACtC,IAAI,aAAa;AAAA,MAAI,MAAM,IAAI,WAAW,UAAU,GAAG;AAAA,EACxD;AAAA,EACA,OAAO;AAAA;",
-  "debugId": "64BFD310901EABF064756E2164756E21",
-  "names": []
-}