@bumail/queue 0.2.0 → 0.4.0

package/dist/redis/scripts.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Lua scripts a Redis store runs: each operation that writes is one
+ * script, so Redis runs it whole, with no other command between its
+ * steps. The fixed keys come as `KEYS`; an item's own keys are its
+ * prefix (`ARGV[1]`), `item:` or `message:`, and its id.
+ *
+ * An item is a hash, `<prefix>item:<id>`; its message a string,
+ * `<prefix>message:<id>`, written from the bytes given, as they are. Its
+ * member in the sorted sets is its sequence number, sixteen digits, `:`,
+ * and its id: Redis orders members of one score by their bytes, so items
+ * equally due come oldest first. Times travel as the strings JavaScript
+ * writes for them and are only compared here (`tonumber`), never written
+ * back from Lua, so none loses a digit.
+ */
+/** A script, and the SHA-1 `EVALSHA` names it by. */
+export interface Script {
+    readonly source: string;
+    readonly sha: string;
+}
+/**
+ * KEYS schema; ARGV prefix, version. Writes the version on a new queue;
+ * returns the one found.
+ */
+export declare const SCHEMA: Script;
+/**
+ * KEYS items, ready, seq; ARGV prefix, id, from, recipients, size,
+ * created, message, max (or ''). `{'full', n}` when `max` items are
+ * there already, else `{'ok'}`.
+ */
+export declare const ADD: Script;
+/**
+ * KEYS ready, leases, items; ARGV prefix, owner, now, expiry. The
+ * earliest due, then the oldest, of the items no lease holds and of those
+ * whose lease expired, leased to the owner; its fields, or false. The
+ * expired leases are read whole: there are as many as the leases a
+ * crashed or stalled worker left behind, and the leased items an admin
+ * moved later, until they are due.
+ */
+export declare const CLAIM: Script;
+/** KEYS leases; ARGV prefix, id, owner, expiry. 1 while the owner holds the lease, else 0. */
+export declare const RENEW: Script;
+/**
+ * KEYS items, ready, leases; ARGV prefix, id, owner, rev, then 'drop',
+ * or 'record' and recipients, next, attempts, delay. 0 when the owner
+ * does not hold the lease; -1 when another outcome was recorded since
+ * the item was read at `rev`, to read it again; 1 once recorded, the
+ * lease let go of, or the item and its message dropped.
+ */
+export declare const COMPLETE: Script;
+/**
+ * KEYS items, ready, leases; ARGV prefix, id, at, owner (or ''). With an
+ * owner, only while it holds the lease, which it lets go of; without,
+ * the lease stays. 1 when moved, else 0.
+ */
+export declare const RESCHEDULE: Script;
+/** KEYS items, ready, leases; ARGV prefix, id. The item's fields as it stood, or false; dropped with its message. */
+export declare const CANCEL: Script;
+/** KEYS items; ARGV prefix, first, last. A page of items, each its fields, in one read. */
+export declare const LIST: Script;
+//# sourceMappingURL=scripts.d.ts.map

package/dist/redis/scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../../src/redis/scripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAuBH,qDAAqD;AACrD,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAQD;;;GAGG;AACH,eAAO,MAAM,MAAM,QAKjB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,GAAG,QAcd,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,QAyBhB,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,KAAK,QAMhB,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,QAmBnB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAerB,CAAC;AAEH,qHAAqH;AACrH,eAAO,MAAM,MAAM,QAUjB,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,IAAI,QAMf,CAAC"}

package/dist/redis/store.d.ts

@@ -0,0 +1,30 @@
+import type { QueueStore } from '../contract/queue-store';
+import type { AddOptions, AttemptResult, ClaimRequest, NewQueueItem, QueueItem, QueueListOptions } from '../contract/types';
+import type { RedisQueueStoreOptions } from './options';
+/**
+ * A `QueueStore` on Redis through Bun's own `Bun.RedisClient`: several
+ * instances, on one machine or many, share one queue. Every operation
+ * that writes is one Lua script, which Redis runs whole, so two
+ * instances never take the same item. The due items are in sorted sets,
+ * each item a hash, its message a string written byte for byte. One
+ * Redis, or a primary with replicas — not Redis Cluster.
+ */
+export declare class RedisQueueStore implements QueueStore {
+    #private;
+    private constructor();
+    /** Checks the options; connects to nothing until the first call. What is wrong is `INVALID`. */
+    static open(options: RedisQueueStoreOptions): RedisQueueStore;
+    /** Closes the client the store opened for a URL, never one it was given; closing twice is fine. */
+    close(): Promise<void>;
+    add(item: NewQueueItem, options?: AddOptions): Promise<QueueItem>;
+    get(id: string): Promise<QueueItem | undefined>;
+    list(options?: QueueListOptions): Promise<QueueItem[]>;
+    count(): Promise<number>;
+    readMessage(id: string): Promise<Uint8Array | undefined>;
+    claim(request: ClaimRequest): Promise<QueueItem | undefined>;
+    renew(id: string, owner: string, expiresAt: number): Promise<boolean>;
+    complete(id: string, owner: string, result: AttemptResult): Promise<QueueItem | undefined>;
+    reschedule(id: string, at: number, owner?: string): Promise<boolean>;
+    cancel(id: string): Promise<QueueItem | undefined>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/redis/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/redis/store.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAa1E;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,UAAU;;IAQjD,OAAO;IAOP,gGAAgG;IAChG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe;IAI7D,mGAAmG;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmCtB,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IA2BrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAS/C,IAAI,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAatD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAKxB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAOxD,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAc5D,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAarE,QAAQ,CACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,aAAa,GACnB,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IA2B3B,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAepE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;CAQxD"}

package/docs/README.md

@@ -5,6 +5,6 @@ long one.
 
 | Page | Read it when |
 | --- | --- |
-| [Guide](guide.md) | enqueuing, choosing a route (MX, a smarthost, per domain), tuning the retry schedule and the DSNs, running several workers or instances on PostgreSQL, listening to events, testing with a fake clock and sender, or writing a store of your own |
+| [Guide](guide.md) | enqueuing, choosing a route (MX, a smarthost, per domain), tuning the retry schedule and the DSNs, running several workers or instances on PostgreSQL or Redis, listening to events, testing with a fake clock and sender, or writing a store of your own |
 | [Troubleshooting](troubleshooting.md) | the queue or a store threw a `QueueError`, the `error` event fired, or mail stays deferred |
 | [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |

package/docs/guide.md

@@ -14,6 +14,7 @@ workers share it.
 - [Admin](#admin)
 - [The stores](#the-stores)
 - [PostgreSQL](#postgresql)
+- [Redis](#redis)
 - [Testing](#testing)
 - [Writing a store](#writing-a-store)
 - [Options](#options)
@@ -97,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
@@ -159,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
@@ -195,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
@@ -236,7 +274,8 @@ is written as `utf-8; j\x{F6}rg@…`, RFC 6533), and every field is folded.
 ## Several workers, leases and stopping
 
 Any number of queues may share one store, in one process or several —
-or, with [PostgreSQL](#postgresql), on several machines:
+or, with [PostgreSQL](#postgresql) or [Redis](#redis), on several
+machines:
 
 ```ts
 const store = SqliteQueueStore.open({ directory: '/var/lib/bumail/queue' });
@@ -254,9 +293,17 @@ queue.start();
   stops them.
 - **A crashed worker** loses its items when their leases expire: another
   worker claims them then. A worker whose lease was taken meanwhile
-  records nothing, and says so on the `error` event (`LEASE_LOST`). An
-  item cancelled while it was delivered still has its outcomes told by
-  the events, with no DSN and no error.
+  records nothing, and says so on the `error` event (`LEASE_LOST`) — also
+  when that worker has since finished the item and dropped it, the
+  message then sent twice. An item cancelled while it was delivered, its
+  lease still holding, has its outcomes told by the events, with no DSN
+  and no error. Once the lease's expiry has passed, a worker cannot tell
+  a cancel from an item another worker finished: it reports `LEASE_LOST`,
+  lost or cancelled, and tells no outcome. One gap remains when the
+  instances' clocks are out of step: an instance whose clock runs ahead
+  can take the item while this worker's clock says the lease holds, and
+  if it finishes the item between two renewals, the attempt reads as a
+  cancel. Keep the machines on NTP.
 - **`stop()`** claims nothing more, lets every session under way end and
   records its outcome, and gives back what was claimed but not started —
   due at once, no attempt counted — so another worker can take it.
@@ -299,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
 
@@ -354,7 +409,7 @@ store.close(); // closing twice is fine
   each item is claimed once; a writer waits up to `busyTimeout`
   milliseconds for another.
   Not on a network file system: SQLite's locks do not hold there. For
-  several machines, use [PostgreSQL](#postgresql).
+  several machines, use [PostgreSQL](#postgresql) or [Redis](#redis).
 - **Messages in a table of their own**, `messages`, dropped with their
   item in the same transaction. A queue holds a message for days at most
   and never shares one between items, so content addressing (as
@@ -368,6 +423,10 @@ store.close(); // closing twice is fine
 On PostgreSQL, for instances on several machines: see
 [PostgreSQL](#postgresql).
 
+### `RedisQueueStore`
+
+On Redis, for instances on several machines: see [Redis](#redis).
+
 ## PostgreSQL
 
 ```ts
@@ -399,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
 
@@ -417,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
@@ -476,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.
@@ -485,6 +563,172 @@ Raise `max` only when a busy worker waits on the pool, and keep every
 instance's pool, and your application's, within the server's
 `max_connections` (100 by default): four instances of `max: 10` take 40.
 
+## Redis
+
+```ts
+import { createQueue } from '@bumail/queue';
+import { RedisQueueStore } from '@bumail/queue/redis';
+
+const client = new Bun.RedisClient(Bun.env['REDIS_URL']);
+const store = RedisQueueStore.open({ client, keyPrefix: 'mail:queue:' });
+const queue = createQueue({ store, hostname, resolver, owner: `${host}-${process.pid}` });
+queue.start();
+
+process.on('SIGTERM', async () => {
+	await queue.stop();
+	client.close(); // yours: the store never closes a client it was given
+});
+```
+
+`@bumail/queue/redis` runs on Bun's own `Bun.RedisClient` (`Bun.redis`
+is its default instance): there is no driver to install and no peer to
+add. Every instance of your server opens a store on the same Redis, and
+they share one queue. It is held to the same contract specs as the other
+stores, and to the same specs of two instances delivering every item
+exactly once, against `redis:7`.
+
+### The client
+
+- **`client`** is a `Bun.RedisClient` of yours — you set its options and
+  close it — or **`url`** a `redis://` (`rediss://` for TLS, or the other
+  schemes `Bun.RedisClient` takes), for which the store opens a client
+  with Bun's defaults and closes it in `close()`. One or the other, never
+  both.
+- It is typed by its shape, `RedisQueueClient` (`send`, `getBuffer` and
+  `close`), so the declarations need nothing of `@types/bun`; a
+  `Bun.RedisClient` fits it.
+- **Nothing connects at `open`**: a wrong option is refused there, and a
+  server out of reach on the first call. With Bun's defaults a client
+  reconnects on its own, up to 20 times, and holds the commands sent
+  while it is disconnected until Redis is back (a `PING` sent during a
+  5-second stop answered once Redis started again). A command already
+  sent when the connection drops, or sent before the client noticed,
+  fails instead (`Connection closed`): a renewal tries again on its own,
+  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
+
+Every key starts with `keyPrefix` (`bumail:queue:` by default):
+
+| key | type | what it holds |
+| --- | --- | --- |
+| `<prefix>item:<id>` | hash | an item: `id`, `from`, `recipients` (JSON, each recipient's state), `size`, `created`, `next`, `attempts`, `delay`, while leased `owner` and `expires`, its `member` in the sorted sets and `rev`, how many outcomes were recorded |
+| `<prefix>message:<id>` | string | the message as enqueued, whole, byte for byte |
+| `<prefix>items` | sorted set | every item, scored by its next attempt: `list` and `count` |
+| `<prefix>ready` | sorted set | the items no lease holds, scored by their next attempt |
+| `<prefix>leases` | sorted set | the leased items, scored by when their leases expire |
+| `<prefix>seq` | string | the counter that orders items equally due |
+| `<prefix>schema` | string | the layout version |
+
+A member of the sorted sets is the item's sequence number, sixteen
+digits, then `:` and its id, so items equally due come oldest first.
+Times are kept as the strings JavaScript writes for them, and read back
+exactly. The prefix is lowercase letters, digits, `_`, `:`, `.` and
+`-`, starting with a letter, 40 characters at most: no `{`, so no
+Cluster hash tag, and no glob character, so `SCAN 0 MATCH <prefix>*`
+finds the queue's keys and nothing else. A `<prefix>schema` that holds
+anything but a layout version is refused at the first call: the prefix
+is another application's. Give each queue its own
+prefix to keep several in one Redis database. An id the store did not
+make (`crypto.randomUUID()`'s form) is one no item has: no id a caller
+gives reaches another key.
+
+### Several instances and leases
+
+Every operation that writes is one Lua script, run by `EVALSHA` (by
+`EVAL` when Redis no longer has it, after a restart, a failover or a
+`SCRIPT FLUSH`): Redis runs a script whole, with no command of another
+instance between its steps.
+
+- **A claim** takes the first item of `ready` due by `now`, and every
+  lease of `leases` expired by `now`, keeps the earliest due of them,
+  then the oldest, and moves it from `ready` to `leases` with its new
+  expiry, in one script. Two instances never take the same item. An
+  expired lease is found at once, not by a sweep; there are only as many
+  as a crashed or stalled instance left.
+- **`complete`** reads the item, applies the outcome in JavaScript, and
+  records it with a script that checks the owner still holds the lease
+  and that no other outcome was recorded since (`rev`); otherwise it
+  reads again, at most 8 times, then records nothing (`LEASE_LOST`), as
+  it does when the lease was lost.
+- **`renew`**, **`reschedule`** and **`cancel`** are a script each, and
+  an `add` with `limits.maxItems` counts and adds in one, so two
+  instances never both take the last place.
+- **The clocks** of the instances must agree, as on PostgreSQL: the store
+  keeps no clock, and Redis's is never read.
+
+### Deploying Redis
+
+- **One Redis, or a primary with replicas — not Redis Cluster.** A script
+  reaches each item's keys, which are not all named up front, so the
+  queue's keys must live on one node. Point the store at the primary: a
+  replica refuses writes (`READONLY`). After a failover, the URL must
+  reach the new primary — a provider's endpoint that follows it, say.
+- **Durability is Redis's, and weaker than PostgreSQL's.** Redis
+  acknowledges a write once it is in memory:
+  - with `appendonly yes` and `appendfsync always`, a write is on disk
+    before it is acknowledged, as on `bun:sqlite` or PostgreSQL;
+  - with `appendfsync everysec` (Redis's default once AOF is on), a
+    crash of the server loses up to about a second of acknowledged
+    writes;
+  - with snapshots only (`save`, AOF off), it loses everything since the
+    last snapshot, minutes of it;
+  - **replication is asynchronous**: a primary that fails before its
+    replica has a write loses that write when the replica is promoted,
+    whatever the fsync setting.
+
+  A lost write is an enqueued message gone (the client was told it was
+  queued), an outcome forgotten (a recipient delivered and sent the
+  message again), or a lease given twice. Use `appendfsync always`
+  where a lost message matters, and PostgreSQL where it must survive a
+  failover.
+- **`maxmemory-policy noeviction`.** Every message lives in memory, whole,
+  until its item is done. Under any other policy a full Redis evicts
+  queue keys — an item, or its message — to make room; with
+  `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. 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
+  example's `mail:queue:`), and nothing else:
+
+  ```
+  ACL SETUSER bumail-worker on >secret resetkeys ~mail:queue:* -@all +evalsha +eval +get +set +del +incr +hgetall +hget +hset +hdel +hincrby +zadd +zrem +zrange +zrangebyscore +zcard
+  ```
+
+### What `Bun.redis` does with bytes and text
+
+Measured on Bun 1.4.2 against Redis 7:
+
+- An argument may be a `Uint8Array`: `send` writes it as it is, every
+  byte value, to `EVAL` and `EVALSHA` too. That is how a message is
+  written, through the script that adds its item.
+- A bulk string in a reply is decoded as UTF-8 into a JavaScript string,
+  so bytes that are not UTF-8 do not come back from `send`. A message is
+  read with `getBuffer`, which keeps the bytes.
+- A string argument is encoded as UTF-8, and a lone surrogate becomes
+  U+FFFD without a word: the contract's checks refuse a lone surrogate
+  (and a NUL, which Redis could keep) before anything is sent, so what is
+  read back is always what was given.
+- `HGETALL` sent directly comes back as an object; the same from a script
+  as a flat list of names and values. A script's `false` is `null`.
+- An error reply rejects with a `RedisError` whose message is Redis's
+  (`NOSCRIPT No matching script…`); none of them repeats the URL.
+- A server out of reach: with Bun's defaults a call waits for 20
+  reconnections, about half a minute, then rejects with `Max
+  reconnection attempts reached`; a URL that is not one is not refused by
+  `new Bun.RedisClient`, only by its first call, so the store checks the
+  scheme itself.
+
 ## Testing
 
 Inject the clock and the sender, and call `deliverDue()` by hand: no
@@ -541,20 +785,31 @@ 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
   dropped with its message.
 - Times are given by the caller; the store keeps no clock.
 - Nothing it returns is shared with what it keeps.
+- `reschedule` with an owner refuses an empty owner as `INVALID`, even
+  for an id no item has. An id a store cannot keep (one holding a NUL or
+  a lone surrogate) may instead be answered `false`, unknown, before the
+  owner is checked.
 - Text it keeps holds no NUL and no lone surrogate: the contract's
   checks refuse them (`INVALID`) in what is added, claimed and recorded,
   since PostgreSQL cannot keep them, and an id holding one is unknown.
   The queue never gives a store such text: it cleans every reply.
 
-The contract's specs, `describeQueueStore`, which both stores here run,
+The contract's specs, `describeQueueStore`, which every store here runs,
 are internal for now: a store written outside this package cannot run
 them yet.
 

package/docs/roadmap.md

@@ -6,19 +6,17 @@ only number on it.
 
 ## Now
 
-Nothing in progress: the Redis store, first under Next, is the next one
-taken. The PostgreSQL store is merged (see Shipped).
+Nothing in progress: the MongoDB store, first under Next, is the next
+one taken. The Redis store shipped in 0.3.0 (see Shipped).
 
 ## Next
 
 More answers to the `QueueStore` contract, built for several instances of
 a server sharing one queue — each claim atomic across them, each lease
 taken back from an instance that crashed — and each held to the same
-contract specs as the memory, `bun:sqlite` and PostgreSQL stores. None
-adds a dependency.
+contract specs as the memory, `bun:sqlite`, PostgreSQL and Redis
+stores. None adds a dependency.
 
-- **A Redis store**, on Bun's own `Bun.redis` — the due items in a sorted
-  set, the claim and the lease in one script.
 - **A MongoDB store** — the contract answered structurally, against a
   collection of the shape a MongoDB driver gives, so the package peers on
   no driver: the application passes in its own collection; the claim a
@@ -55,7 +53,7 @@ Then:
 
 - **A runtime dependency.** The memory store needs none, the `bun:sqlite`
   store uses Bun's own SQLite, the PostgreSQL store Bun's own `Bun.sql`,
-  the Redis store to come `Bun.redis`, and the MongoDB store will take
+  the Redis store Bun's own `Bun.redis`, and the MongoDB store will take
   the application's own collection, typed by its shape.
 - **Relaying on its own.** The queue sends what the app enqueues; who may
   send is decided before, by the SMTP server's AUTH or the app. No option
@@ -67,6 +65,50 @@ 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
+  `{ url }` a `redis://` URL, and needs no driver. Every operation that
+  writes is one Lua script, which Redis runs whole: two instances never
+  take the same item, a crashed instance's leases expire and its items
+  are claimed again, and `maxItems` holds across instances. The due
+  items are in sorted sets, each item a hash, its message written byte
+  for byte, every key under a `keyPrefix`. Held to the same contract
+  specs as the other stores, and to specs of two instances delivering
+  every item exactly once. One Redis, or a primary with replicas, not
+  Cluster; its durability is Redis's, which the guide spells out.
+- **A lease lost to an instance that finished the item is reported** —
+  an instance that stalled past its lease, while another claimed the
+  item, delivered it and dropped it, no longer takes the item's absence
+  for a cancel: it reports `LEASE_LOST` on the `error` event, tells no
+  outcome and sends no DSN, so the operator learns the message may have
+  gone out twice. With no record of who dropped an item, a lease that
+  expired, or a renewal refused while the item was still there, is
+  reported as lost or cancelled; a cancel under a lease that
+  still held is told as before, and no longer draws a `LEASE_LOST` from
+  a renewal that finds the item gone.
+
+### 0.2.0
+
 - **A PostgreSQL store**, `@bumail/queue/postgres`, on Bun's own
   `Bun.sql`, for instances of a server on several machines sharing one
   queue: `PostgresQueueStore.open({ sql })` takes a `Bun.SQL` client or a