mirror of
https://github.com/apple/swift-nio-imap
synced 2026-11-22 04:30:43 +00:00
187 lines
8.6 KiB
Swift
187 lines
8.6 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// This source file is part of the SwiftNIO open source project
|
|
//
|
|
// Copyright (c) 2020 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
|
|
//
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
/// Configuration options for encoding IMAP commands.
|
|
///
|
|
/// `CommandEncodingOptions` controls how IMAP commands are encoded into wire format,
|
|
/// particularly affecting the choice of literal formats and string quoting. These options
|
|
/// allow clients to select encoding strategies based on server capabilities and protocol
|
|
/// versions.
|
|
///
|
|
/// ## Literal Formats
|
|
///
|
|
/// The IMAP protocol defines several literal formats, each with different tradeoffs:
|
|
/// - **Quoted strings**: Safe, fast, but limited to certain characters
|
|
/// - **Synchronizing literals** (`{20}`): Standard in RFC 3501, requires continuation
|
|
/// - **Non-synchronizing literals** (`{20+}`/`{20-}`): RFC 7888, faster, no continuation needed
|
|
/// - **Binary literals** (`~{20}`): RFC 3516, for binary data in `APPEND` commands
|
|
///
|
|
/// The options below control which formats the encoder will use when serializing strings
|
|
/// and binary data.
|
|
///
|
|
/// ## Example
|
|
///
|
|
/// ```swift
|
|
/// var options = CommandEncodingOptions()
|
|
/// options.useNonSynchronizingLiteralPlus = true // Use LITERAL+ format
|
|
/// options.useBinaryLiteral = true // Support binary data
|
|
/// ```
|
|
///
|
|
/// - SeeAlso: [RFC 3501 Section 4.3](https://datatracker.ietf.org/doc/html/rfc3501#section-4.3) (quoted strings),
|
|
/// [RFC 3501 Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc3501#section-4.3.3) (literals),
|
|
/// [RFC 7888](https://datatracker.ietf.org/doc/html/rfc7888) (non-synchronizing literals),
|
|
/// [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516) (binary literals)
|
|
public struct CommandEncodingOptions: Hashable, Sendable {
|
|
/// Use RFC 3501 quoted strings when possible.
|
|
///
|
|
/// Quoted strings are the preferred encoding for short strings containing only
|
|
/// safe characters. Setting this to `false` forces use of literals instead.
|
|
///
|
|
/// - SeeAlso: [RFC 3501 Section 4.3](https://datatracker.ietf.org/doc/html/rfc3501#section-4.3)
|
|
public var useQuotedString: Bool
|
|
|
|
/// Use the RFC 3501 synchronizing literal format (`{20}\r\n`).
|
|
///
|
|
/// The standard literal format that requires the server to send a `+`
|
|
/// continuation request before the client sends the literal data. Set to `true`
|
|
/// for RFC 3501-compliant encoding.
|
|
///
|
|
/// - SeeAlso: [RFC 3501 Section 4.3.3](https://datatracker.ietf.org/doc/html/rfc3501#section-4.3.3)
|
|
public var useSynchronizingLiteral: Bool
|
|
|
|
/// Use the non-synchronizing literal plus format (`{20+}\r\n`).
|
|
///
|
|
/// Defined in RFC 7888, this format allows sending literal data immediately
|
|
/// without waiting for a continuation request, improving performance at the cost
|
|
/// of requiring server support.
|
|
///
|
|
/// Requires server capability: ``Capability/literalPlus``
|
|
///
|
|
/// - SeeAlso: [RFC 7888](https://datatracker.ietf.org/doc/html/rfc7888)
|
|
public var useNonSynchronizingLiteralPlus: Bool
|
|
|
|
/// Use the non-synchronizing literal minus format (`{20-}\r\n`).
|
|
///
|
|
/// An alternative non-synchronizing literal format. If both this and
|
|
/// ``useNonSynchronizingLiteralPlus`` are `true`, the implementation may choose
|
|
/// either format.
|
|
///
|
|
/// - SeeAlso: [RFC 7888](https://datatracker.ietf.org/doc/html/rfc7888)
|
|
public var useNonSynchronizingLiteralMinus: Bool
|
|
|
|
/// Use binary content literals (`~{20}\r\n`).
|
|
///
|
|
/// Defined in RFC 3516, this format allows sending arbitrary binary data.
|
|
/// Note that binary literals can only be used in certain contexts, such as the
|
|
/// `APPEND` command with the `BINARY` extension.
|
|
///
|
|
/// Requires server capability: ``Capability/binary``
|
|
///
|
|
/// - Note: These can only be used in some places, namely `APPEND`.
|
|
/// - SeeAlso: [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516)
|
|
public var useBinaryLiteral: Bool
|
|
|
|
/// Use the CHARSET parameter in `SEARCH` commands.
|
|
///
|
|
/// RFC 3501 requires this parameter; later standards (RFC 9051, RFC 9755)
|
|
/// recommend against or forbid it. This is typically modified based on the
|
|
/// `UTF8=ACCEPT` capability (see ``updateEnabledOptions(capabilities:)``).
|
|
///
|
|
/// - SeeAlso: [RFC 3501 Section 6.4.4](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.4),
|
|
/// [RFC 9051](https://datatracker.ietf.org/doc/html/rfc9051),
|
|
/// [RFC 9755](https://datatracker.ietf.org/doc/html/rfc9755)
|
|
public var useSearchCharset: Bool
|
|
|
|
/// The default RFC 3501-compliant encoding options.
|
|
///
|
|
/// These options enable quoted strings and synchronizing literals only,
|
|
/// providing baseline compatibility with any IMAP server.
|
|
public static let rfc3501: Self = .init()
|
|
|
|
/// Creates new command encoding options with specified literal format preferences.
|
|
///
|
|
/// By default, quoted strings and synchronizing literals are enabled, providing
|
|
/// RFC 3501-compliant behavior.
|
|
///
|
|
/// - Parameters:
|
|
/// - useQuotedString: Whether to use quoted strings. Defaults to `true`.
|
|
/// - useSynchronizingLiteral: Whether to use synchronizing literals. Defaults to `true`.
|
|
/// - useNonSynchronizingLiteralPlus: Whether to use LITERAL+ format. Defaults to `false`.
|
|
/// - useNonSynchronizingLiteralMinus: Whether to use LITERAL- format. Defaults to `false`.
|
|
/// - useBinaryLiteral: Whether to use binary literals. Defaults to `false`.
|
|
public init(
|
|
useQuotedString: Bool = true,
|
|
useSynchronizingLiteral: Bool = true,
|
|
useNonSynchronizingLiteralPlus: Bool = false,
|
|
useNonSynchronizingLiteralMinus: Bool = false,
|
|
useBinaryLiteral: Bool = false
|
|
) {
|
|
self.useQuotedString = useQuotedString
|
|
self.useSynchronizingLiteral = useSynchronizingLiteral
|
|
self.useNonSynchronizingLiteralPlus = useNonSynchronizingLiteralPlus
|
|
self.useNonSynchronizingLiteralMinus = useNonSynchronizingLiteralMinus
|
|
self.useBinaryLiteral = useBinaryLiteral
|
|
// set this to true instead of passing it from the caller, since
|
|
// it shouldn't be based on CAPABILITY, only modified based on
|
|
// ENABLED.
|
|
self.useSearchCharset = true
|
|
}
|
|
}
|
|
|
|
extension CommandEncodingOptions {
|
|
/// Creates encoding options by inspecting server capabilities.
|
|
///
|
|
/// Automatically enables extended literal formats based on
|
|
/// server capabilities, making it easy to use the best available encoding strategy.
|
|
///
|
|
/// The initialization process:
|
|
/// - Starts with RFC 3501 defaults (quoted strings + synchronizing literals)
|
|
/// - If server has `LITERAL+` capability: enables ``useNonSynchronizingLiteralPlus``
|
|
/// - If server has `LITERAL-` capability: enables ``useNonSynchronizingLiteralMinus``
|
|
/// - If server has `BINARY` capability: enables ``useBinaryLiteral``
|
|
///
|
|
/// - Parameter capabilities: Array of ``Capability`` from a `CAPABILITY` response.
|
|
///
|
|
/// - SeeAlso: ``Capability/literalPlus``, ``Capability/literalMinus``, ``Capability/binary``
|
|
public init(capabilities: [Capability]) {
|
|
self.init()
|
|
if capabilities.contains(.literalPlus) {
|
|
self.useNonSynchronizingLiteralPlus = true
|
|
} else if capabilities.contains(.literalMinus) {
|
|
self.useNonSynchronizingLiteralMinus = true
|
|
}
|
|
if capabilities.contains(.binary) {
|
|
self.useBinaryLiteral = true
|
|
}
|
|
}
|
|
|
|
/// Updates encoding options based on ENABLE response capabilities.
|
|
///
|
|
/// After a client successfully enables extensions with the `ENABLE` command,
|
|
/// this method updates the encoding options to reflect any newly enabled capabilities.
|
|
/// Currently, this only affects the `useSearchCharset` option.
|
|
///
|
|
/// When `UTF8=ACCEPT` is enabled, the `useSearchCharset` option is set to `false`
|
|
/// because the server no longer requires charset specifications in SEARCH commands.
|
|
///
|
|
/// - Parameter capabilities: Server capabilities that have been enabled.
|
|
///
|
|
/// - SeeAlso: ``Capability/utf8(_:)``, [RFC 6531 Section 3.1](https://datatracker.ietf.org/doc/html/rfc6531#section-3.1)
|
|
public mutating func updateEnabledOptions(capabilities: [Capability]) {
|
|
if capabilities.contains(.utf8(.accept)) {
|
|
self.useSearchCharset = false
|
|
}
|
|
}
|
|
}
|