@zerotal/notifications 1.7.4 → 1.8.0

package/CHANGELOG.md

@@ -8,6 +8,21 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.8.0] — 2026-08-24
+
+### Fixed
+
+- **No mail could be sent over port 587.** A STARTTLS upgrade hands back a new socket and
+  leaves the old one attached, still firing its callbacks — and what the old one delivers from
+  then on is the undecrypted TLS stream. Both sets of handlers appended to one reply buffer,
+  so handshake records and ciphertext sat in the middle of the server's replies and no line
+  matched a reply any more: the driver waited out its timeout without ever parsing the `250`,
+  and the server logged a connection lost after STARTTLS. `close` and `error` were worse than
+  `data` — the plaintext socket ending is a normal part of handing over to TLS, and it marked
+  the live connection closed, rejecting whatever was waiting on the session that had just
+  replaced it. Callbacks now capture the generation they were installed for and an upgrade
+  bumps it, so anything from an older stream is ignored.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/api-surface.md

@@ -18,21 +18,6 @@ class BroadcastMessage = {
   readonly data: Record<string, unknown>
 }
 
-class BroadcastNotificationJob = {
-  new (_channel?: string, _event?: string, _data?: Record<string, unknown>, queue?: string): BroadcastNotificationJob
-  static fromPayload: (data: Record<string, unknown>) => BroadcastNotificationJob
-  _chain: SerializedJob[] | undefined
-  batchId: string | undefined
-  className: string
-  debounceKey: () => string
-  handle: () => Promise<void>
-  payload: () => Record<string, unknown>
-  readonly debounce?: number
-  readonly maxAttempts: number
-  readonly queue: string
-  readonly retryDelay: number
-}
-
 class DatabaseChannel = {
   new (table: string, _sql: SQLInstance): DatabaseChannel
   _count: () => Promise<number>
@@ -236,62 +221,6 @@ class NotificationSent = {
   readonly ok: boolean
 }
 
-class NotificationsPruneCommand = {
-  new (): NotificationsPruneCommand
-  static args: ArgDef[]
-  static commandName: string
-  static description: string
-  static flags: FlagDef[]
-  static needsApp: boolean
-  _readLine: () => Promise<string>
-  _writer: OutputWriter
-  app: unknown
-  args: Record<string, string>
-  ask: (question: string, defaultValue?: string) => Promise<string>
-  choice: (question: string, options: string[]) => Promise<string>
-  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
-  dim: (msg: string) => void
-  error: (msg: string) => void
-  flags: Record<string, string | number | boolean>
-  info: (msg: string) => void
-  line: (msg: string) => void
-  newLine: () => void
-  run: () => Promise<void>
-  secret: (question: string) => Promise<string>
-  section: (title: string) => void
-  table: (rows: [string, string][], indent?: number) => void
-  warn: (msg: string) => void
-  write: (msg: string) => void
-}
-
-class NotificationsTestCommand = {
-  new (): NotificationsTestCommand
-  static args: ArgDef[]
-  static commandName: string
-  static description: string
-  static flags: FlagDef[]
-  static needsApp: boolean
-  _readLine: () => Promise<string>
-  _writer: OutputWriter
-  app: unknown
-  args: Record<string, string>
-  ask: (question: string, defaultValue?: string) => Promise<string>
-  choice: (question: string, options: string[]) => Promise<string>
-  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
-  dim: (msg: string) => void
-  error: (msg: string) => void
-  flags: Record<string, string | number | boolean>
-  info: (msg: string) => void
-  line: (msg: string) => void
-  newLine: () => void
-  run: () => Promise<void>
-  secret: (question: string) => Promise<string>
-  section: (title: string) => void
-  table: (rows: [string, string][], indent?: number) => void
-  warn: (msg: string) => void
-  write: (msg: string) => void
-}
-
 class OnDemandNotifiable = {
   new (_routes: OnDemandRoutes): OnDemandNotifiable
   readonly email?: string
@@ -317,21 +246,6 @@ class RichLine = {
   text: (content: string) => RichLine
 }
 
-class SendNotificationJob = {
-  new (_notifiable?: Notifiable | undefined, _notification?: Notification | undefined, serialized?: SerializedNotification): SendNotificationJob
-  static fromPayload: (data: Record<string, unknown>) => SendNotificationJob
-  _chain: SerializedJob[] | undefined
-  batchId: string | undefined
-  className: string
-  debounceKey: () => string
-  handle: () => Promise<void>
-  payload: () => Record<string, unknown>
-  readonly debounce?: number
-  readonly maxAttempts: number
-  readonly queue: 'notifications'
-  readonly retryDelay: number
-}
-
 class SlackChannel = {
   new (config?: { webhook?: string; }): SlackChannel
   send: (notifiable: Notifiable, notification: Notification) => Promise<void>
@@ -396,8 +310,6 @@ function NotificationConfig = (options?: DeepPartial<NotificationConfigShape>) =
 
 function recentDeliveries = () => RecentDelivery[]
 
-function validateNotificationConfig = (config: NotificationConfigShape) => void
-
 interface ChannelStat = {
   avgMs: number
   channel: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/notifications",
-  "version": "1.7.4",
+  "version": "1.8.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,12 +30,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.4",
-    "@zerotal/orm": "1.7.4",
-    "@zerotal/queue": "1.7.4"
+    "@zerotal/core": "1.8.0",
+    "@zerotal/orm": "1.8.0",
+    "@zerotal/queue": "1.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.7.4",
+    "@zerotal/broadcasting": "1.8.0",
     "typescript": "^5.8.0"
   },
   "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",

package/src/drivers/SmtpDriver.ts

@@ -151,8 +151,16 @@ interface SmtpReply {
  * coalesced with the next reply. Reading is therefore driven by the protocol's
  * own framing — a reply ends at the first line whose code is followed by a space
  * rather than a hyphen — not by packet boundaries.
+ *
+ * Exported for its tests only. The transport rules it enforces — a superseded
+ * socket is not this session's, a reply is framed by the protocol and not by
+ * packet boundaries — cannot be reached through `SmtpDriver.send()` without a
+ * STARTTLS-capable peer, and Bun cannot be one: server-side TLS upgrade is not
+ * supported, so no in-process fake can complete the handshake.
+ *
+ * @internal
  */
-class SmtpConnection {
+export class SmtpConnection {
   private _buffer = "";
   private _replies: SmtpReply[] = [];
   private _waiters: Array<{
@@ -163,6 +171,25 @@ class SmtpConnection {
   private _closed = false;
   private _encrypted: boolean;
 
+  /**
+   * Which set of socket callbacks is the live one.
+   *
+   * `upgradeTLS()` does not detach the plaintext socket: its handlers go on
+   * firing, and what they deliver from then on is the *undecrypted* TLS stream —
+   * handshake records and ciphertext. Feeding that to `_onData` put binary in the
+   * middle of the reply buffer, so the `250` after STARTTLS was never parsed and
+   * every send died on the read timeout, with the server logging a connection
+   * lost after STARTTLS. `close` and `error` were worse: the superseded socket
+   * ending marked the live connection closed and rejected whatever was waiting on
+   * it.
+   *
+   * Each set of callbacks captures the generation it was installed for, and an
+   * upgrade bumps it. Anything from an older generation is somebody else's
+   * stream. Identity comparison against the current socket would nearly work,
+   * but a counter cannot be fooled by a runtime that hands the same object back.
+   */
+  private _generation = 0;
+
   private constructor(
     private _socket: import("bun").Socket<undefined>,
     private readonly _host: string,
@@ -192,9 +219,10 @@ class SmtpConnection {
           ? { tls: { rejectUnauthorized: options.rejectUnauthorized, serverName: host } }
           : {}),
         socket: {
-          data: (_s, data) => conn._onData(data),
-          error: (_s, err) => conn._onError(err),
-          close: () => conn._onClose(),
+          // Generation 0: the connection as opened. An upgrade supersedes it.
+          data: (_s, data) => conn._onData(data, 0),
+          error: (_s, err) => conn._onError(err, 0),
+          close: () => conn._onClose(0),
           open: () => {},
         },
       });
@@ -212,12 +240,15 @@ class SmtpConnection {
   /** Upgrade a plaintext connection to TLS after a 220 response to STARTTLS. */
   async upgradeTLS(host: string, rejectUnauthorized: boolean): Promise<void> {
     try {
+      // Bumped before the call, so the plaintext socket's callbacks are already
+      // stale by the time the handshake can deliver its first record.
+      const generation = ++this._generation;
       const [, tls] = this._socket.upgradeTLS<undefined>({
         tls: { rejectUnauthorized, serverName: host },
         socket: {
-          data: (_s, data) => this._onData(data),
-          error: (_s, err) => this._onError(err),
-          close: () => this._onClose(),
+          data: (_s, data) => this._onData(data, generation),
+          error: (_s, err) => this._onError(err, generation),
+          close: () => this._onClose(generation),
           open: () => {},
         },
       });
@@ -305,7 +336,8 @@ class SmtpConnection {
     }
   }
 
-  private _onData(data: Uint8Array): void {
+  private _onData(data: Uint8Array, generation: number): void {
+    if (generation !== this._generation) return; // ciphertext from a superseded socket
     this._buffer += new TextDecoder().decode(data);
     this._parse();
   }
@@ -350,14 +382,18 @@ class SmtpConnection {
     }
   }
 
-  private _onError(error: Error): void {
+  private _onError(error: Error, generation: number): void {
+    if (generation !== this._generation) return;
     this._failure = new SmtpConnectionError(
       `SMTP socket error on ${this._host}:${this._port} — ${error.message}`,
     );
     this._rejectAll(this._failure);
   }
 
-  private _onClose(): void {
+  private _onClose(generation: number): void {
+    // The plaintext socket ends as a matter of course once TLS takes over, and
+    // treating that as the connection dropping killed the session that replaced it.
+    if (generation !== this._generation) return;
     this._closed = true;
     if (this._waiters.length > 0) {
       this._rejectAll(