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