@bumail/smtp 0.11.0 → 0.12.0

package/README.md

@@ -300,6 +300,33 @@ It resolves once the server took the message for one recipient at least:
 encrypted and the certificate checked. Anything else rejects with an
 `SmtpError` whose `temporary` says whether trying later may succeed.
 
+### Reuse connections with a pool
+
+`createSmtpPool(options?)` keeps connections to the same server between
+messages, so a burst to one host pays for one greeting, one STARTTLS
+and one AUTH. The pool's own options, all optional, are `maxMessages`
+(100 per connection), `idleSeconds` (5), `maxAgeSeconds` (300) and
+`maxIdlePerHost` (4). `pool.sendMail(message, options)` takes the options
+of `sendMail`.
+
+```ts
+import { createSmtpPool } from '@bumail/smtp/client';
+
+const pool = createSmtpPool(); // or createSmtpPool({ idleSeconds: 10 })
+const first = await pool.sendMail(message, { host: 'smtp.example.com', from: 'alice@example.com', to: 'bob@example.org' });
+const second = await pool.sendMail(message, { host: 'smtp.example.com', from: 'alice@example.com', to: 'carol@example.org' });
+console.log(first.reused, second.reused); // false, then true: the second went over the first's connection
+await pool.close(); // QUITs the idle connections, waits for the busy ones
+```
+
+A connection is reset (RSET) each time it is lent, kept apart by
+server address, greeting name, TLS and credentials, and never reused
+after a 421, a timeout, a bad reply, a lost stream or bytes it was not
+asked for. A reused connection that turns out dead before MAIL FROM is
+replaced by a fresh one without the caller seeing it. `@bumail/queue` uses a
+pool by default (its `reuse` option), and so does the `bumail serve` outbound
+queue of `@bumail/server`.
+
 ## Send mail: direct to a domain's MX
 
 `{ domain, resolver }` instead of `{ host }` looks up the domain's MX
@@ -484,7 +511,7 @@ host; a 5xx stops. A null MX (RFC 7505) fails at once with `NULL_MX`.
 | `SmtpServer` | `listen({ port, hostname? })` (once; again, even before the first resolved, throws `ALREADY_LISTENING`; on implicit TLS, a key or certificate it cannot read or use throws `INVALID_OPTION`), `setTls({ key, cert })` (a renewed pair for new STARTTLS upgrades and new implicit TLS connections; open sessions keep theirs; a pair that cannot be used throws `INVALID_OPTION` and the old one stays), `stop(closeConnections?)` (`true` hangs up on every client, after STARTTLS too), `connections` |
 | `SmtpServerOptions` | `hostname`, `mode`, `localDomains`, `tls`, `implicitTls`, `authenticate`, the limits (`maxConnectionsPerClient` among them), `hookTimeout`, `handshakeTimeout`, `greetingDelay`, `proxyProtocol`, `onError`, and the hooks |
 | `ProxyProtocolOptions` | `trusted`: the proxies' IPv4 and IPv6 addresses and CIDRs, the only peers whose PROXY header (v1 or v2) is read |
-| `SmtpError`, `SmtpErrorCode` | `code`: `INVALID_OPTION`, `ALREADY_LISTENING`, `STOPPED` (a `stop()` came before `listen` resolved), and what a content stream or `onError` can get: `MESSAGE_TOO_BIG`, `BARE_LINE_BREAK`, `NUL_BYTE`, `CONNECTION_LOST`, `HOOK_TIMEOUT`, `INVALID_HOOK_REPLY`, `MESSAGE_NOT_READ`; `sendMail`'s are listed below. `temporary`, `reply` and `rejected` are set for `sendMail`'s errors (`rejected` also after the final dot), and `afterData` when the final dot was written and no reply came (the server may have taken the message; `accepted` and `rejected` then list the recipients taken and refused at `RCPT TO`) |
+| `SmtpError`, `SmtpErrorCode` | `code`: `INVALID_OPTION`, `ALREADY_LISTENING`, `STOPPED` (a `stop()` came before `listen` resolved, or `sendMail` on a closed pool), and what a content stream or `onError` can get: `MESSAGE_TOO_BIG`, `BARE_LINE_BREAK`, `NUL_BYTE`, `CONNECTION_LOST`, `HOOK_TIMEOUT`, `INVALID_HOOK_REPLY`, `MESSAGE_NOT_READ`; `sendMail`'s are listed below. `temporary`, `reply` and `rejected` are set for `sendMail`'s errors (`rejected` also after the final dot), and `afterData` when the final dot was written and no reply came (the server may have taken the message; `accepted` and `rejected` then list the recipients taken and refused at `RCPT TO`) |
 | `SmtpHooks` | `onConnect`, `onMailFrom`, `onRcptTo`, `onData` |
 | `HookResult` | what a hook returns: `undefined` to accept, a `Reply` to refuse |
 | `Session` | `id`, `remoteAddress`, `secure`, `helo`, `esmtp`, `user`, and `data` for your own state |
@@ -505,9 +532,10 @@ host; a 5xx stops. A null MX (RFC 7505) fails at once with `NULL_MX`.
 | export | |
 | --- | --- |
 | `sendMail(message, options)` | delivers one message; resolves to a `SendMailResult`, rejects with an `SmtpError` |
+| `createSmtpPool(options?)`, `SmtpPool`, `SmtpPoolOptions` | a pool of reusable connections: `pool.sendMail(message, options)` (as `sendMail`, `result.reused`) and `pool.close()`; `maxMessages` (100), `idleSeconds` (5), `maxAgeSeconds` (300), `maxIdlePerHost` (4) |
 | `SendMailOptions` | `from`, `to`, and `{ host, port? }` or `{ domain, resolver, port? }`; `helo`, `tls`, `secure`, `ca`, `auth`, `allowPlaintextAuth`, `size`, `smtputf8`, `ret`, `envid`, `recipients` (DSN, see [Sending DSN parameters](./docs/guide.md#sending-dsn-parameters)), `normalizeLineEnds`, `timeouts`, `deadline` |
 | `HostDestination`, `MxDestination`, `SendMailEnvelope` | the parts of `SendMailOptions` |
-| `SendMailResult` | `accepted`, `rejected`, `reply`, `host`, `port`, `tls` (`false` or `{ verified }`), `authenticated`, `dsnOffered` (the server listed DSN in EHLO, so the DSN options were sent) |
+| `SendMailResult` | `accepted`, `rejected`, `reply`, `host`, `port`, `tls` (`false` or `{ verified }`), `authenticated`, `dsnOffered` (the server listed DSN in EHLO, so the DSN options were sent), `reused?` (a pool only: the connection had carried a message before) |
 | `SendMailAuth` | `username`, `password`, `mechanism?` (`PLAIN` or `LOGIN`) |
 | `SendMailTimeouts` | seconds: `connect`, `greeting`, `command`, `mail`, `rcpt`, `dataStart`, `dataBlock`, `dataEnd` |
 | `TlsMode` | `'opportunistic'`, `'required'` or `'none'` |

package/dist/client/connect.d.ts

@@ -0,0 +1,18 @@
+import type { SendMailResult } from './options';
+import { type Ready } from './session';
+import type { ClientSettings } from './settings';
+import { ClientSocket } from './socket';
+import type { Clock, Endpoint } from './target';
+import type { Delivered } from './transaction';
+/** Errors from before MAIL FROM: another MX host may do better. */
+export declare const early: WeakSet<object>;
+/** A connection, past its greeting, EHLO, STARTTLS and AUTH. */
+export interface Session {
+    readonly socket: ClientSocket;
+    readonly ready: Ready;
+}
+/** Connects and opens a session; a failure is marked `early`. The socket's clock is the delivery's. */
+export declare function connect(endpoint: Endpoint, settings: Pick<ClientSettings, 'tls' | 'secure' | 'ca' | 'timeouts' | 'helo' | 'auth' | 'allowPlaintextAuth'>, clock: Clock): Promise<Session>;
+/** What a delivery reports: the server's answers, where they came from and how the session was secured. */
+export declare function resultOf(delivered: Delivered, { socket, ready }: Session, endpoint: Pick<Endpoint, 'host' | 'port'>): SendMailResult;
+//# sourceMappingURL=connect.d.ts.map

package/dist/client/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/client/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAQ,KAAK,KAAK,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAa,MAAM,UAAU,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,mEAAmE;AACnE,eAAO,MAAM,KAAK,iBAAwB,CAAC;AAE3C,gEAAgE;AAChE,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACtB;AAED,uGAAuG;AACvG,wBAAsB,OAAO,CAC5B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,IAAI,CACb,cAAc,EACZ,KAAK,GACL,QAAQ,GACR,IAAI,GACJ,UAAU,GACV,MAAM,GACN,MAAM,GACN,oBAAoB,CACtB,EACD,KAAK,EAAE,KAAK,GACV,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAED,2GAA2G;AAC3G,wBAAgB,QAAQ,CACvB,SAAS,EAAE,SAAS,EACpB,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,GACvC,cAAc,CAQhB"}

package/dist/client/inbox.d.ts

@@ -10,6 +10,8 @@ export declare class Inbox {
     #private;
     /** Takes the next bytes; says what is wrong with them, if they are not replies. */
     push(chunk: Uint8Array): string | undefined;
+    /** The bytes counted against `MAX_REPLY_BYTES` start over: a new message on a reused connection. */
+    reset(): void;
     /** The next complete reply. */
     shift(): Reply | undefined;
     /** Bytes or replies not yet read. */

package/dist/client/inbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/client/inbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,6EAA6E;AAC7E,eAAO,MAAM,eAAe,QAAc,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,KAAK;;IAMjB,mFAAmF;IACnF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAiB3C,+BAA+B;IAC/B,KAAK,IAAI,KAAK,GAAG,SAAS;IAI1B,qCAAqC;IACrC,IAAI,OAAO,IAAI,OAAO,CAErB;CACD"}
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/client/inbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG/C,6EAA6E;AAC7E,eAAO,MAAM,eAAe,QAAc,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,KAAK;;IAMjB,mFAAmF;IACnF,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAiB3C,oGAAoG;IACpG,KAAK,IAAI,IAAI;IAIb,+BAA+B;IAC/B,KAAK,IAAI,KAAK,GAAG,SAAS;IAI1B,qCAAqC;IACrC,IAAI,OAAO,IAAI,OAAO,CAErB;CACD"}

package/dist/client/index.d.ts

@@ -3,5 +3,7 @@ export type { Reply } from '../protocol/reply';
 export { isMailbox } from './address';
 export { type MailHost, resolveMx } from './mx';
 export type { HostDestination, MessageSource, MxDestination, MxResolver, SendMailAuth, SendMailEnvelope, SendMailOptions, SendMailResult, SendMailTimeouts, TlsMode, } from './options';
+export { createSmtpPool, type SmtpPool } from './pool';
+export type { SmtpPoolOptions } from './pool/options';
 export { sendMail } from './send';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAChD,YAAY,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,OAAO,GACP,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,gBAAgB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,QAAQ,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAChD,YAAY,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,OAAO,GACP,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvD,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC"}