An SMTP client and server library for Zig implementing RFC 5321.
1// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>
2// SPDX-License-Identifier: MIT
3
4//! Shared SMTP protocol primitives ([RFC 5321](https://datatracker.ietf.org/doc/html/rfc5321)):
5//! line reading, reply parsing,
6//! command parsing, and message data dot-stuffing. Used by both the client
7//! and server layers, and usable directly for custom protocol handling.
8
9const std = @import("std");
10const Io = std.Io;
11
12pub const crlf = "\r\n";
13
14/// Bytes that may never appear in a command argument.
15///
16/// CR and LF end the command line, so a value carrying either one lets
17/// whatever follows it be read by the server as further SMTP commands — an
18/// address of `a@b>\r\nRCPT TO:<victim@c` turns one recipient into two.
19/// NUL is here because it separates the three fields of an SASL PLAIN
20/// response, where a value carrying one silently shifts the boundary
21/// between authorization identity, username and password.
22pub const forbidden_in_argument = "\r\n\x00";
23
24/// Whether `text` is safe to write into a command line as an argument.
25///
26/// This is a framing check, not address validation: it says that `text`
27/// cannot end the line early, not that it is a well-formed mailbox. The
28/// full RFC 5321 path grammar is deliberately not enforced, because plenty
29/// of addresses in real use do not satisfy it and a client that refused to
30/// carry them would be the wrong tool. Callers building commands from
31/// untrusted input should check here and reject what fails.
32pub fn isSafeArgument(text: []const u8) bool {
33 return std.mem.findAny(u8, text, forbidden_in_argument) == null;
34}
35
36test isSafeArgument {
37 try std.testing.expect(isSafeArgument("alice@example.com"));
38 try std.testing.expect(isSafeArgument("\"odd name\"@example.com"));
39 try std.testing.expect(!isSafeArgument("a@b>\r\nRCPT TO:<victim@c"));
40 try std.testing.expect(!isSafeArgument("a@b\nMAIL FROM:<c@d>"));
41 try std.testing.expect(!isSafeArgument("alice\x00root"));
42}
43
44pub const ReadLineError = error{
45 ReadFailed,
46 EndOfStream,
47 /// The line did not fit in the reader's buffer.
48 LineTooLong,
49};
50
51/// Reads one CRLF- (or bare LF-) terminated line, returning it without the
52/// line ending. The returned slice points into the reader's buffer and is
53/// invalidated by the next read.
54pub fn readLine(reader: *Io.Reader) ReadLineError![]u8 {
55 const line = reader.takeSentinel('\n') catch |err| switch (err) {
56 error.StreamTooLong => return error.LineTooLong,
57 error.ReadFailed, error.EndOfStream => |e| return e,
58 };
59 if (line.len > 0 and line[line.len - 1] == '\r') return line[0 .. line.len - 1];
60 return line;
61}
62
63/// A server reply: a 3-digit code and one or more lines of text.
64pub const Reply = struct {
65 code: u16,
66 /// Text of all reply lines joined with '\n', with codes and separators
67 /// stripped. Points into the buffer passed to `read`.
68 text: []const u8,
69
70 pub const ReadError = ReadLineError || error{
71 InvalidReply,
72 /// The reply text did not fit in the provided buffer.
73 ReplyTooLong,
74 };
75
76 /// Reads one (possibly multiline) reply. The text is copied into `buffer`
77 /// and the returned reply's `text` field points into it.
78 pub fn read(reader: *Io.Reader, buffer: []u8) ReadError!Reply {
79 var text: Io.Writer = .fixed(buffer);
80 var code: ?u16 = null;
81 var first = true;
82 while (true) {
83 const line = try readLine(reader);
84 if (line.len < 3) return error.InvalidReply;
85 const line_code = std.fmt.parseInt(u16, line[0..3], 10) catch
86 return error.InvalidReply;
87 if (line_code < 100 or line_code > 599) return error.InvalidReply;
88 if (code) |prev| {
89 // All lines of a multiline reply must carry the same code.
90 if (prev != line_code) return error.InvalidReply;
91 } else {
92 code = line_code;
93 }
94 var last = true;
95 var line_text: []const u8 = "";
96 if (line.len > 3) {
97 switch (line[3]) {
98 ' ' => {},
99 '-' => last = false,
100 else => return error.InvalidReply,
101 }
102 line_text = line[4..];
103 }
104 if (!first) text.writeByte('\n') catch return error.ReplyTooLong;
105 text.writeAll(line_text) catch return error.ReplyTooLong;
106 first = false;
107 if (last) break;
108 }
109 return .{ .code = code.?, .text = text.buffered() };
110 }
111
112 /// Iterates over the individual text lines of the reply.
113 pub fn lines(r: *const Reply) std.mem.SplitIterator(u8, .scalar) {
114 return std.mem.splitScalar(u8, r.text, '\n');
115 }
116
117 // Reply classes per RFC 5321 §4.2.1
118 // (https://datatracker.ietf.org/doc/html/rfc5321#section-4.2.1).
119 pub fn isPositiveCompletion(r: Reply) bool {
120 return r.code >= 200 and r.code < 300;
121 }
122 pub fn isPositiveIntermediate(r: Reply) bool {
123 return r.code >= 300 and r.code < 400;
124 }
125 pub fn isTransientFailure(r: Reply) bool {
126 return r.code >= 400 and r.code < 500;
127 }
128 pub fn isPermanentFailure(r: Reply) bool {
129 return r.code >= 500 and r.code < 600;
130 }
131
132 test read {
133 var reader: Io.Reader = .fixed("250-first\r\n250 second\r\n");
134 var buffer: [64]u8 = undefined;
135 const reply = try read(&reader, &buffer);
136 try std.testing.expectEqual(@as(u16, 250), reply.code);
137 try std.testing.expectEqualStrings("first\nsecond", reply.text);
138 }
139
140 test lines {
141 const reply: Reply = .{ .code = 250, .text = "one\ntwo" };
142 var it = reply.lines();
143 try std.testing.expectEqualStrings("one", it.next().?);
144 try std.testing.expectEqualStrings("two", it.next().?);
145 try std.testing.expectEqual(@as(?[]const u8, null), it.next());
146 }
147
148 test isPositiveCompletion {
149 try std.testing.expect((Reply{ .code = 250, .text = "" }).isPositiveCompletion());
150 try std.testing.expect(!(Reply{ .code = 354, .text = "" }).isPositiveCompletion());
151 }
152
153 test isPositiveIntermediate {
154 try std.testing.expect((Reply{ .code = 354, .text = "" }).isPositiveIntermediate());
155 }
156
157 test isTransientFailure {
158 try std.testing.expect((Reply{ .code = 451, .text = "" }).isTransientFailure());
159 }
160
161 test isPermanentFailure {
162 try std.testing.expect((Reply{ .code = 550, .text = "" }).isPermanentFailure());
163 }
164};
165
166/// A parsed client command, as seen by a server.
167pub const Command = union(enum) {
168 helo: []const u8,
169 ehlo: []const u8,
170 /// LHLO, the LMTP greeting
171 /// ([RFC 2033](https://datatracker.ietf.org/doc/html/rfc2033)), which
172 /// has the same semantics as EHLO. An LMTP server takes this one and
173 /// refuses HELO and EHLO; an SMTP server does the reverse.
174 lhlo: []const u8,
175 /// MAIL FROM. An empty path is the null reverse-path (`MAIL FROM:<>`).
176 mail: PathArgs,
177 /// RCPT TO.
178 rcpt: PathArgs,
179 data,
180 rset,
181 noop,
182 quit,
183 vrfy: []const u8,
184 help,
185 starttls,
186 /// AUTH ([RFC 4954](https://datatracker.ietf.org/doc/html/rfc4954)).
187 auth: AuthArgs,
188 /// BDAT, the CHUNKING extension
189 /// ([RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030)). The
190 /// command line is followed by exactly `size` raw octets.
191 bdat: BdatArgs,
192 /// Unrecognized command verb; the payload is the full line.
193 unknown: []const u8,
194
195 pub const BdatArgs = struct {
196 size: u64,
197 /// True for the final chunk of the message ("BDAT n LAST").
198 last: bool = false,
199 };
200
201 pub const AuthArgs = struct {
202 mechanism: []const u8,
203 /// Raw base64 initial response, if the client sent one ("=" denotes
204 /// an empty initial response).
205 initial: []const u8 = "",
206 };
207
208 pub const PathArgs = struct {
209 /// The mailbox, with angle brackets and any obsolete source route
210 /// stripped.
211 path: []const u8,
212 /// Raw ESMTP parameters that followed the path, e.g. "SIZE=1024".
213 params: []const u8 = "",
214
215 pub fn paramIterator(args: PathArgs) ParamIterator {
216 return .init(args.params);
217 }
218
219 test paramIterator {
220 const args: PathArgs = .{ .path = "a@example.com", .params = "SIZE=7" };
221 var it = args.paramIterator();
222 try std.testing.expectEqualStrings("SIZE", it.next().?.keyword);
223 }
224 };
225
226 pub const ParseError = error{Syntax};
227
228 /// Parses one command line (without its line ending). Returned slices
229 /// point into `line`.
230 pub fn parse(line: []const u8) ParseError!Command {
231 const trimmed = std.mem.trim(u8, line, " \t");
232 const verb_end = std.mem.indexOfAny(u8, trimmed, " \t") orelse trimmed.len;
233 const verb = trimmed[0..verb_end];
234 const rest = std.mem.trimStart(u8, trimmed[verb_end..], " \t");
235
236 if (ieql(verb, "HELO")) {
237 if (rest.len == 0) return error.Syntax;
238 return .{ .helo = rest };
239 }
240 if (ieql(verb, "EHLO")) {
241 if (rest.len == 0) return error.Syntax;
242 return .{ .ehlo = rest };
243 }
244 if (ieql(verb, "LHLO")) {
245 if (rest.len == 0) return error.Syntax;
246 return .{ .lhlo = rest };
247 }
248 if (ieql(verb, "MAIL")) return .{ .mail = try parsePathArgs(rest, "FROM:") };
249 if (ieql(verb, "RCPT")) return .{ .rcpt = try parsePathArgs(rest, "TO:") };
250 if (ieql(verb, "DATA")) return .data;
251 if (ieql(verb, "RSET")) return .rset;
252 if (ieql(verb, "NOOP")) return .noop;
253 if (ieql(verb, "QUIT")) return .quit;
254 if (ieql(verb, "VRFY")) return .{ .vrfy = rest };
255 if (ieql(verb, "HELP")) return .help;
256 if (ieql(verb, "STARTTLS")) return .starttls;
257 if (ieql(verb, "BDAT")) {
258 var it = std.mem.tokenizeAny(u8, rest, " \t");
259 const size_token = it.next() orelse return error.Syntax;
260 const size = std.fmt.parseInt(u64, size_token, 10) catch return error.Syntax;
261 var last = false;
262 if (it.next()) |token| {
263 if (!ieql(token, "LAST")) return error.Syntax;
264 last = true;
265 }
266 if (it.next() != null) return error.Syntax;
267 return .{ .bdat = .{ .size = size, .last = last } };
268 }
269 if (ieql(verb, "AUTH")) {
270 const mech_end = std.mem.indexOfAny(u8, rest, " \t") orelse rest.len;
271 if (mech_end == 0) return error.Syntax;
272 return .{ .auth = .{
273 .mechanism = rest[0..mech_end],
274 .initial = std.mem.trimStart(u8, rest[mech_end..], " \t"),
275 } };
276 }
277 return .{ .unknown = line };
278 }
279
280 fn parsePathArgs(rest: []const u8, comptime keyword: []const u8) ParseError!PathArgs {
281 if (rest.len < keyword.len or !ieql(rest[0..keyword.len], keyword))
282 return error.Syntax;
283 const after = std.mem.trimStart(u8, rest[keyword.len..], " \t");
284 if (after.len == 0 or after[0] != '<') {
285 // Lenient: accept a bare address ending at whitespace.
286 const end = std.mem.indexOfAny(u8, after, " \t") orelse after.len;
287 if (end == 0) return error.Syntax;
288 return .{
289 .path = after[0..end],
290 .params = std.mem.trimStart(u8, after[end..], " \t"),
291 };
292 }
293 // The closing bracket must be found outside any quoted local-part:
294 // <"a>b"@example.com> is legal (RFC 5321 quoted-string, with
295 // backslash escapes).
296 const close = close: {
297 var in_quotes = false;
298 var i: usize = 1;
299 while (i < after.len) : (i += 1) {
300 const byte = after[i];
301 if (in_quotes) {
302 if (byte == '\\') {
303 i += 1;
304 } else if (byte == '"') {
305 in_quotes = false;
306 }
307 } else if (byte == '"') {
308 in_quotes = true;
309 } else if (byte == '>') {
310 break :close i;
311 }
312 }
313 return error.Syntax;
314 };
315 var path = after[1..close];
316 // Strip an obsolete source route: <@relay1,@relay2:user@host>.
317 if (path.len > 0 and path[0] == '@') {
318 const colon = std.mem.indexOfScalar(u8, path, ':') orelse return error.Syntax;
319 path = path[colon + 1 ..];
320 }
321 return .{
322 .path = path,
323 .params = std.mem.trimStart(u8, after[close + 1 ..], " \t"),
324 };
325 }
326
327 fn ieql(a: []const u8, b: []const u8) bool {
328 return std.ascii.eqlIgnoreCase(a, b);
329 }
330
331 test parse {
332 const command = try parse("RCPT TO:<bob@example.net>");
333 try std.testing.expectEqualStrings("bob@example.net", command.rcpt.path);
334 try std.testing.expectError(error.Syntax, parse("MAIL <missing-keyword>"));
335 }
336};
337
338/// The `RET` parameter of an extended MAIL command
339/// ([RFC 3461 §4.3](https://datatracker.ietf.org/doc/html/rfc3461#section-4.3)):
340/// how much of the message a failed DSN should carry back. Absent, the
341/// choice is the reporting MTA's.
342/// RFC 3461 §4.4 caps the `ENVID` parameter value at 100 characters, which
343/// is a limit on the xtext-encoded form and not on what went into it.
344pub const max_envid_len = 100;
345
346pub const Ret = enum {
347 /// Return the entire message.
348 full,
349 /// Return the headers only.
350 hdrs,
351
352 pub const ParseError = error{Syntax};
353
354 pub fn parse(value: []const u8) ParseError!Ret {
355 if (std.ascii.eqlIgnoreCase(value, "FULL")) return .full;
356 if (std.ascii.eqlIgnoreCase(value, "HDRS")) return .hdrs;
357 return error.Syntax;
358 }
359
360 /// Writes the value as it appears on the wire.
361 pub fn format(r: Ret, writer: *Io.Writer) Io.Writer.Error!void {
362 try writer.writeAll(switch (r) {
363 .full => "FULL",
364 .hdrs => "HDRS",
365 });
366 }
367
368 test parse {
369 try std.testing.expectEqual(Ret.hdrs, try parse("hdrs"));
370 try std.testing.expectError(error.Syntax, parse("PARTIAL"));
371 }
372};
373
374/// The `NOTIFY` parameter of an extended RCPT command
375/// ([RFC 3461 §4.1](https://datatracker.ietf.org/doc/html/rfc3461#section-4.1)):
376/// the conditions under which the sender wants to hear about this
377/// recipient. Absent, RFC 3461 lets a server read it as either
378/// `FAILURE` or `FAILURE,DELAY` — which is why "not specified" is an
379/// absent `?Notify` here and not a value of it.
380pub const Notify = union(enum) {
381 /// `NOTIFY=NEVER`: no DSN for this recipient under any circumstance.
382 /// RFC 3461 requires the keyword to appear on its own, and parsing
383 /// rejects it in a list.
384 never,
385 /// One or more of `SUCCESS`, `FAILURE` and `DELAY`.
386 on: Conditions,
387
388 pub const Conditions = struct {
389 success: bool = false,
390 failure: bool = false,
391 delay: bool = false,
392 };
393
394 pub const ParseError = error{Syntax};
395
396 pub fn parse(value: []const u8) ParseError!Notify {
397 if (std.ascii.eqlIgnoreCase(value, "NEVER")) return .never;
398 var conditions: Conditions = .{};
399 var it = std.mem.splitScalar(u8, value, ',');
400 var any = false;
401 while (it.next()) |keyword| {
402 if (std.ascii.eqlIgnoreCase(keyword, "SUCCESS")) {
403 conditions.success = true;
404 } else if (std.ascii.eqlIgnoreCase(keyword, "FAILURE")) {
405 conditions.failure = true;
406 } else if (std.ascii.eqlIgnoreCase(keyword, "DELAY")) {
407 conditions.delay = true;
408 } else return error.Syntax; // Including NEVER: it may not be listed.
409 any = true;
410 }
411 if (!any) return error.Syntax;
412 return .{ .on = conditions };
413 }
414
415 /// Writes the value as it appears on the wire.
416 pub fn format(n: Notify, writer: *Io.Writer) Io.Writer.Error!void {
417 switch (n) {
418 .never => try writer.writeAll("NEVER"),
419 .on => |conditions| {
420 var written = false;
421 inline for (.{
422 .{ conditions.success, "SUCCESS" },
423 .{ conditions.failure, "FAILURE" },
424 .{ conditions.delay, "DELAY" },
425 }) |pair| {
426 if (pair[0]) {
427 if (written) try writer.writeByte(',');
428 try writer.writeAll(pair[1]);
429 written = true;
430 }
431 }
432 // An empty condition set has no legal spelling; NEVER is
433 // what "tell me nothing" is written as.
434 if (!written) try writer.writeAll("NEVER");
435 },
436 }
437 }
438
439 test parse {
440 try std.testing.expectEqual(Notify.never, try parse("NEVER"));
441 const both = try parse("SUCCESS,delay");
442 try std.testing.expect(both.on.success and both.on.delay and !both.on.failure);
443 try std.testing.expectError(error.Syntax, parse("NEVER,SUCCESS"));
444 try std.testing.expectError(error.Syntax, parse(""));
445 try std.testing.expectError(error.Syntax, parse("SUCCESS,MAYBE"));
446 }
447};
448
449/// The `ORCPT` parameter of an extended RCPT command
450/// ([RFC 3461 §4.2](https://datatracker.ietf.org/doc/html/rfc3461#section-4.2)):
451/// the address the message was originally addressed to, carried unchanged
452/// through aliasing and forwarding so that a DSN can name what the sender
453/// actually wrote.
454pub const Orcpt = struct {
455 /// The address type, an atom — `rfc822` in all but the unusual cases.
456 addr_type: []const u8,
457 /// The original recipient, xtext-decoded.
458 address: []const u8,
459
460 /// RFC 3461 §4.2 caps the whole parameter value at 500 characters.
461 pub const max_len = 500;
462
463 pub const ParseError = error{Syntax};
464
465 /// Parses `addr-type ";" xtext`, decoding the address into `buffer`.
466 /// The returned `addr_type` points into `value` and `address` points
467 /// into `buffer`, so the two have different lifetimes; a caller keeping
468 /// the result past either one copies both.
469 pub fn parse(buffer: []u8, value: []const u8) ParseError!Orcpt {
470 const semicolon = std.mem.findScalar(u8, value, ';') orelse return error.Syntax;
471 const addr_type = value[0..semicolon];
472 if (addr_type.len == 0) return error.Syntax;
473 for (addr_type) |byte| if (!isAtomByte(byte)) return error.Syntax;
474 return .{
475 .addr_type = addr_type,
476 .address = xtextDecode(buffer, value[semicolon + 1 ..]) catch return error.Syntax,
477 };
478 }
479
480 /// Writes the parameter value as it appears on the wire, xtext-encoding
481 /// the address.
482 pub fn format(o: Orcpt, writer: *Io.Writer) Io.Writer.Error!void {
483 try writer.writeAll(o.addr_type);
484 try writer.writeByte(';');
485 try writeXtext(writer, o.address);
486 }
487
488 /// RFC 5321 `atom` less the specials, which is what an addr-type may be.
489 fn isAtomByte(byte: u8) bool {
490 return switch (byte) {
491 'A'...'Z', 'a'...'z', '0'...'9' => true,
492 '!', '#', '$', '%', '&', '\'', '*', '+', '-', '/', '=', '?' => true,
493 '^', '_', '`', '{', '|', '}', '~' => true,
494 else => false,
495 };
496 }
497
498 test parse {
499 var buffer: [64]u8 = undefined;
500 const orcpt = try parse(&buffer, "rfc822;bob+2Bx@example.net");
501 try std.testing.expectEqualStrings("rfc822", orcpt.addr_type);
502 try std.testing.expectEqualStrings("bob+x@example.net", orcpt.address);
503 try std.testing.expectError(error.Syntax, parse(&buffer, "bob@example.net"));
504 try std.testing.expectError(error.Syntax, parse(&buffer, ";bob@example.net"));
505 }
506};
507
508/// Whether `byte` may appear in an xtext unencoded
509/// ([RFC 3461 §4](https://datatracker.ietf.org/doc/html/rfc3461#section-4)):
510/// printable US-ASCII other than `+`, which introduces an escape, and `=`,
511/// which separates an ESMTP keyword from its value.
512pub fn isXchar(byte: u8) bool {
513 return byte >= '!' and byte <= '~' and byte != '+' and byte != '=';
514}
515
516/// Writes `text` xtext-encoded: anything that is not an `xchar` becomes
517/// `+` and two upper-case hex digits. Every byte therefore survives,
518/// including the ones that would otherwise end the command line, so an
519/// xtext-encoded parameter is safe to write from untrusted input.
520///
521/// RFC 3461 asks that the value before encoding be printable US-ASCII.
522/// That is the caller's to observe; encoding anything else here produces
523/// valid xtext regardless rather than a corrupt command.
524pub fn writeXtext(writer: *Io.Writer, text: []const u8) Io.Writer.Error!void {
525 for (text) |byte| {
526 if (isXchar(byte)) {
527 try writer.writeByte(byte);
528 } else {
529 try writer.print("+{X:0>2}", .{byte});
530 }
531 }
532}
533
534/// The length `writeXtext` will produce for `text`, for checking a value
535/// against the length limits RFC 3461 puts on the encoded form.
536pub fn xtextEncodedLen(text: []const u8) usize {
537 var len: usize = 0;
538 for (text) |byte| len += if (isXchar(byte)) 1 else 3;
539 return len;
540}
541
542pub const XtextError = error{
543 /// Not valid xtext: a `+` not followed by two hex digits, or a raw byte
544 /// that the encoder was required to escape.
545 BadXtext,
546 NoSpaceLeft,
547};
548
549/// Decodes xtext into `buffer`, returning the decoded bytes. Decoding is
550/// strict: a byte an encoder was obliged to escape is rejected rather than
551/// passed through, since accepting it would let two different encodings
552/// mean the same thing.
553pub fn xtextDecode(buffer: []u8, text: []const u8) XtextError![]u8 {
554 var out: usize = 0;
555 var i: usize = 0;
556 while (i < text.len) {
557 const byte = text[i];
558 if (byte == '+') {
559 if (i + 2 >= text.len) return error.BadXtext;
560 const hex = text[i + 1 ..][0..2];
561 // Checked before parsing because `parseInt` also accepts a sign
562 // and underscore separators, which hex digits are not. Lower
563 // case is accepted on the way in even though RFC 3461 requires
564 // upper case on the way out.
565 for (hex) |digit| if (!std.ascii.isHex(digit)) return error.BadXtext;
566 const value = std.fmt.parseInt(u8, hex, 16) catch return error.BadXtext;
567 if (out >= buffer.len) return error.NoSpaceLeft;
568 buffer[out] = value;
569 out += 1;
570 i += 3;
571 } else {
572 if (!isXchar(byte)) return error.BadXtext;
573 if (out >= buffer.len) return error.NoSpaceLeft;
574 buffer[out] = byte;
575 out += 1;
576 i += 1;
577 }
578 }
579 return buffer[0..out];
580}
581
582test xtextDecode {
583 var buffer: [64]u8 = undefined;
584 try std.testing.expectEqualStrings(
585 "a+b=c",
586 try xtextDecode(&buffer, "a+2Bb+3Dc"),
587 );
588 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a+2"));
589 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a+ZZb"));
590 // A raw '=' or ' ' is what the encoder had to escape.
591 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a=b"));
592 try std.testing.expectError(error.BadXtext, xtextDecode(&buffer, "a b"));
593}
594
595test writeXtext {
596 var out_buf: [64]u8 = undefined;
597 var writer: Io.Writer = .fixed(&out_buf);
598 try writeXtext(&writer, "id+1=2 \r\n");
599 try std.testing.expectEqualStrings("id+2B1+3D2+20+0D+0A", writer.buffered());
600 try std.testing.expectEqual(writer.buffered().len, xtextEncodedLen("id+1=2 \r\n"));
601
602 // Every byte survives the round trip.
603 var raw: [256]u8 = undefined;
604 for (&raw, 0..) |*byte, i| byte.* = @intCast(i);
605 var round_buf: [1024]u8 = undefined;
606 var round: Io.Writer = .fixed(&round_buf);
607 try writeXtext(&round, &raw);
608 var decoded_buf: [256]u8 = undefined;
609 try std.testing.expectEqualSlices(u8, &raw, try xtextDecode(&decoded_buf, round.buffered()));
610}
611
612/// Iterates the ESMTP parameters of a MAIL or RCPT command
613/// ([RFC 5321 §4.1.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.2)),
614/// e.g. "SIZE=1024 BODY=8BITMIME".
615pub const ParamIterator = struct {
616 rest: []const u8,
617
618 pub const Param = struct {
619 keyword: []const u8,
620 /// Empty when the parameter carries no value.
621 value: []const u8 = "",
622 };
623
624 pub fn init(params: []const u8) ParamIterator {
625 return .{ .rest = params };
626 }
627
628 pub fn next(it: *ParamIterator) ?Param {
629 it.rest = std.mem.trimStart(u8, it.rest, " \t");
630 if (it.rest.len == 0) return null;
631 const end = std.mem.indexOfAny(u8, it.rest, " \t") orelse it.rest.len;
632 const token = it.rest[0..end];
633 it.rest = it.rest[end..];
634 if (std.mem.indexOfScalar(u8, token, '=')) |eq| {
635 return .{ .keyword = token[0..eq], .value = token[eq + 1 ..] };
636 }
637 return .{ .keyword = token };
638 }
639
640 test init {
641 var it: ParamIterator = .init("SIZE=42");
642 try std.testing.expectEqualStrings("SIZE", it.next().?.keyword);
643 }
644
645 test next {
646 var it: ParamIterator = .init("BODY=8BITMIME CUSTOM");
647 const body = it.next().?;
648 try std.testing.expectEqualStrings("BODY", body.keyword);
649 try std.testing.expectEqualStrings("8BITMIME", body.value);
650 const custom = it.next().?;
651 try std.testing.expectEqualStrings("CUSTOM", custom.keyword);
652 try std.testing.expectEqualStrings("", custom.value);
653 try std.testing.expectEqual(@as(?Param, null), it.next());
654 }
655};
656
657/// Writes `data` as SMTP message content: line endings are normalized to CRLF
658/// and lines beginning with '.' are dot-stuffed
659/// ([RFC 5321 §4.5.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.5.2)). Does not
660/// write the terminating ".\r\n".
661pub fn writeStuffed(writer: *Io.Writer, data: []const u8) Io.Writer.Error!void {
662 var rest = data;
663 while (rest.len > 0) {
664 var line: []const u8 = undefined;
665 if (std.mem.indexOfScalar(u8, rest, '\n')) |i| {
666 line = rest[0..i];
667 rest = rest[i + 1 ..];
668 } else {
669 line = rest;
670 rest = rest[rest.len..];
671 }
672 if (line.len > 0 and line[line.len - 1] == '\r') line = line[0 .. line.len - 1];
673 if (line.len > 0 and line[0] == '.') try writer.writeByte('.');
674 try writer.writeAll(line);
675 try writer.writeAll(crlf);
676 }
677}
678
679test readLine {
680 var reader: Io.Reader = .fixed("first\r\nsecond\nthird\r\n");
681 try std.testing.expectEqualStrings("first", try readLine(&reader));
682 try std.testing.expectEqualStrings("second", try readLine(&reader));
683 try std.testing.expectEqualStrings("third", try readLine(&reader));
684 try std.testing.expectError(error.EndOfStream, readLine(&reader));
685}
686
687test Reply {
688 var reader: Io.Reader = .fixed("250 2.0.0 Ok\r\n");
689 var buf: [128]u8 = undefined;
690 const reply = try Reply.read(&reader, &buf);
691 try std.testing.expectEqual(@as(u16, 250), reply.code);
692 try std.testing.expectEqualStrings("2.0.0 Ok", reply.text);
693 try std.testing.expect(reply.isPositiveCompletion());
694}
695
696test "Reply.read multiline" {
697 var reader: Io.Reader = .fixed("250-mx.example.com\r\n250-PIPELINING\r\n250 SIZE 1000\r\n");
698 var buf: [128]u8 = undefined;
699 const reply = try Reply.read(&reader, &buf);
700 try std.testing.expectEqual(@as(u16, 250), reply.code);
701 try std.testing.expectEqualStrings("mx.example.com\nPIPELINING\nSIZE 1000", reply.text);
702 var it = reply.lines();
703 try std.testing.expectEqualStrings("mx.example.com", it.next().?);
704 try std.testing.expectEqualStrings("PIPELINING", it.next().?);
705 try std.testing.expectEqualStrings("SIZE 1000", it.next().?);
706 try std.testing.expectEqual(@as(?[]const u8, null), it.next());
707}
708
709test "Reply.read rejects malformed replies" {
710 var buf: [128]u8 = undefined;
711 {
712 var reader: Io.Reader = .fixed("2x0 hello\r\n");
713 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
714 }
715 {
716 var reader: Io.Reader = .fixed("250-one\r\n251 two\r\n");
717 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
718 }
719 {
720 var reader: Io.Reader = .fixed("42\r\n");
721 try std.testing.expectError(error.InvalidReply, Reply.read(&reader, &buf));
722 }
723}
724
725test Command {
726 {
727 const cmd = try Command.parse("EHLO client.example.com");
728 try std.testing.expectEqualStrings("client.example.com", cmd.ehlo);
729 }
730 {
731 const cmd = try Command.parse("mail from:<alice@example.com> SIZE=1024");
732 try std.testing.expectEqualStrings("alice@example.com", cmd.mail.path);
733 try std.testing.expectEqualStrings("SIZE=1024", cmd.mail.params);
734 }
735 {
736 // Null reverse-path and a space after the colon.
737 const cmd = try Command.parse("MAIL FROM: <>");
738 try std.testing.expectEqualStrings("", cmd.mail.path);
739 }
740 {
741 // Obsolete source route is stripped.
742 const cmd = try Command.parse("RCPT TO:<@relay.example:bob@example.net>");
743 try std.testing.expectEqualStrings("bob@example.net", cmd.rcpt.path);
744 }
745 {
746 // Quoted local-parts (from postfix's address corpora) may contain
747 // spaces and even '>' or escaped quotes.
748 const cmd = try Command.parse("MAIL FROM:<\"foo bar\"@example.com> SIZE=9");
749 try std.testing.expectEqualStrings("\"foo bar\"@example.com", cmd.mail.path);
750 try std.testing.expectEqualStrings("SIZE=9", cmd.mail.params);
751 }
752 {
753 const cmd = try Command.parse("RCPT TO:<\"a>b\"@example.com>");
754 try std.testing.expectEqualStrings("\"a>b\"@example.com", cmd.rcpt.path);
755 }
756 {
757 const cmd = try Command.parse("RCPT TO:<\"a\\\">b\"@example.com>");
758 try std.testing.expectEqualStrings("\"a\\\">b\"@example.com", cmd.rcpt.path);
759 }
760 try std.testing.expectError(error.Syntax, Command.parse("MAIL FROM:<\"unterminated@example.com>"));
761 {
762 const cmd = try Command.parse("QUIT");
763 try std.testing.expectEqual(Command.quit, cmd);
764 }
765 {
766 const cmd = try Command.parse("AUTH PLAIN AHVzZXIAcGFzcw==");
767 try std.testing.expectEqualStrings("PLAIN", cmd.auth.mechanism);
768 try std.testing.expectEqualStrings("AHVzZXIAcGFzcw==", cmd.auth.initial);
769 }
770 {
771 const cmd = try Command.parse("auth login");
772 try std.testing.expectEqualStrings("login", cmd.auth.mechanism);
773 try std.testing.expectEqualStrings("", cmd.auth.initial);
774 }
775 {
776 const cmd = try Command.parse("MADE UP");
777 try std.testing.expectEqualStrings("MADE UP", cmd.unknown);
778 }
779 {
780 const cmd = try Command.parse("BDAT 1024");
781 try std.testing.expectEqual(@as(u64, 1024), cmd.bdat.size);
782 try std.testing.expect(!cmd.bdat.last);
783 }
784 {
785 const cmd = try Command.parse("bdat 0 last");
786 try std.testing.expectEqual(@as(u64, 0), cmd.bdat.size);
787 try std.testing.expect(cmd.bdat.last);
788 }
789 try std.testing.expectError(error.Syntax, Command.parse("BDAT"));
790 try std.testing.expectError(error.Syntax, Command.parse("BDAT nan"));
791 try std.testing.expectError(error.Syntax, Command.parse("BDAT 5 FIRST"));
792 try std.testing.expectError(error.Syntax, Command.parse("BDAT 5 LAST extra"));
793 try std.testing.expectError(error.Syntax, Command.parse("AUTH"));
794 try std.testing.expectError(error.Syntax, Command.parse("MAIL TO:<a@b>"));
795 try std.testing.expectError(error.Syntax, Command.parse("RCPT TO:"));
796 try std.testing.expectError(error.Syntax, Command.parse("HELO"));
797}
798
799test writeStuffed {
800 var buf: [256]u8 = undefined;
801 {
802 var w: Io.Writer = .fixed(&buf);
803 try writeStuffed(&w, "line one\r\n.starts with dot\r\n");
804 try std.testing.expectEqualStrings("line one\r\n..starts with dot\r\n", w.buffered());
805 }
806 {
807 // LF-only input is normalized, missing final newline is added.
808 var w: Io.Writer = .fixed(&buf);
809 try writeStuffed(&w, "a\nb");
810 try std.testing.expectEqualStrings("a\r\nb\r\n", w.buffered());
811 }
812 {
813 // A lone "." line must not become a terminator.
814 var w: Io.Writer = .fixed(&buf);
815 try writeStuffed(&w, ".\n");
816 try std.testing.expectEqualStrings("..\r\n", w.buffered());
817 }
818 {
819 var w: Io.Writer = .fixed(&buf);
820 try writeStuffed(&w, "");
821 try std.testing.expectEqualStrings("", w.buffered());
822 }
823}
824
825test "fuzz Command.parse" {
826 try std.testing.fuzz({}, fuzzCommandParse, .{});
827}
828
829fn fuzzCommandParse(context: void, smith: *std.testing.Smith) !void {
830 _ = context;
831 var line_buf: [512]u8 = undefined;
832 const line = line_buf[0..smith.value(u9)];
833 smith.bytes(line);
834
835 const command = Command.parse(line) catch return;
836 // Payload slices must always lie within the parsed line.
837 switch (command) {
838 .helo, .ehlo, .lhlo, .vrfy, .unknown => |payload| try std.testing.expect(payload.len <= line.len),
839 .mail, .rcpt => |args| {
840 try std.testing.expect(args.path.len <= line.len);
841 try std.testing.expect(args.params.len <= line.len);
842 },
843 .auth => |args| {
844 try std.testing.expect(args.mechanism.len <= line.len);
845 try std.testing.expect(args.initial.len <= line.len);
846 },
847 .data, .rset, .noop, .quit, .help, .starttls, .bdat => {},
848 }
849}
850
851test "fuzz Reply.read" {
852 try std.testing.fuzz({}, fuzzReplyRead, .{});
853}
854
855fn fuzzReplyRead(context: void, smith: *std.testing.Smith) !void {
856 _ = context;
857 var input_buf: [1024]u8 = undefined;
858 const input = input_buf[0..smith.value(u10)];
859 smith.bytes(input);
860
861 var reader: Io.Reader = .fixed(input);
862 var text_buf: [128]u8 = undefined;
863 // Each successful read consumes at least one line, so this terminates.
864 while (true) {
865 const reply = Reply.read(&reader, &text_buf) catch break;
866 try std.testing.expect(reply.code >= 100 and reply.code <= 599);
867 }
868}
869
870test ParamIterator {
871 const command = try Command.parse("MAIL FROM:<a@example.com> SIZE=1024 BODY=8BITMIME FLAG");
872 var it = command.mail.paramIterator();
873
874 const size = it.next().?;
875 try std.testing.expectEqualStrings("SIZE", size.keyword);
876 try std.testing.expectEqualStrings("1024", size.value);
877
878 const body = it.next().?;
879 try std.testing.expectEqualStrings("BODY", body.keyword);
880 try std.testing.expectEqualStrings("8BITMIME", body.value);
881
882 const flag = it.next().?;
883 try std.testing.expectEqualStrings("FLAG", flag.keyword);
884 try std.testing.expectEqualStrings("", flag.value);
885
886 try std.testing.expectEqual(@as(?ParamIterator.Param, null), it.next());
887}
888
889test crlf {
890 try std.testing.expectEqualStrings("\r\n", crlf);
891}
892
893test "RFC 5321 mailbox forms from the is_email corpus round-trip" {
894 // Parses Dominic Sayers' is_email test suite (tests.xml and
895 // tests-original.xml, embedded from the lazy `isemail` dependency by
896 // `zig build test -Disemail-corpus`) and checks that every address
897 // valid at the RFC 5321 layer passes through the lenient path parser
898 // byte-for-byte, params intact.
899 if (comptime @import("build_options").isemail_corpus) {
900 const corpus = @embedFile("isemail_tests_xml") ++ "\n" ++
901 @embedFile("isemail_tests_original_xml");
902 var checked: usize = 0;
903 var rest: []const u8 = corpus;
904 while (std.mem.indexOf(u8, rest, "<test ")) |start_index| {
905 const end_index = std.mem.indexOfPos(u8, rest, start_index, "</test>") orelse break;
906 const block = rest[start_index..end_index];
907 rest = rest[end_index + "</test>".len ..];
908
909 const category = xmlElementText(block, "category") orelse continue;
910 if (!std.mem.eql(u8, category, "ISEMAIL_VALID_CATEGORY") and
911 !std.mem.eql(u8, category, "ISEMAIL_RFC5321")) continue;
912 const raw = xmlElementText(block, "address") orelse continue;
913 var address_buf: [256]u8 = undefined;
914 const address = try xmlUnescape(&address_buf, raw);
915
916 var line_buf: [300]u8 = undefined;
917 const line = try std.fmt.bufPrint(&line_buf, "MAIL FROM:<{s}> SIZE=1", .{address});
918 const command = try Command.parse(line);
919 try std.testing.expectEqualStrings(address, command.mail.path);
920 try std.testing.expectEqualStrings("SIZE=1", command.mail.params);
921 checked += 1;
922 }
923 // The two files carry 125 RFC 5321-valid cases between them; fail
924 // loudly if the extraction ever silently rots.
925 try std.testing.expect(checked >= 120);
926 } else return error.SkipZigTest;
927}
928
929fn xmlElementText(block: []const u8, comptime tag: []const u8) ?[]const u8 {
930 const open = "<" ++ tag ++ ">";
931 const close = "</" ++ tag ++ ">";
932 const start = (std.mem.indexOf(u8, block, open) orelse return null) + open.len;
933 const end = std.mem.indexOfPos(u8, block, start, close) orelse return null;
934 return block[start..end];
935}
936
937fn xmlUnescape(buffer: []u8, input: []const u8) ![]const u8 {
938 var out: usize = 0;
939 var i: usize = 0;
940 while (i < input.len) {
941 if (input[i] != '&') {
942 buffer[out] = input[i];
943 out += 1;
944 i += 1;
945 continue;
946 }
947 const semi = std.mem.indexOfScalarPos(u8, input, i, ';') orelse return error.BadEntity;
948 const entity = input[i + 1 .. semi];
949 i = semi + 1;
950 if (std.mem.eql(u8, entity, "amp")) {
951 buffer[out] = '&';
952 out += 1;
953 } else if (std.mem.eql(u8, entity, "lt")) {
954 buffer[out] = '<';
955 out += 1;
956 } else if (std.mem.eql(u8, entity, "gt")) {
957 buffer[out] = '>';
958 out += 1;
959 } else if (std.mem.eql(u8, entity, "quot")) {
960 buffer[out] = '"';
961 out += 1;
962 } else if (std.mem.eql(u8, entity, "apos")) {
963 buffer[out] = '\'';
964 out += 1;
965 } else if (std.mem.startsWith(u8, entity, "#x") or std.mem.startsWith(u8, entity, "#X")) {
966 const codepoint = try std.fmt.parseInt(u21, entity[2..], 16);
967 out += try std.unicode.utf8Encode(codepoint, buffer[out..]);
968 } else if (std.mem.startsWith(u8, entity, "#")) {
969 const codepoint = try std.fmt.parseInt(u21, entity[1..], 10);
970 out += try std.unicode.utf8Encode(codepoint, buffer[out..]);
971 } else return error.BadEntity;
972 }
973 return buffer[0..out];
974}