Validate response text, command tags and namespace delimiters (#866)

* Reject invalid response text when writing

`.no(.init(text: "No mailbox x\r\n* BYE pwned"))` was written verbatim,
injecting an untagged response; likewise tagged, BYE, PREAUTH and
continuation responses.

RFC 9051: `text = 1*(TEXT-CHAR / UTF8-2 / UTF8-3 / UTF8-4)`. `writeText`
now asserts no NUL, CR or LF. Empty stays valid. The parser now accepts
UTF-8 text.

* Add Command.Tag for command and response tags

`TaggedCommand(tag: "A1 NOOP\r\nA2 DELETE INBOX\r\nA3", command: .noop)`
was written verbatim, injecting a command; likewise `APPEND` start.
`TaggedResponse(tag: "* BYE x\r\nA1", …)` injected a response.

RFC 3501: `tag = 1*<any ASTRING-CHAR except "+">`. New `Command.Tag`
replaces the `String` in `TaggedCommand`, `TaggedResponse`, `Response`,
`CommandStreamPart`, `AppendCommand`, `BadCommand` and NIOIMAP's state
machine errors; `init?(_:)` validates, literals trap. The parser already
enforces the production. IMAPCommands converts its numeric tags.

* Validate and escape namespace delimiters

`NamespaceDescription(string: "x", char: "\r\n", …)` wrote a raw CRLF
inside `"…"`, injecting a response. `"\""` encoded as `"""`, and `"\\"`
as `"\"` (unterminated); non-ASCII was accepted.

RFC 2342: `DQUOTE QUOTED-CHAR DQUOTE / nil`. `init(string:delimiter:
responseExtensions:)` (was `char:`) throws `InvalidDelimiterError` for
non-ASCII, CR, LF, NUL; the delimiter is stored as a byte, read-only.
Quoted-specials are escaped on write and parsed when escaped.

* Gate a capturing exit test on Swift 6.3
This commit is contained in:
Daniel Eggert authored and GitHub committed 2026-11-04 17:41:52 +00:00
1 parent f77de8e279
commit 4606da62d2
32 files changed
+614 -118

No files matched your search

@@ -139,7 +139,7 @@ final actor TestConnection: ConnectionProtocol {
continuation.yield(
.tagged(
TaggedResponse(
tag: "\(tag)",
tag: Command.Tag(String(tag))!,
state: state
)
)
@@ -129,7 +129,7 @@ final actor TestServer: Sendable {
let greeting: UntaggedStatus
let expectedOrdering: Ordering
private var expectedCommands: [ExpectedCommand]
private var previousTag: String?
private var previousTag: Command.Tag?
private var runningAppend: RunningAppend?
private init(
@@ -296,7 +296,7 @@ extension TestServer {
previousTag == nil
else {
struct ReceivedCommandWhileWaitingForContinuation: Swift.Error {
var previousTag: String
var previousTag: Command.Tag
var command: TaggedCommand
}
throw ReceivedCommandWhileWaitingForContinuation(
@@ -446,7 +446,7 @@ extension TestServer {
private func didReceive(
appendInto mailbox: MailboxName,
tag: String,
tag: Command.Tag,
expectation: RunningAppend
) throws {
guard
@@ -32,7 +32,7 @@ class CommandTester: Benchmark {
@discardableResult func run() throws -> Int {
for i in 1...self.iterations {
var commandBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .init(), loggingMode: false)
commandBuffer.writeCommand(.init(tag: "\(i)", command: self.command))
commandBuffer.writeCommand(.init(tag: Command.Tag("\(i)")!, command: self.command))
var buffer = ByteBuffer()
var chunk = commandBuffer.buffer.nextChunk()
+1 -1
View File
@@ -50,7 +50,7 @@ extension IMAPConnection {
}
static func withAppendWriter<R>(
tag: String,
tag: Command.Tag,
appendingTo mailbox: MailboxName,
underlying: consuming OutboundQueue.AppendQueueWriter,
didCompleteCommand: inout Bool,
+5 -5
View File
@@ -200,7 +200,7 @@ public final class IMAPConnection: Sendable {
try await outboundWriter.write(
TaggedCommand(
tag: "\(tag)",
tag: Command.Tag(tag),
command: command
)
)
@@ -236,7 +236,7 @@ public final class IMAPConnection: Sendable {
try await outboundWriter.write(
TaggedCommand(
tag: "\(tag)",
tag: Command.Tag(tag),
command: .idleStart
)
)
@@ -282,7 +282,7 @@ public final class IMAPConnection: Sendable {
try await outboundWriter.write(
TaggedCommand(
tag: "\(tag)",
tag: Command.Tag(tag),
command: .authenticate(
mechanism: mechanism,
initialResponse: initialResponse
@@ -394,7 +394,7 @@ public final class IMAPConnection: Sendable {
try await outboundWriter.withAppendWriter {
(writer: consuming OutboundQueue.AppendQueueWriter) in
try await AppendWriter.withAppendWriter(
tag: "\(tag)",
tag: Command.Tag(tag),
appendingTo: mailbox,
underlying: writer,
didCompleteCommand: &didCompleteCommand
@@ -836,7 +836,7 @@ extension IMAPConnection.PerCommandResponseStream {
guard
let tag = IMAPConnection.Tag(response.tag),
let continuation = continuations.removeValue(forKey: tag)
else { return .unknownTag(response.tag) }
else { return .unknownTag(String(response.tag)) }
self = .streams(nextTag, continuations)
return .finishContinuation(continuation, response)
case .connectionClosed:
+18
View File
@@ -13,6 +13,7 @@
//===----------------------------------------------------------------------===//
import Logging
import NIOIMAP
extension IMAPConnection {
/// A command tag that uniquely identifies an in-flight IMAP command.
@@ -77,3 +78,20 @@ extension IMAPConnection.Tag {
self.init(rawValue: value)
}
}
extension Command.Tag {
/// Creates the wire tag for a connection tag, for example `A1`.
init(_ tag: IMAPConnection.Tag) {
guard let tag = Command.Tag(String(tag)) else {
preconditionFailure("Invalid command tag: \(String(reflecting: String(tag)))")
}
self = tag
}
}
extension IMAPConnection.Tag {
/// Creates a connection tag from a wire tag; `nil` if this connection didn't generate it.
init?(_ tag: Command.Tag) {
self.init(String(tag))
}
}
@@ -54,7 +54,7 @@ extension ClientStateMachine {
}
// The tag of the APPEND command
var tag: String
var tag: Command.Tag
var state: State = .started(canFinish: false)
var isWaitingForContinuationRequest: Bool {
@@ -37,10 +37,10 @@ extension ClientStateMachine {
}
/// The tag of the IDLE command.
let tag: String
let tag: Command.Tag
private(set) var state: State = .waitingForConfirmation
init(tag: String) {
init(tag: Command.Tag) {
self.tag = tag
}
@@ -37,7 +37,7 @@ public struct UnexpectedResponse: Error {
/// Used to give more context about where the unexpected response was encountered.
public enum Kind: Equatable, Sendable {
case commandCompletionWithUnknownTag(tag: String)
case commandCompletionWithUnknownTag(tag: Command.Tag)
case appendNotWaitingForTaggedResponse
case appendWaitingForTaggedResponse
case appendWithPendingContinuation
@@ -78,9 +78,9 @@ public struct UnexpectedContinuationRequest: Error {
}
public struct DuplicateCommandTag: Error {
public var tag: String
public var tag: Command.Tag
public init(tag: String) {
public init(tag: Command.Tag) {
self.tag = tag
}
}
@@ -224,7 +224,7 @@ struct ClientStateMachine {
var encodingOptions: ClientEncodingOptions
var state: State = .expectingNormalResponse
private var activeCommandTags: Set<String> = []
private var activeCommandTags: Set<Command.Tag> = []
private var allocator: ByteBufferAllocator!
// We mark where we should write up to at the next opportunity
@@ -61,7 +61,7 @@ public enum AppendCommand: Hashable, Sendable {
///
/// - parameter tag: An identifier for the command, typically alphanumeric characters
/// - parameter appendingTo: The destination mailbox name
case start(tag: String, appendingTo: MailboxName)
case start(tag: Command.Tag, appendingTo: MailboxName)
/// Metadata for a message to be appended to the mailbox.
///
@@ -122,7 +122,7 @@ public enum AppendCommand: Hashable, Sendable {
/// `\r\n` to complete the command.
case finish
public var tag: String? {
public var tag: Command.Tag? {
switch self {
case .start(let tag, _):
return tag
@@ -265,8 +265,8 @@ public enum CommandStreamPart: Hashable, Sendable {
/// command tag to correlate client requests with server responses. Returns `nil` for
/// ``idleDone`` and ``continuationResponse(_:)`` cases, which are not tagged commands.
///
/// - Returns: The tag string for tagged commands, or `nil` for untagged operations.
public var tag: String? {
/// - Returns: The tag for tagged commands, or `nil` for untagged operations.
public var tag: Command.Tag? {
switch self {
case .idleDone, .continuationResponse:
return nil
@@ -325,7 +325,7 @@ extension CommandEncodeBuffer {
switch command {
case .start(tag: let tag, appendingTo: let mailbox):
return
self.buffer.writeString("\(tag) APPEND ") + self.buffer.writeMailbox(mailbox)
self.buffer.writeTag(tag) + self.buffer.writeString(" APPEND ") + self.buffer.writeMailbox(mailbox)
case .beginMessage(message: let message):
return self.buffer.writeAppendMessage(message)
case .messageBytes(var bytes):
@@ -0,0 +1,105 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
extension Command {
/// The identifier a client prefixes a command with, and the server echoes in the command's
/// tagged response.
///
/// ### Example
///
/// ```
/// C: A001 NOOP
/// S: A001 OK NOOP completed
/// ```
///
/// `A001` is the tag.
///
/// ## Validity
///
/// A tag is written to the wire verbatim, so anything that isn't a `tag` is rejected:
///
/// - ``init(_:)`` returns `nil`. Use it for a tag derived from input.
/// - ``init(stringLiteral:)`` traps. A literal is written by the programmer, so an invalid one
/// is a bug to be caught on first run rather than handled.
///
/// - SeeAlso: [RFC 3501 Section 2.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-2.2.1)
public struct Tag: Hashable, Sendable {
let stringValue: String
/// Creates a tag from a string, if the string is a valid `tag`.
///
/// A string literal resolves to ``init(stringLiteral:)`` instead, which traps rather than
/// returning `nil`.
///
/// - parameter stringValue: The tag, for example `A001`.
/// - returns: A new tag, or `nil` if `stringValue` is not a valid `tag`.
public init?(_ stringValue: String) {
guard Self.isValidTag(stringValue) else { return nil }
self.stringValue = stringValue
}
init(unchecked stringValue: String) {
assert(Self.isValidTag(stringValue))
self.stringValue = stringValue
}
/// Whether the given string is a `tag`
/// ([RFC 3501 Section 9](https://datatracker.ietf.org/doc/html/rfc3501#section-9)):
/// ```
/// tag = 1*<any ASTRING-CHAR except "+">
/// ```
static func isValidTag(_ string: String) -> Bool {
!string.isEmpty && string.utf8.allSatisfy(\.isTagChar)
}
}
}
extension String {
/// Creates a `String` from a ``Command/Tag``.
///
/// - parameter other: The tag to convert.
public init(_ other: Command.Tag) {
self = other.stringValue
}
}
extension Command.Tag: ExpressibleByStringLiteral {
/// Creates a tag from a string literal.
///
/// A literal is written by the programmer, so an invalid one is a bug to be caught on first
/// run rather than handled. Use ``init(_:)`` for anything else.
///
/// - parameter value: The string literal.
/// - Precondition: `value` is a valid `tag`; this traps if it isn't.
public init(stringLiteral value: String) {
precondition(Self.isValidTag(value), "Invalid command tag: \(String(reflecting: value))")
self.init(unchecked: value)
}
}
extension Command.Tag: CustomStringConvertible {
/// The tag, for example `A001`.
public var description: String {
self.stringValue
}
}
// MARK: - Encoding
extension EncodeBuffer {
@discardableResult mutating func writeTag(_ tag: Command.Tag) -> Int {
assert(Command.Tag.isValidTag(tag.stringValue))
return self.writeString(tag.stringValue)
}
}
@@ -35,12 +35,12 @@ import struct NIO.ByteBuffer
/// - SeeAlso: [RFC 3501 Section 2.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-2.2.1) (Command Syntax)
/// - SeeAlso: ``Command``, ``CommandStreamPart/tagged(_:)``
public struct TaggedCommand: Hashable, Sendable {
/// The tag string used to correlate this command with its response.
/// The tag used to correlate this command with its response.
///
/// Tags are typically alphanumeric identifiers assigned by the client. The server
/// will include this tag in its response to allow the client to match responses to
/// requests, especially when using pipelined commands.
public var tag: String
public var tag: Command.Tag
/// The command to send with this tag.
///
@@ -49,9 +49,9 @@ public struct TaggedCommand: Hashable, Sendable {
/// Creates a new tagged command.
///
/// - parameter tag: The tag string, typically a mixture of alphanumeric characters
/// - parameter tag: The tag, typically a mixture of alphanumeric characters
/// - parameter command: The command to associate with the tag
public init(tag: String, command: Command) {
public init(tag: Command.Tag, command: Command) {
self.tag = tag
self.command = command
}
@@ -71,7 +71,8 @@ extension CommandEncodeBuffer {
/// - returns: The number of bytes written.
@discardableResult public mutating func writeCommand(_ command: TaggedCommand) -> Int {
var size = 0
size += self.buffer.writeString("\(command.tag) ")
size += self.buffer.writeTag(command.tag)
size += self.buffer.writeSpace()
size += self.writeCommand(command.command)
size += self.buffer.writeString("\r\n")
return size
@@ -48,7 +48,12 @@ public struct NamespaceDescription: Hashable, Sendable {
/// The delimiter separates components of a mailbox name in this namespace. Common delimiters
/// include `/` and `.`. If `nil`, the namespace does not use a hierarchy delimiter,
/// meaning mailbox names are not hierarchical within this namespace.
public var delimiter: Character?
public var delimiter: Character? {
self.delimiterByte.map { Character(Unicode.Scalar($0)) }
}
/// A `QUOTED-CHAR` (unescaped), or `nil`.
let delimiterByte: UInt8?
/// Response extensions for this namespace, supporting future protocol enhancements.
///
@@ -62,17 +67,54 @@ public struct NamespaceDescription: Hashable, Sendable {
///
/// - Parameters:
/// - string: The namespace prefix string.
/// - char: The hierarchy delimiter for this namespace, or `nil` if not used.
/// - delimiter: The hierarchy delimiter for this namespace, or `nil` if not used.
/// - responseExtensions: Response extensions for this namespace.
/// - Throws: ``InvalidDelimiterError`` if `delimiter` is not an ASCII character, or is CR, LF, or
/// NUL (which can't be written as a `QUOTED-CHAR`).
public init(
string: ByteBuffer,
char: Character? = nil,
delimiter: Character? = nil,
responseExtensions: OrderedDictionary<ByteBuffer, [ByteBuffer]>
) throws {
var delimiterByte: UInt8?
if let delimiter {
// `Character("\r\n").asciiValue` is LF, so CRLF is rejected too.
guard let byte = delimiter.asciiValue, Self.isValidDelimiter(byte) else {
throw InvalidDelimiterError(delimiter: delimiter)
}
delimiterByte = byte
}
self.init(string: string, delimiterByte: delimiterByte, responseExtensions: responseExtensions)
}
init(
string: ByteBuffer,
delimiterByte: UInt8?,
responseExtensions: OrderedDictionary<ByteBuffer, [ByteBuffer]>
) {
assert(delimiterByte.map(Self.isValidDelimiter) ?? true)
self.string = string
self.delimiter = char
self.delimiterByte = delimiterByte
self.responseExtensions = responseExtensions
}
/// Whether the given byte can be written as a `QUOTED-CHAR`
/// ([RFC 2342 Section 6](https://datatracker.ietf.org/doc/html/rfc2342#section-6)), escaping
/// quoted-specials:
/// ```
/// QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> / "\" quoted-specials
/// ```
static func isValidDelimiter(_ byte: UInt8) -> Bool {
byte.isTextChar
}
}
extension NamespaceDescription {
/// The error thrown when a namespace delimiter can't be written as a `QUOTED-CHAR`.
public struct InvalidDelimiterError: Error, Hashable {
/// The rejected delimiter.
public var delimiter: Character
}
}
// MARK: - Encoding
@@ -84,8 +126,14 @@ extension EncodeBuffer {
size += self.writeIMAPString(description.string)
size += self.writeSpace()
if let char = description.delimiter {
size += self.writeString("\"\(char)\"")
if let byte = description.delimiterByte {
// DQUOTE QUOTED-CHAR DQUOTE, QUOTED-CHAR = ... / "\" quoted-specials
size += self.writeString("\"")
if byte.isQuotedSpecial {
size += self.writeString("\\")
}
size += self.writeString(String(UnicodeScalar(byte)))
size += self.writeString("\"")
} else {
size += self.writeNil()
}
@@ -171,12 +171,12 @@ public enum Response: Hashable, Sendable {
/// The command tag associated with this response, if any.
///
/// Returns the tag string for ``tagged(_:)`` responses, which matches the original command tag
/// Returns the tag for ``tagged(_:)`` responses, which matches the original command tag
/// to correlate the response with its request. Returns `nil` for untagged responses, fatal responses,
/// continuation requests, and other response types that are not associated with a specific command.
///
/// - Returns: The tag string for tagged responses, or `nil` otherwise.
public var tag: String? {
/// - Returns: The tag for tagged responses, or `nil` otherwise.
public var tag: Command.Tag? {
switch self {
case .untagged, .fetch, .fatal, .authenticationChallenge, .idleStarted:
return nil
@@ -47,8 +47,14 @@ public struct ResponseText: Hashable, Sendable {
/// A human-readable description from the server.
///
/// The text provides context-specific information about the response, such as error messages or
/// successful completion notifications. It is always present but may be a single space for some
/// protocol-compliant responses.
/// successful completion notifications. It may be empty.
///
/// - Warning: The text is written to the wire verbatim and must not contain NUL, CR, or LF:
/// `No mailbox x\r\n* BYE pwned` would inject a whole response. Writing such text traps in
/// debug builds.
/// - Note: The parser skips spaces before the text, so leading spaces are not read back.
/// - Warning: With a `nil` ``code``, a text that starts with `[` may be read back as a code:
/// text `[ALERT] hi` is sent as `* OK [ALERT] hi`. Don't start it with untrusted input.
public var text: String
/// Creates a new `ResponseText`.
@@ -68,14 +74,14 @@ extension EncodeBuffer {
self.writeString("[") + self.writeResponseTextCode(code) + self.writeString("] ")
}
// If the text is empty, write an additional space
// to enforce standard compliance. Oddly, this is
// perfectly legal IMAP.
+ self.writeText(text.text.count > 0 ? text.text : " ")
// `text` is `1*…`, so empty text is written as a single space, which parses back as
// empty.
+ self.writeText(text.text.isEmpty ? " " : text.text)
}
@discardableResult mutating func writeText(_ text: String) -> Int {
self.writeString(text)
assert(text.utf8.allSatisfy(\.isUTF8TextByte), "Invalid text: \(String(reflecting: text))")
return self.writeString(text)
}
}
@@ -55,7 +55,7 @@ public struct TaggedResponse: Hashable, Sendable {
/// The same tag that appeared in the original client command, allowing the client
/// to correlate the response with its request. The tag uniquely identifies the command within
/// the connection session.
public var tag: String
public var tag: Command.Tag
/// The outcome status of the command execution.
///
@@ -67,7 +67,7 @@ public struct TaggedResponse: Hashable, Sendable {
/// Creates a new `TaggedResponse`.
/// - parameter tag: The tag of the command that led to this response.
/// - parameter state: Signals if the command was successfully executed.
public init(tag: String, state: State) {
public init(tag: Command.Tag, state: State) {
self.tag = tag
self.state = state
}
@@ -77,6 +77,9 @@ public struct TaggedResponse: Hashable, Sendable {
extension EncodeBuffer {
@discardableResult mutating func writeTaggedResponse(_ response: TaggedResponse) -> Int {
self.writeString("\(response.tag) ") + self.writeTaggedResponseState(response.state) + self.writeString("\r\n")
self.writeTag(response.tag)
+ self.writeSpace()
+ self.writeTaggedResponseState(response.state)
+ self.writeString("\r\n")
}
}
@@ -226,7 +226,7 @@ extension GrammarParser {
// text requires minimum 1 char, but we want to be lenient here
// and allow 0 characters to represent empty text
let parsed = try PL.parseZeroOrMoreCharacters(buffer: &buffer, tracker: tracker) { (char) -> Bool in
char.isTextChar
char.isUTF8TextByte
}
let text = try ParserLibrary.parseBufferAsUTF8(parsed)
@@ -1852,17 +1852,25 @@ extension GrammarParser {
// (DQUOTE QUOTED-CHAR DQUOTE / nil)
// [Namespace-Response-Extensions] ")"
func parseNamespaceDescription(buffer: inout ParseBuffer, tracker: StackTracker) throws -> NamespaceDescription {
func parseNamespaceDescr_quotedChar(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Character? {
func parseNamespaceDescr_quotedChar(buffer: inout ParseBuffer, tracker: StackTracker) throws -> UInt8? {
try PL.parseFixedString("\"", buffer: &buffer, tracker: tracker)
let char = try PL.parseByte(buffer: &buffer, tracker: tracker)
guard char.isQuotedChar else {
throw ParserError(hint: "Invalid character")
// QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> / "\" quoted-specials
var byte = try PL.parseByte(buffer: &buffer, tracker: tracker)
if byte == UInt8(ascii: "\\") {
byte = try PL.parseByte(buffer: &buffer, tracker: tracker)
guard byte.isQuotedSpecial else {
throw ParserError(hint: "Expected quoted special")
}
} else {
guard byte.isQuotedChar else {
throw ParserError(hint: "Invalid character")
}
}
try PL.parseFixedString("\"", buffer: &buffer, tracker: tracker)
return Character(.init(char))
return byte
}
func parseNamespaceDescr_nil(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Character? {
func parseNamespaceDescr_nil(buffer: inout ParseBuffer, tracker: StackTracker) throws -> UInt8? {
try self.parseNil(buffer: &buffer, tracker: tracker)
return nil
}
@@ -1871,7 +1879,7 @@ extension GrammarParser {
try PL.parseFixedString("(", buffer: &buffer, tracker: tracker)
let string = try self.parseString(buffer: &buffer, tracker: tracker)
try PL.parseSpaces(buffer: &buffer, tracker: tracker)
let char = try PL.parseOneOf(
let delimiter = try PL.parseOneOf(
parseNamespaceDescr_quotedChar,
parseNamespaceDescr_nil,
buffer: &buffer,
@@ -1879,7 +1887,7 @@ extension GrammarParser {
)
let extensions = try self.parseNamespaceResponseExtensions(buffer: &buffer, tracker: tracker)
try PL.parseFixedString(")", buffer: &buffer, tracker: tracker)
return .init(string: string, char: char, responseExtensions: extensions)
return .init(string: string, delimiterByte: delimiter, responseExtensions: extensions)
}
}
@@ -2647,11 +2655,9 @@ extension GrammarParser {
}
// tag = 1*<any ASTRING-CHAR except "+">
func parseTag(buffer: inout ParseBuffer, tracker: StackTracker) throws -> String {
let parsed = try PL.parseOneOrMoreCharacters(buffer: &buffer, tracker: tracker) { char -> Bool in
char.isAStringChar && char != UInt8(ascii: "+")
}
return try ParserLibrary.parseBufferAsUTF8(parsed)
func parseTag(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Command.Tag {
let parsed = try PL.parseOneOrMoreCharacters(buffer: &buffer, tracker: tracker) { $0.isTagChar }
return Command.Tag(unchecked: try ParserLibrary.parseBufferAsUTF8(parsed))
}
// tagged-ext = tagged-ext-label SP tagged-ext-val
@@ -77,7 +77,7 @@ public struct BadCommand: Error {
///
/// Allows the server to send a properly-tagged error response to the client,
/// maintaining IMAP's request/response correlation even when the command is malformed.
public var commandTag: String
public var commandTag: Command.Tag
/// Why parsing failed.
///
@@ -71,6 +71,12 @@ extension UInt8 {
}
}
/// `TEXT-CHAR`, or a byte of a UTF8-2/3/4 sequence: RFC 9051 `text`. Callers check that the
/// bytes are well-formed UTF-8.
var isUTF8TextByte: Bool {
self.isTextChar || self > 0x7F
}
var isAStringChar: Bool {
switch self {
case _ where self.isResponseSpecial, _ where isAtomChar:
@@ -80,6 +86,11 @@ extension UInt8 {
}
}
/// tag = 1*<any ASTRING-CHAR except "+">
var isTagChar: Bool {
self.isAStringChar && self != UInt8(ascii: "+")
}
/// ATOM-CHAR = <any CHAR except atom-specials>
/// CHAR = %x01-7F ; RFC 5234
var isAtomChar: Bool {
+34
View File
@@ -0,0 +1,34 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
@testable import IMAPCommands
import NIOIMAP
import Testing
/// Tagged responses are routed to their command by converting the wire tag back.
@Suite("IMAPConnection.Tag")
struct TagTests {
@Test("connection tags round-trip through wire tags")
func roundTrip() {
let tag = IMAPConnection.Tag.first.makeNext()
#expect(Command.Tag(tag) == "A2")
#expect(IMAPConnection.Tag(Command.Tag(tag)) == tag)
}
@Test("wire tags this connection didn't generate are not connection tags")
func foreignTag() {
let wireTag: Command.Tag = "B1"
#expect(IMAPConnection.Tag(wireTag) == nil)
}
}
@@ -300,9 +300,9 @@ private struct CommandStreamTests {
(AppendCommand.catenateData(.end), nil),
(AppendCommand.endCatenate, nil),
(AppendCommand.finish, nil),
] as [(AppendCommand, String?)]
] as [(AppendCommand, Command.Tag?)]
)
func appendCommandTag(_ fixture: (AppendCommand, String?)) {
func appendCommandTag(_ fixture: (AppendCommand, Command.Tag?)) {
#expect(fixture.0.tag == fixture.1)
}
@@ -314,9 +314,9 @@ private struct CommandStreamTests {
(CommandStreamPart.append(.start(tag: "C3", appendingTo: .inbox)), "C3"),
(CommandStreamPart.append(.finish), nil),
(CommandStreamPart.continuationResponse("data"), nil),
] as [(CommandStreamPart, String?)]
] as [(CommandStreamPart, Command.Tag?)]
)
func commandStreamPartTag(_ fixture: (CommandStreamPart, String?)) {
func commandStreamPartTag(_ fixture: (CommandStreamPart, Command.Tag?)) {
#expect(fixture.0.tag == fixture.1)
}
@@ -0,0 +1,143 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the SwiftNIO open source project
//
// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors
// Licensed under Apache License v2.0
//
// See LICENSE.txt for license information
// See CONTRIBUTORS.txt for the list of SwiftNIO project authors
//
// SPDX-License-Identifier: Apache-2.0
//
//===----------------------------------------------------------------------===//
import NIO
@_spi(NIOIMAPInternal) @testable import NIOIMAPCore
import Testing
@Suite("Command.Tag")
struct CommandTagTests {
/// A tag is written to the wire verbatim, so ``Command/Tag/init(_:)`` is the only thing
/// between a caller that builds tags from untrusted input and an injected command.
@Test(
"invalid tags are rejected",
arguments: [
"",
"+",
"A+1", // ASTRING-CHAR, but not a tag char.
"A 1",
"A(1",
"A{1",
"A*1",
"A%1",
#"A"1"#,
#"A\1"#,
"Ä1",
"A\u{7F}1",
"A1 NOOP\r\nA2 DELETE INBOX\r\nA3", // Would inject a whole command.
"* BYE x\r\nA1", // Would inject an untagged response.
]
)
func invalidTags(_ string: String) {
#expect(Command.Tag(string) == nil)
}
@Test("valid tags", arguments: validTagStrings)
func validTags(_ string: String) {
#expect(Command.Tag(string).map { String($0) } == string)
}
/// Written verbatim, so every tag we accept has to parse back unchanged, in a command and in a
/// response.
@Test("valid tags round-trip in a command", arguments: validTagStrings)
func commandRoundTrip(_ string: String) throws {
let tag = try #require(Command.Tag(string))
var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .rfc3501, loggingMode: false)
encodeBuffer.writeCommand(TaggedCommand(tag: tag, command: .noop))
var buffer = ParseBuffer(encodeBuffer.buffer.nextChunk().bytes)
let parsed = try GrammarParser().parseTaggedCommand(buffer: &buffer, tracker: .testTracker)
#expect(parsed == TaggedCommand(tag: tag, command: .noop))
}
@Test("valid tags round-trip in an APPEND", arguments: validTagStrings)
func appendRoundTrip(_ string: String) throws {
let tag = try #require(Command.Tag(string))
var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .rfc3501, loggingMode: false)
encodeBuffer.writeCommandStream(.append(.start(tag: tag, appendingTo: .inbox)))
var bytes = encodeBuffer.buffer.nextChunk().bytes
bytes.writeString(" ")
var buffer = ParseBuffer(bytes)
let parsed = try GrammarParser().parseAppend(buffer: &buffer, tracker: .testTracker)
#expect(parsed == .append(.start(tag: tag, appendingTo: .inbox)))
}
@Test("valid tags round-trip in a tagged response", arguments: validTagStrings)
func responseRoundTrip(_ string: String) throws {
TestUtilities.expectRoundTrip(
TaggedResponse(tag: try #require(Command.Tag(string)), state: .ok(.init(text: "done"))),
terminator: "",
encoder: { $0.writeTaggedResponse($1) },
parser: GrammarParser().parseTaggedResponse
)
}
@Test(arguments: [
ParseFixture.tag("abc", "\r", expected: .success("abc")),
ParseFixture.tag("abc", "+", expected: .success("abc")),
ParseFixture.tag("+", "", expected: .failure),
ParseFixture.tag("", "", expected: .incompleteMessage),
// RFC 3501: tag = 1*<any ASTRING-CHAR except "+">; ASTRING-CHAR
// inherits the CTL exclusion via ATOM-CHAR, and RFC 5234 has
// CTL = %x00-1F / %x7F, so a tag stops at DEL and cannot start with it.
ParseFixture.tag("ab", "\u{7F}c\r", expected: .success("ab")),
ParseFixture.tag("\u{7F}", "", expected: .failure),
// Stops at non-ASCII: parsed tags go through `init(unchecked:)`.
ParseFixture.tag("ab", "ü\r", expected: .success("ab")),
])
func parse(_ fixture: ParseFixture<Command.Tag>) {
fixture.checkParsing()
}
#if !os(iOS) && !os(watchOS) && !os(tvOS) && !os(visionOS) && !os(Android)
@Test("an invalid string literal traps") func stringLiteralPreconditionFailure() async {
let result = await #expect(
processExitsWith: ExitTest.Condition.failure,
observing: [\.standardErrorContent],
performing: {
let tag: Command.Tag = "A 1"
_ = tag
}
)
TestUtilities.expectTrapMessage(result, "Invalid command tag")
}
#endif
}
// MARK: -
private let validTagStrings = [
"A",
"1",
"A001",
"a.b-c_d",
"]",
"A]1",
"!#$&'",
"~|`^=",
]
extension ParseFixture<Command.Tag> {
fileprivate static func tag(
_ input: String,
_ terminator: String,
expected: Expected
) -> Self {
ParseFixture(
input: input,
terminator: terminator,
expected: expected,
parser: GrammarParser().parseTag
)
}
}
@@ -22,13 +22,13 @@ struct NamespaceTests {
@Test(arguments: [
EncodeFixture.namespace([], "NIL"),
EncodeFixture.namespace(
[.init(string: "str1", char: nil, responseExtensions: [:])],
[try! .init(string: "str1", delimiter: nil, responseExtensions: [:])],
"((\"str1\" NIL))"
),
EncodeFixture.namespace(
[
.init(string: "str1", char: nil, responseExtensions: [:]),
.init(string: "str2", char: nil, responseExtensions: [:]),
try! .init(string: "str1", delimiter: nil, responseExtensions: [:]),
try! .init(string: "str2", delimiter: nil, responseExtensions: [:]),
],
"((\"str1\" NIL)(\"str2\" NIL))"
),
@@ -21,15 +21,15 @@ import Testing
struct NamespaceDescriptionTests {
@Test(arguments: [
EncodeFixture.namespaceDescription(
.init(string: "string", char: nil, responseExtensions: [:]),
try! .init(string: "string", delimiter: nil, responseExtensions: [:]),
"(\"string\" NIL)"
),
EncodeFixture.namespaceDescription(
.init(string: "string", char: "a", responseExtensions: [:]),
try! .init(string: "string", delimiter: "a", responseExtensions: [:]),
"(\"string\" \"a\")"
),
EncodeFixture.namespaceDescription(
.init(string: "string", char: nil, responseExtensions: ["str2": ["str3"]]),
try! .init(string: "string", delimiter: nil, responseExtensions: ["str2": ["str3"]]),
"(\"string\" NIL \"str2\" (\"str3\"))"
),
])
@@ -37,29 +37,97 @@ struct NamespaceDescriptionTests {
fixture.checkEncoding()
}
@Test(
"encode escapes quoted-specials",
arguments: [
("\\", #"("x" "\\")"#),
("\"", #"("x" "\"")"#),
] as [(Character, String)]
)
func encodeQuotedSpecial(_ delimiter: Character, _ expected: String) throws {
EncodeFixture(
input: try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:]),
bufferKind: .defaultServer,
expectedString: expected,
encoder: { $0.writeNamespaceDescription($1) }
).checkEncoding()
}
/// The delimiter isn't PII, so logging shows it.
@Test("logging mode shows the delimiter")
func loggingMode() throws {
var buffer = EncodeBuffer.serverEncodeBuffer(
buffer: ByteBuffer(),
options: ResponseEncodingOptions(),
loggingMode: true
)
buffer.writeNamespaceDescription(
try NamespaceDescription(string: "x", delimiter: "/", responseExtensions: [:])
)
#expect(String(buffer: buffer.nextChunk().bytes).hasSuffix(#" "/")"#))
}
/// `DQUOTE QUOTED-CHAR DQUOTE`: CR, LF, NUL, and non-ASCII can't be written.
@Test(
"invalid delimiter throws",
arguments: ["\r", "\n", "\r\n", "\0", "ü", "🇨🇭"] as [Character]
)
func invalidDelimiter(_ delimiter: Character) {
#expect(throws: NamespaceDescription.InvalidDelimiterError(delimiter: delimiter)) {
try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:])
}
}
/// Every delimiter we accept has to parse back unchanged.
@Test(
"delimiter round-trips",
arguments: [nil, "/", ".", "\\", "\"", "~", "\t", " ", "\u{7F}"] as [Character?]
)
func delimiterRoundTrip(_ delimiter: Character?) throws {
let description = try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:])
#expect(description.delimiter == delimiter)
TestUtilities.expectRoundTrip(
description,
encoder: { $0.writeNamespaceDescription($1) },
parser: GrammarParser().parseNamespaceDescription
)
}
@Test(arguments: [
ParseFixture.namespaceDescription(
"(\"str1\" NIL)",
" ",
expected: .success(.init(string: "str1", char: nil, responseExtensions: [:]))
expected: .success(try! .init(string: "str1", delimiter: nil, responseExtensions: [:]))
),
ParseFixture.namespaceDescription(
"(\"str\" \"a\")",
" ",
expected: .success(.init(string: "str", char: "a", responseExtensions: [:]))
expected: .success(try! .init(string: "str", delimiter: "a", responseExtensions: [:]))
),
ParseFixture.namespaceDescription(
"(\"str\" \"\r\")",
" ",
expected: .failureIgnoringBufferModifications
),
// Escaped quoted-specials: `"\\"` is a backslash, `"\""` a double quote.
ParseFixture.namespaceDescription(
#"("str" "\\")"#,
" ",
expected: .success(try! .init(string: "str", delimiter: "\\", responseExtensions: [:]))
),
ParseFixture.namespaceDescription(
#"("str" "\"")"#,
" ",
expected: .success(try! .init(string: "str", delimiter: "\"", responseExtensions: [:]))
),
ParseFixture.namespaceDescription(#"("str" "\a")"#, " ", expected: .failureIgnoringBufferModifications),
ParseFixture.namespaceDescription(
"(\"str\" NIL \"ext-key\" (\"val1\" \"val2\"))",
" ",
expected: .success(
.init(
try! .init(
string: "str",
char: nil,
delimiter: nil,
responseExtensions: ["ext-key": ["val1", "val2"]]
)
)
@@ -78,13 +146,13 @@ struct NamespaceDescriptionTests {
),
ParseFixture.namespace(
"((\"#mh/\" \"/\"))",
expected: .success([.init(string: "#mh/", char: "/", responseExtensions: [:])])
expected: .success([try! .init(string: "#mh/", delimiter: "/", responseExtensions: [:])])
),
ParseFixture.namespace(
"((\"\" \"/\")(\"#mh/\" \"/\"))",
expected: .success([
.init(string: "", char: "/", responseExtensions: [:]),
.init(string: "#mh/", char: "/", responseExtensions: [:]),
try! .init(string: "", delimiter: "/", responseExtensions: [:]),
try! .init(string: "#mh/", delimiter: "/", responseExtensions: [:]),
])
),
ParseFixture.namespace("", "", expected: .incompleteMessage),
@@ -26,9 +26,11 @@ struct NamespaceResponseTests {
),
EncodeFixture.namespaceResponse(
.init(
userNamespace: [NamespaceDescription(string: "", responseExtensions: [:])],
otherUserNamespace: [NamespaceDescription(string: "#shared/", char: "/", responseExtensions: [:])],
sharedNamespace: [NamespaceDescription(string: "Public Folders/", responseExtensions: [:])]
userNamespace: [try! NamespaceDescription(string: "", responseExtensions: [:])],
otherUserNamespace: [
try! NamespaceDescription(string: "#shared/", delimiter: "/", responseExtensions: [:])
],
sharedNamespace: [try! NamespaceDescription(string: "Public Folders/", responseExtensions: [:])]
),
"NAMESPACE ((\"\" NIL)) ((\"#shared/\" \"/\")) ((\"Public Folders/\" NIL))"
),
@@ -299,9 +299,9 @@ private struct PIIFixture: Sendable, CustomTestStringConvertible {
private struct ResponseTagFixture: Sendable, CustomTestStringConvertible {
let response: Response
let expectedTag: String?
let expectedTag: Command.Tag?
var testDescription: String { expectedTag ?? "(nil)" }
var testDescription: String { expectedTag.map { String($0) } ?? "(nil)" }
}
private struct StreamingKindSectionSpecifierFixture: Sendable, CustomTestStringConvertible {
@@ -18,6 +18,49 @@ import Testing
@Suite("ResponseText")
struct ResponseTextTests {
/// Written verbatim, so all text we accept has to parse back unchanged, with and without a code.
@Test("valid text round-trips", arguments: validTextStrings)
func validTextRoundTrips(_ string: String) {
for code in [nil, ResponseTextCode.alert] {
TestUtilities.expectRoundTrip(
ResponseText(code: code, text: string),
terminator: "\r\n",
encoder: { $0.writeResponseText($1) },
parser: GrammarParser().parseResponseText
)
}
}
// Exit tests can only capture values (the `[string = …]` list below) with Swift 6.3 and later.
#if compiler(>=6.3) && DEBUG && !os(iOS) && !os(watchOS) && !os(tvOS) && !os(visionOS) && !os(Android)
/// Text is written to the wire verbatim, so a server that echoes untrusted input could inject a
/// whole response.
@Test(
"writing invalid text traps",
arguments: [
"a\rb",
"a\nb",
"a\u{0}b",
"No mailbox x\r\n* BYE pwned",
]
)
func invalidTextTraps(_ string: String) async {
let result = await #expect(
processExitsWith: ExitTest.Condition.failure,
observing: [\.standardErrorContent],
performing: { [string = string as String] in
var buffer = EncodeBuffer.serverEncodeBuffer(
buffer: ByteBuffer(),
options: ResponseEncodingOptions(),
loggingMode: false
)
buffer.writeResponseText(ResponseText(text: string))
}
)
TestUtilities.expectTrapMessage(result, "Invalid text")
}
#endif
@Test(arguments: [
EncodeFixture.responseText(.init(code: nil, text: "buffer"), "buffer"),
EncodeFixture.responseText(.init(code: .alert, text: "buffer"), "[ALERT] buffer"),
@@ -44,11 +87,21 @@ struct ResponseTextTests {
expected: .success(.init(code: .uidValidity(1_561_789_793), text: ""))
),
ParseFixture.responseText("[UIDNEXT 171]", expected: .success(.init(code: .uidNext(171), text: ""))),
ParseFixture.responseText("Grüezi 🇨🇭", expected: .success(.init(code: nil, text: "Grüezi 🇨🇭"))),
])
func parse(_ fixture: ParseFixture<ResponseText>) {
fixture.checkParsing()
}
@Test("non-UTF-8 text fails to parse")
func parseLatin1() {
// Latin-1 `ü`.
var buffer = ParseBuffer(ByteBuffer(bytes: [UInt8(ascii: "a"), 0xFC, UInt8(ascii: "\r")]))
#expect(throws: ParserError.self) {
try GrammarParser().parseResponseText(buffer: &buffer, tracker: .testTracker)
}
}
@Test(
"custom debug string convertible",
arguments: [
@@ -63,6 +116,19 @@ struct ResponseTextTests {
// MARK: -
private let validTextStrings = [
"",
"a",
"CAPABILITY completed",
"a b ",
"a\tb",
"[a",
"a]",
"Grüezi",
"日本語",
"🇨🇭",
]
extension EncodeFixture<ResponseText> {
fileprivate static func responseText(
_ input: ResponseText,
@@ -187,9 +187,9 @@ struct ResponseTextCodeTests {
expected: .success(
.namespace(
.init(
userNamespace: [.init(string: "Foo", responseExtensions: [:])],
userNamespace: [try! .init(string: "Foo", responseExtensions: [:])],
otherUserNamespace: [],
sharedNamespace: [.init(string: "Bar", char: nil, responseExtensions: [:])]
sharedNamespace: [try! .init(string: "Bar", delimiter: nil, responseExtensions: [:])]
)
)
)
@@ -294,24 +294,6 @@ private struct GrammarParserPrimitivesTests {
fixture.checkParsing()
}
@Test(
"parse tag",
arguments: [
ParseFixture.tag("abc", "\r", expected: .success("abc")),
ParseFixture.tag("abc", "+", expected: .success("abc")),
ParseFixture.tag("+", "", expected: .failure),
ParseFixture.tag("", "", expected: .incompleteMessage),
// RFC 3501: tag = 1*<any ASTRING-CHAR except "+">; ASTRING-CHAR
// inherits the CTL exclusion via ATOM-CHAR, and RFC 5234 has
// CTL = %x00-1F / %x7F, so a tag stops at DEL and cannot start with it.
ParseFixture.tag("ab", "\u{7F}c\r", expected: .success("ab")),
ParseFixture.tag("\u{7F}", "", expected: .failure),
]
)
func parseTag(_ fixture: ParseFixture<String>) {
fixture.checkParsing()
}
@Test(
"parse vendor-token",
arguments: [
@@ -415,19 +397,6 @@ extension ParseFixture<String> {
)
}
fileprivate static func tag(
_ input: String,
_ terminator: String,
expected: Expected
) -> Self {
ParseFixture(
input: input,
terminator: terminator,
expected: expected,
parser: GrammarParser().parseTag
)
}
fileprivate static func vendorToken(
_ input: String,
_ terminator: String,
@@ -186,7 +186,7 @@ private enum RoundtripTests {
)
static func commandRoundtrip(_ fixture: RoundtripFixture) throws {
var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .init(), loggingMode: false)
let tag = "1"
let tag: Command.Tag = "1"
let taggedCommand = TaggedCommand(tag: tag, command: fixture.command)
encodeBuffer.writeCommand(taggedCommand)
// required for commands that might terminate with a literal (e.g. append)
@@ -115,6 +115,14 @@ struct UInt8ParseTypeMembershipTests {
#expect(invalid.allSatisfy { !$0.isAStringChar })
}
@Test("tag char")
func tagChar() {
let valid = atomChars.union([UInt8(ascii: "]")]).subtracting([UInt8(ascii: "+")])
let invalid = allChars.subtracting(valid)
#expect(valid.allSatisfy { $0.isTagChar })
#expect(invalid.allSatisfy { !$0.isTagChar })
}
/// `list-char = ATOM-CHAR / list-wildcards / resp-specials`
@Test("list char")
func listChar() {
@@ -152,6 +160,14 @@ struct UInt8ParseTypeMembershipTests {
#expect(invalid.allSatisfy { !$0.isTextChar })
}
@Test("UTF-8 text byte")
func utf8TextByte() {
let invalid: Set<UInt8> = [UInt8(ascii: "\r"), .init(ascii: "\n"), 0]
let valid = allChars.subtracting(invalid)
#expect(valid.allSatisfy { $0.isUTF8TextByte })
#expect(invalid.allSatisfy { !$0.isUTF8TextByte })
}
@Test("hex character")
func hexCharacter() {
var valid = Set<UInt8>()