@bumail/queue 0.11.0 → 0.13.0

package/README.md

@@ -28,6 +28,7 @@ queue that only uses a smarthost needs none.
 | `@bumail/queue/sqlite` | `SqliteQueueStore`: on disk with `bun:sqlite`, shared by the processes of one machine |
 | `@bumail/queue/postgres` | `PostgresQueueStore`: on PostgreSQL through Bun's own `Bun.sql`, shared by instances on several machines |
 | `@bumail/queue/redis` | `RedisQueueStore`: on Redis through Bun's own `Bun.redis`, shared by instances on several machines |
+| `@bumail/queue/conformance` | `describeQueueStore`: the `QueueStore` contract suite, run with `bun test` against a store written outside the package |
 
 ## Usage
 
@@ -152,6 +153,27 @@ 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).
 
+## 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
@@ -255,6 +277,29 @@ if (next) await queue.retryNow(next.id); // false while a worker delivers it
 if (next) await queue.cancel(next.id); // no DSN
 ```
 
+## A store of your own
+
+`QueueStore` may grow in a 0.x minor version (methods, fields); a store of your own follows it.
+
+Hold a `QueueStore` you wrote to the same tests the stores here pass.
+The spec runs with `bun test` (the suite imports `bun:test`):
+
+```ts
+// my-store.spec.ts
+import { describeQueueStore } from '@bumail/queue/conformance';
+import { MyQueueStore } from './my-store';
+
+describeQueueStore('MyQueueStore', {
+	create: () => MyQueueStore.open({ url: process.env.MY_STORE_URL }),
+	share: (store) => (store as MyQueueStore).connectAgain(), // a second handle on the same queue
+	dispose: (store) => (store as MyQueueStore).close(),
+});
+```
+
+Without `share` the two several-workers tests are skipped, and a store
+shared over a network should pass a real second connection. See
+[Holding your own store to the contract](https://github.com/softistx/bumail/blob/develop/packages/queue/docs/guide.md#holding-your-own-store-to-the-contract).
+
 ## Testing
 
 ```ts
@@ -344,8 +389,9 @@ control character in it.
 | 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`), `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 |

package/dist/conformance/claims.d.ts

@@ -0,0 +1,4 @@
+import { type StoreFactories } from './setup';
+/** Claims, leases and schedules. */
+export declare function describeClaims(factories: StoreFactories): void;
+//# sourceMappingURL=claims.d.ts.map

package/dist/conformance/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../../src/conformance/claims.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,cAAc,EAAM,MAAM,SAAS,CAAC;AAa1E,oCAAoC;AACpC,wBAAgB,cAAc,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAM9D"}

package/dist/conformance/complete-dsns.d.ts

@@ -0,0 +1,4 @@
+import { type StoreFactories } from './setup';
+/** The DSNs `complete` takes: stored with the outcome, or not at all. */
+export declare function completeDsns(factories: StoreFactories): void;
+//# sourceMappingURL=complete-dsns.d.ts.map

package/dist/conformance/complete-dsns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete-dsns.d.ts","sourceRoot":"","sources":["../../src/conformance/complete-dsns.ts"],"names":[],"mappings":"AAEA,OAAO,EAON,KAAK,cAAc,EAEnB,MAAM,SAAS,CAAC;AAgBjB,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,GAAG,IAAI,CAK5D"}

package/dist/conformance/concurrency.d.ts

@@ -0,0 +1,4 @@
+import { type StoreFactories } from './setup';
+/** Several claimers on one queue, and a claimer that crashed. */
+export declare function describeConcurrency({ create, share }: StoreFactories): void;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/conformance/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../../src/conformance/concurrency.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,cAAc,EAAM,MAAM,SAAS,CAAC;AA2BjE,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,cAAc,GAAG,IAAI,CAkD3E"}

package/dist/conformance/describe-queue-store.d.ts

@@ -0,0 +1,11 @@
+import type { QueueStoreHarness } from './setup';
+/**
+ * The specs every `QueueStore` must pass, to call from a spec file run by
+ * `bun test`. The harness builds an empty store with `create`; `share` is
+ * another handle on the same queue (a second connection, as a second
+ * process opens), so the claim's atomicity is checked across handles, not
+ * only within one: without it those tests are registered as skipped.
+ * `dispose` runs after every test with the stores that test created.
+ */
+export declare function describeQueueStore(name: string, harness: QueueStoreHarness): void;
+//# sourceMappingURL=describe-queue-store.d.ts.map

package/dist/conformance/describe-queue-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-queue-store.d.ts","sourceRoot":"","sources":["../../src/conformance/describe-queue-store.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,GACxB,IAAI,CA6BN"}

package/dist/conformance/doubt.d.ts

@@ -0,0 +1,5 @@
+import { type StoreFactories } from './setup';
+/** The marks a recipient keeps when a server may hold a copy. */
+export declare function doubt({ create }: StoreFactories): void;
+export declare function fallbackDoubt({ create }: StoreFactories): void;
+//# sourceMappingURL=doubt.d.ts.map

package/dist/conformance/doubt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doubt.d.ts","sourceRoot":"","sources":["../../src/conformance/doubt.ts"],"names":[],"mappings":"AAEA,OAAO,EAMN,KAAK,cAAc,EAEnB,MAAM,SAAS,CAAC;AAEjB,iEAAiE;AACjE,wBAAgB,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CAwEtD;AAED,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CA8E9D"}

package/dist/conformance/dsn.d.ts

@@ -0,0 +1,4 @@
+import { type StoreFactories } from './setup';
+/** RFC 3461's parameters: kept as given, for the item's whole life. */
+export declare function dsnParameters({ create }: StoreFactories): void;
+//# sourceMappingURL=dsn.d.ts.map

package/dist/conformance/dsn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dsn.d.ts","sourceRoot":"","sources":["../../src/conformance/dsn.ts"],"names":[],"mappings":"AACA,OAAO,EAKN,KAAK,cAAc,EAEnB,MAAM,SAAS,CAAC;AAEjB,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,EAAE,cAAc,GAAG,IAAI,CAqJ9D"}

package/dist/conformance/index.d.ts

@@ -0,0 +1,3 @@
+export { describeQueueStore } from './describe-queue-store';
+export type { CreateQueueStore, QueueStoreHarness, ShareStore } from './setup';
+//# sourceMappingURL=index.d.ts.map

package/dist/conformance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conformance/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}