fix(drivers): thirteen verified defects across the driver layer (#116–#128)

[productdevbook]

Thirteen defects in the driver layer, each reproduced with a runnable probe before it was filed and each closed here with a regression test. Issues #116–#128.

Silent corruption and lost mail

#116 — a short text attachment arrived corrupt. isBase64("test") was true, so a four-byte text attachment went on the wire unencoded and the recipient's client decoded it into "µë-". No error, on any driver.

"test" isBase64 = true -> sent as "test"
what the recipient decodes: "µë-"
correct would have been:    "dGVzdA=="

This one is not fixable by improving the guess: "test" is valid text and valid base64, and so is "data", "Name", "MyReport". A string is now text unless the caller says encoding: "base64".

#117 — a failed pool handoff hung send() forever. release() shifted the waiter off the queue and then awaited create(). When that rejected — the provider stopped accepting connections, DNS went away — the waiter had already been removed and was never resolved or rejected. smtp.ts swallowed the rejection, so nothing was logged either. Waiters now carry both outcomes.

#118 — a body dying mid-stream was classified as permanent. await response.text() sat outside the try, and fetch() resolves as soon as the headers arrive. A proxy timing out while the body streamed threw past the driver boundary and arrived as PROVIDER / retryable: false — so retry skipped it and the mail was simply lost. It is a retryable NETWORK failure now.

#119 — resend.sendBatch dropped idempotencyKey entirely. send() set the header; sendBatch() did not. Since any list of two or more goes down the batch path, a retried batch duplicated every message in it. A batch now presents one key derived from its messages' keys — stable for the same batch, different for any other.

#124 — SMTP sent a completely empty email. A template-only message passes the core's body check, reaches SMTP with no text and no html, and buildMime renders an empty part. It was transmitted, accepted, and reported ok.

The fix is general: driver.features was declared by all six drivers and read by nothing. The core reads it now, and a message asking for something the driver has said it cannot do comes back UNSUPPORTED. Only that message fails — the rest of the batch goes out — and a driver that declares no features at all is not second-guessed.

Wrong on the wire

#121 — a long non-ASCII subject broke two RFCs at once. One encoded-word of 124 characters against RFC 2047's cap of 75, on a header line of 1997 octets against RFC 5322's hard limit of 998. foldHeader could not help: base64 has no spaces to fold on. Now split across several encoded-words, never mid-character, and round-tripping exactly.

#122 — a quote in a filename opened a second parameter.

Content-Disposition: attachment; filename="report.txt"; filename="payload.exe"

Quotes are escaped now, and a non-ASCII filename uses RFC 2231 (filename*=UTF-8''…) rather than an encoded-word, which is not valid in a parameter.

#120 — resend.sendBatch sent attachments to an endpoint that rejects them. Resend's reference: "The attachments field is not supported yet." Behaviour therefore changed with list length — sendBatch([a]) attached the invoice, sendBatch([a, b]) did not. Such a batch takes the single-send path now.

#123 — neither batch driver chunked at the provider's cap. 150 messages in one Resend request (cap 100), 600 in one Postmark request (cap 500). The provider rejected the request and that single error was reported against every message in it.

#125 — every SMTP connection announced localhost.localdomain. resolveLocalName() reached for globalThis.require, which does not exist in an ESM module, so req?.(…) short-circuited, the hostname branch was unreachable, and the try/catch never even fired. Dead code that the docs described as working. It reads node:os properly now, once per driver, and keeps the fallback for a name that is not fully qualified.

#126 — Postmark dropped the first tag's value. The comment above the code said "the rest carry as metadata so nothing the caller set is silently dropped"; tags[0].value was exactly what got silently dropped.

#127 — DKIM documented PKCS1 and only imported PKCS8. openssl genrsa writes PKCS1, and Web Crypto has no PKCS1 import format at all, so the most common key file failed with an unhelpful Invalid keyData. PKCS1 keys are now wrapped in the RFC 5208 PrivateKeyInfo envelope — and the resulting signature is byte-identical to the one the same key produces as PKCS8, which is how I know the DER is right.

#128 — the composites re-initialized on every send. fallback and roundRobin reach their legs directly, so the core's memoized ensureInitialized never saw them. Five sends, five initialize() calls.

Verification

269 tests before, 293 now. Lint, format, typecheck, JSR dry run, build with every .d.mts present, bundle budgets, version consistency — all clean. Coverage 84.53% statements / 87.29% lines, above the floors set in #129.

Note on versioning

Attachment.encoding is additive, but #116 changes what happens to a string attachment that looks like base64 and was not declared as such. That is a corruption fix rather than a feature removal, but it is a behaviour change — worth 1.1.0 rather than a patch, and worth a line in the release notes.

Noticed, not fixed

Two leads in connection.ts, the least-covered file left at 60%:

• sendInternal awaits "drain" with no error path. A socket erroring while backpressured could hang the write — the same shape as fix(drivers): a failed SMTP pool handoff drops the waiter, hanging send() forever #117. Not reproducible against the current fake server, so unproven rather than refuted.
• The STARTTLS upgrade leaves data/error/close listeners on the pre-upgrade socket. Exercising it needs a TLS-capable fake server, which the harness does not have.

Both are worth a follow-up, and both need the test harness extended before they can be settled either way.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQAPDWLnDrdYHKhou3Ntvb