@bumail/queue 0.12.0 → 0.14.0

package/README.md

@@ -12,11 +12,12 @@ share one queue. No runtime dependency: only peers.
 
 ```sh
 bun add @bumail/queue @bumail/smtp @bumail/mime
+bun add @bumail/mta-sts   # a required peer (its types are in the API), used when you set mtaSts
 bun add @bumail/dns   # for direct delivery by MX: the resolver
 ```
 
-`@bumail/smtp` (its client) and `@bumail/mime` (for the DSNs) are required
-peers. `@bumail/dns` is optional: any resolver of its shape will do, and a
+`@bumail/smtp` (its client), `@bumail/mime` (for the DSNs) and
+`@bumail/mta-sts` (for `mtaSts`) are required peers. `@bumail/dns` is optional: any resolver of its shape will do, and a
 queue that only uses a smarthost needs none.
 
 ## Subpaths
@@ -153,6 +154,48 @@ With `fallback` (a smarthost), a recipient whose session by MX failed by a
 connection failure, a timeout or a reputation refusal goes through that
 smarthost at once (not after the final dot of `DATA`, where the MX may have taken the message: every recipient the MX did not refuse at `RCPT` is marked `mayHaveReachedMx` and never falls back on its own; a refused one may). If the smarthost's own session ends after the final dot, the recipient is marked `mayHaveReachedFallback` and later attempts go to the smarthost again, not to the MX; see [Falling back to a smarthost](docs/guide.md#falling-back-to-a-smarthost).
 
+## MTA-STS
+
+Opt in with `mtaSts` (off unless given; the smarthost routes and the `fallback` never use it). For each recipient domain on the MX route the queue reads `_mta-sts.<domain>` and fetches the policy (RFC 8461) through `@bumail/mta-sts`, keeping it in a `PolicyCache` until its `max_age` ends. With mode `enforce` it sends with `tls: 'required'` to the MX hosts the policy names only; with `testing` it sends as usual and only reports; a failure under `enforce` is deferred as `4.7.5` and bounced as `5.7.5` only at `retry.giveUpAfter`, after the policy is fetched once more. Under `enforce` nothing goes to the `fallback`: a connection failure defers. `mtaSts.skip(item, domain)` exempts a session (a mailed TLS-RPT report, a domain delivered in-process). Every try is told on the `tls` event, for RFC 8460 reports.
+
+```ts
+import { nodeResolver } from '@bumail/dns';
+import { createMemoryPolicyCache, createQueue } from '@bumail/queue';
+import { MemoryQueueStore } from '@bumail/queue/memory';
+
+const resolver = nodeResolver(); // has txt
+const queue = createQueue({
+	store: new MemoryQueueStore(),
+	hostname: 'mail.example.net',
+	resolver,
+	mtaSts: { cache: createMemoryPolicyCache() }, // fetch: globalThis.fetch; resolver: the queue's
+});
+queue.on('tls', ({ domain, policy, mxHost, ok, tlsResult }) => {});
+```
+
+The `tls` event also carries `kind` (`'try'` or `'policy'`), `at` (the queue's clock, ms), `sendingAddress` and `reused`. A `send` of your own receives `mxNames`, `tls`, `onAttempt` and `onSkip` in its options and has to pass them to `sendMail`. See [MTA-STS](docs/guide.md#mta-sts).
+
+## Reusing connections
+
+Without a `send` of your own, the queue sends through a pool of SMTP
+connections it owns: several messages to one server share a connection
+(100 at most, idle 5 seconds), and `stop()` closes the pool. `reuse` tunes
+it, `reuse: false` opens one connection per session, and a `send` you give
+is never wrapped. Events carry `reused` when the sender says so. The
+`bumail serve` queue of `@bumail/server` sends through the same pool, with
+no setting. See `createSmtpPool` in the `@bumail/smtp` README.
+
+```ts
+createQueue({
+	store: new MemoryQueueStore(),
+	hostname: 'mail.example.net',
+	resolver: nodeResolver(),
+	reuse: { maxMessages: 50, idleSeconds: 10 }, // default { 100, 5 }; or false
+});
+```
+
+See [Reusing connections](docs/guide.md#reusing-connections).
+
 ## Several workers
 
 ```ts
@@ -249,6 +292,7 @@ queue.on('delivered', ({ id, recipient, reply }) => console.info({ id, recipient
 queue.on('deferred', ({ recipient, reply, nextAttemptAt }) => {});
 queue.on('failed', ({ recipient, reply }) => {}); // reply: { code?, status?, text, host? }
 queue.on('dsn', ({ kind, of, to }) => {});
+queue.on('tls', ({ domain, policy, mxHost, address, ok, tlsResult }) => {}); // with mtaSts
 queue.on('error', ({ error, id }) => console.error(id, error)); // the store, a lost lease, a bad route
 
 const [next] = await queue.list({ limit: 50 }); // the next due first
@@ -363,17 +407,34 @@ control character in it.
   }
   ```
 
+## Upgrading
+
+With MTA-STS (the release that adds `mtaSts`):
+
+- **`@bumail/mta-sts` is a required peer.** Install it even when `mtaSts`
+  is unused: `bun add @bumail/mta-sts`.
+- **`QueueEvents` has a new `tls` event kind**, for the TLS-RPT counts. A
+  listener that switches on the event kinds should handle it or ignore it.
+- **`SmtpErrorCode` has `MX_NOT_ALLOWED`** (`X.7.5`, from `@bumail/smtp`), for
+  an MX host an `enforce` policy does not allow. A `switch` over the codes
+  needs the case.
+- **A custom `send` must pass `mxNames`, `tls` and `onAttempt` to
+  `sendMail`**, or an `enforce` policy is not applied and the `tls` events
+  stay silent.
+- `QueueStore` is unchanged.
+
 ## API
 
 | export | |
 | --- | --- |
 | `createQueue(options)`, `Queue` | the queue: `enqueue`, `deliverDue`, `start`, `stop`, `on`, `list`, `get`, `retryNow`, `cancel`, `owner` |
-| `QueueOptions` (`route`, `routes`, `fallback`), `Route`, `Smarthost`, `RetrySchedule`, `DsnOptions`, `QueueLimits`, `Clock`, `Sender` | what `createQueue` takes |
+| `QueueOptions` (`route`, `routes`, `fallback`, `reuse`, `mtaSts`), `Route`, `Smarthost`, `RetrySchedule`, `DsnOptions`, `ReuseOptions`, `QueueLimits`, `Clock`, `Sender` | what `createQueue` takes |
 | `MessageSource`, `QueueEnvelope` (`ret`, `envid`, `recipients`), `RecipientDsn`, `RecipientNotify`, `NotifyEvent`, `OriginalRecipient`, `RetMode` | what `enqueue` takes, with the DSN parameters |
 | `describeQueueStore`, `QueueStoreHarness`, `CreateQueueStore`, `ShareStore` | from `@bumail/queue/conformance`: `describeQueueStore(name, { create, share?, dispose? })`, run under `bun test`; without `share` the two several-workers tests are skipped |
 | `deliveredDsn(input)`, `DeliveredDsnInput`, `DeliveredRecipient` | the `delivered` DSN for a local delivery: the bytes to enqueue, or `undefined` when no recipient asked for `SUCCESS` |
 | `failedDsn(input)`, `FailedDsnInput`, `FailedRecipient`, `DEFAULT_MAX_RETURN` | the `failed` DSN for a recipient the application could not deliver locally: the bytes to enqueue, or `undefined` for a null reverse-path or when no recipient asked for failures; `DEFAULT_MAX_RETURN` is the 64 KiB a DSN returns of the original by default |
-| `QueueEvents`, `QueueListener`, `RecipientEvent` (`route`, `fallback`, `mxReply`, `mayHaveReachedMx`, `mayHaveReachedFallback`), `DeferredEvent`, `DsnEvent`, `QueueErrorEvent` | the events |
+| `QueueEvents`, `QueueListener`, `RecipientEvent` (`route`, `fallback`, `mxReply`, `mayHaveReachedMx`, `mayHaveReachedFallback`), `DeferredEvent`, `DsnEvent`, `TlsEvent`, `TlsPolicyReport`, `QueueErrorEvent` | the events |
+| `MtaStsOptions`, `StsResolver`, `PolicyCache`, `PolicyCacheEntry`, `createMemoryPolicyCache()` | MTA-STS: the `mtaSts` option, its policy cache (`get`, `set`, `delete?`) and a cache in memory |
 | `QueueStore` | the contract a store answers: `add`, `get`, `list`, `count`, `readMessage`, `claim`, `renew`, `complete(id, owner, result, dsns)`, `reschedule`, `cancel` |
 | `Completed` (`item`, `dsns`) | what `complete` returns: the item as it now stands, and the DSN items it stored in the same step, in the order given; `undefined` when the lease was lost |
 | `QueueItem`, `RecipientState`, `RecipientStatus`, `FinalStatus`, `Diagnostic`, `Lease` | an item, and where each recipient stands |

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { DEFAULT_MAX_RETURN } from './dsn/policy';
 export { QueueError, type QueueErrorCode } from './errors';
 export type { MessageSource, QueueEnvelope } from './queue/envelope';
 export type { DeferredEvent, DsnEvent, QueueErrorEvent, QueueEvents, QueueListener, RecipientEvent, } from './queue/events';
-export type { Clock, DsnOptions, QueueLimits, QueueOptions, RetrySchedule, Route, Sender, Smarthost, } from './queue/options';
+export type { Clock, DsnOptions, QueueLimits, QueueOptions, RetrySchedule, ReuseOptions, Route, Sender, Smarthost, } from './queue/options';
 export { createQueue, type Queue } from './queue/queue';
+export { createMemoryPolicyCache, type PolicyCache, type PolicyCacheEntry, } from './sts/cache';
+export type { MtaStsOptions, StsResolver, TlsEvent, TlsPolicyReport, } from './sts/options';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,KAAK,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,OAAO,GACP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,YAAY,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,GACT,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EACX,aAAa,EACb,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACX,KAAK,EACL,UAAU,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,KAAK,EACL,MAAM,EACN,SAAS,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EACX,UAAU,EACV,aAAa,EACb,YAAY,EACZ,SAAS,EACT,UAAU,EACV,WAAW,EACX,KAAK,EACL,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,cAAc,EACd,eAAe,EACf,eAAe,EACf,OAAO,GACP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACN,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,YAAY,GACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,SAAS,GACT,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAC3D,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACrE,YAAY,EACX,aAAa,EACb,QAAQ,EACR,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACX,KAAK,EACL,UAAU,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,KAAK,EACL,MAAM,EACN,SAAS,GACT,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EACN,uBAAuB,EACvB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,aAAa,EACb,WAAW,EACX,QAAQ,EACR,eAAe,GACf,MAAM,eAAe,CAAC"}