@upyo/smtp 0.6.0-dev.287 → 0.6.0-dev.289

package/README.md

@@ -27,6 +27,7 @@ Features
  -  File attachments (regular and inline)
  -  Multiple recipients (To, CC, BCC)
  -  SMTP PIPELINING for faster multi-recipient delivery
+ -  SMTP SIZE declaration and advertised-limit checks
  -  Custom headers
  -  Priority levels
  -  Comprehensive testing utilities
@@ -167,6 +168,20 @@ token across pooled connections.  See the
 [oauth-guide]: https://upyo.org/transports/smtp#oauth-2-0-authentication
 
 
+Message size limits
+-------------------
+
+When the server advertises the `SIZE` extension, the transport declares the
+encoded message size on `MAIL FROM`.  If the server also advertises a fixed
+maximum, an oversized message produces a failed receipt before Upyo sends the
+envelope or uploads the message.  Bare `SIZE` and `SIZE 0` advertisements do not
+set a fixed maximum.  This behavior is automatic and needs no configuration.
+
+See [RFC 1870] for the SMTP Message Size Declaration extension.
+
+[RFC 1870]: https://www.rfc-editor.org/rfc/rfc1870
+
+
 DKIM signing
 ------------
 

package/dist/index.cjs

@@ -22,9 +22,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const __upyo_core = __toESM(require("@upyo/core"));
+const node_buffer = __toESM(require("node:buffer"));
 const node_net = __toESM(require("node:net"));
 const node_tls = __toESM(require("node:tls"));
-const node_buffer = __toESM(require("node:buffer"));
 
 //#region src/config.ts
 /**
@@ -361,6 +361,33 @@ var OAuth2TokenManager = class {
 
 //#endregion
 //#region src/smtp-connection.ts
+/**
+* Error thrown when a message exceeds the fixed limit advertised through the
+* SMTP SIZE extension.
+*
+* The check happens before `MAIL FROM`, so the SMTP connection remains usable
+* for another message.
+*
+* @since 0.6.0
+*/
+var SmtpMessageSizeError = class extends RangeError {
+	/** The encoded message size in octets. */
+	actualSize;
+	/** The fixed maximum advertised by the SMTP server. */
+	maximumSize;
+	/**
+	* Creates an SMTP message-size error.
+	*
+	* @param actualSize The encoded message size in octets.
+	* @param maximumSize The fixed maximum advertised by the SMTP server.
+	*/
+	constructor(actualSize, maximumSize) {
+		super(`Message size ${actualSize} octets exceeds the server's maximum of ${maximumSize} octets.`);
+		this.name = "SmtpMessageSizeError";
+		this.actualSize = actualSize;
+		this.maximumSize = maximumSize;
+	}
+};
 var SmtpPipelineTerminatedError = class extends Error {
 	responseIndex;
 	response;
@@ -379,6 +406,24 @@ const MAX_COMMAND_LINE_LENGTH = 512;
 /** The length of the CRLF terminator appended to every command. */
 const CRLF_LENGTH = 2;
 /**
+* Finds the RFC 1870 SIZE extension and its optional fixed maximum.
+*
+* A zero maximum and an omitted maximum both mean that no fixed limit is in
+* force.  A malformed parameter does not prevent use of the extension, but it
+* cannot be used as a local limit.
+*
+* @param capabilities The extension lines returned by EHLO.
+* @returns The SIZE capability, or `null` when it was not advertised.
+*/
+function parseSizeCapability(capabilities) {
+	const capability = capabilities.find((value) => /^SIZE(?:[ \t]|$)/i.test(value));
+	if (capability == null) return null;
+	const match = /^SIZE(?:[ \t]+([0-9]+))?[ \t]*$/i.exec(capability);
+	if (match?.[1] == null) return { maximum: null };
+	const maximum = BigInt(match[1]);
+	return { maximum: maximum === 0n ? null : maximum };
+}
+/**
 * How long, in milliseconds, to wait for the graceful `QUIT` to flush during
 * teardown before giving up, so an unresponsive server cannot block shutdown
 * for the full socket timeout.
@@ -815,7 +860,15 @@ var SmtpConnection = class {
 		throw new SmtpAuthError(`${mechanism} authentication failed: ${response.message}`);
 	}
 	async sendMessage(message, signal) {
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>`;
+		signal?.throwIfAborted();
+		const sizeCapability = parseSizeCapability(this.capabilities);
+		let sizeParameter = "";
+		if (sizeCapability != null) {
+			const messageSize = node_buffer.Buffer.byteLength(message.raw, "utf8") + CRLF_LENGTH;
+			if (sizeCapability.maximum != null && BigInt(messageSize) > sizeCapability.maximum) throw new SmtpMessageSizeError(messageSize, sizeCapability.maximum);
+			sizeParameter = ` SIZE=${messageSize}`;
+		}
+		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}`;
 		const recipientCommands = message.envelope.to.map((recipient) => `RCPT TO:<${recipient}>`);
 		const pipelining = this.capabilities.some((capability) => /^PIPELINING(?:\s|$)/i.test(capability));
 		let mailResponse;
@@ -1581,7 +1634,8 @@ var SmtpTransport = class {
 				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
-			if (connection != null) await this.discardConnection(connection);
+			if (connection != null) if (error instanceof SmtpMessageSizeError) await this.returnConnection(connection);
+			else await this.discardConnection(connection);
 			options?.signal?.throwIfAborted();
 			return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 		}
@@ -1651,7 +1705,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					connectionValid = false;
+					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1673,7 +1727,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					connectionValid = false;
+					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1768,6 +1822,17 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpMessageSizeError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "smtp",
+		code: "smtp.message-size-exceeded",
+		category: "rejected",
+		retryable: false,
+		attempts: 1,
+		providerDetails: {
+			actualSize: error.actualSize,
+			maximumSize: error.maximumSize.toString()
+		}
+	});
 	if (error instanceof SmtpResponseError) {
 		const classification = classifySmtpReply(error.code);
 		return (0, __upyo_core.createFailedReceipt)(message, {

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createFailedReceipt } from "@upyo/core";
+import { Buffer } from "node:buffer";
 import { Socket } from "node:net";
 import { TLSSocket, connect } from "node:tls";
-import { Buffer } from "node:buffer";
 
 //#region src/config.ts
 /**
@@ -338,6 +338,33 @@ var OAuth2TokenManager = class {
 
 //#endregion
 //#region src/smtp-connection.ts
+/**
+* Error thrown when a message exceeds the fixed limit advertised through the
+* SMTP SIZE extension.
+*
+* The check happens before `MAIL FROM`, so the SMTP connection remains usable
+* for another message.
+*
+* @since 0.6.0
+*/
+var SmtpMessageSizeError = class extends RangeError {
+	/** The encoded message size in octets. */
+	actualSize;
+	/** The fixed maximum advertised by the SMTP server. */
+	maximumSize;
+	/**
+	* Creates an SMTP message-size error.
+	*
+	* @param actualSize The encoded message size in octets.
+	* @param maximumSize The fixed maximum advertised by the SMTP server.
+	*/
+	constructor(actualSize, maximumSize) {
+		super(`Message size ${actualSize} octets exceeds the server's maximum of ${maximumSize} octets.`);
+		this.name = "SmtpMessageSizeError";
+		this.actualSize = actualSize;
+		this.maximumSize = maximumSize;
+	}
+};
 var SmtpPipelineTerminatedError = class extends Error {
 	responseIndex;
 	response;
@@ -356,6 +383,24 @@ const MAX_COMMAND_LINE_LENGTH = 512;
 /** The length of the CRLF terminator appended to every command. */
 const CRLF_LENGTH = 2;
 /**
+* Finds the RFC 1870 SIZE extension and its optional fixed maximum.
+*
+* A zero maximum and an omitted maximum both mean that no fixed limit is in
+* force.  A malformed parameter does not prevent use of the extension, but it
+* cannot be used as a local limit.
+*
+* @param capabilities The extension lines returned by EHLO.
+* @returns The SIZE capability, or `null` when it was not advertised.
+*/
+function parseSizeCapability(capabilities) {
+	const capability = capabilities.find((value) => /^SIZE(?:[ \t]|$)/i.test(value));
+	if (capability == null) return null;
+	const match = /^SIZE(?:[ \t]+([0-9]+))?[ \t]*$/i.exec(capability);
+	if (match?.[1] == null) return { maximum: null };
+	const maximum = BigInt(match[1]);
+	return { maximum: maximum === 0n ? null : maximum };
+}
+/**
 * How long, in milliseconds, to wait for the graceful `QUIT` to flush during
 * teardown before giving up, so an unresponsive server cannot block shutdown
 * for the full socket timeout.
@@ -792,7 +837,15 @@ var SmtpConnection = class {
 		throw new SmtpAuthError(`${mechanism} authentication failed: ${response.message}`);
 	}
 	async sendMessage(message, signal) {
-		const mailCommand = `MAIL FROM:<${message.envelope.from}>`;
+		signal?.throwIfAborted();
+		const sizeCapability = parseSizeCapability(this.capabilities);
+		let sizeParameter = "";
+		if (sizeCapability != null) {
+			const messageSize = Buffer.byteLength(message.raw, "utf8") + CRLF_LENGTH;
+			if (sizeCapability.maximum != null && BigInt(messageSize) > sizeCapability.maximum) throw new SmtpMessageSizeError(messageSize, sizeCapability.maximum);
+			sizeParameter = ` SIZE=${messageSize}`;
+		}
+		const mailCommand = `MAIL FROM:<${message.envelope.from}>${sizeParameter}`;
 		const recipientCommands = message.envelope.to.map((recipient) => `RCPT TO:<${recipient}>`);
 		const pipelining = this.capabilities.some((capability) => /^PIPELINING(?:\s|$)/i.test(capability));
 		let mailResponse;
@@ -1558,7 +1611,8 @@ var SmtpTransport = class {
 				rejectedRecipients: result.rejectedRecipients
 			};
 		} catch (error) {
-			if (connection != null) await this.discardConnection(connection);
+			if (connection != null) if (error instanceof SmtpMessageSizeError) await this.returnConnection(connection);
+			else await this.discardConnection(connection);
 			options?.signal?.throwIfAborted();
 			return createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 		}
@@ -1628,7 +1682,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					connectionValid = false;
+					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1650,7 +1704,7 @@ var SmtpTransport = class {
 					};
 				} catch (error) {
 					options?.signal?.throwIfAborted();
-					connectionValid = false;
+					if (!(error instanceof SmtpMessageSizeError)) connectionValid = false;
 					yield createSmtpFailure(error instanceof Error ? error.message : String(error), error);
 				}
 			}
@@ -1745,6 +1799,17 @@ var SmtpTransport = class {
 	}
 };
 function createSmtpFailure(message, error) {
+	if (error instanceof SmtpMessageSizeError) return createFailedReceipt(message, {
+		provider: "smtp",
+		code: "smtp.message-size-exceeded",
+		category: "rejected",
+		retryable: false,
+		attempts: 1,
+		providerDetails: {
+			actualSize: error.actualSize,
+			maximumSize: error.maximumSize.toString()
+		}
+	});
 	if (error instanceof SmtpResponseError) {
 		const classification = classifySmtpReply(error.code);
 		return createFailedReceipt(message, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/smtp",
-  "version": "0.6.0-dev.287",
+  "version": "0.6.0-dev.289",
   "description": "SMTP transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,7 +53,7 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.6.0-dev.287+45372d17"
+    "@upyo/core": "0.6.0-dev.289+b1231421"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",