mirror of
https://github.com/apple/swift-nio-imap
synced 2026-11-22 04:30:43 +00:00
* 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
798 lines
31 KiB
Swift
798 lines
31 KiB
Swift
//===----------------------------------------------------------------------===//
|
||
//
|
||
// This source file is part of the SwiftNIO open source project
|
||
//
|
||
// Copyright (c) 2021 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) import NIOIMAPCore
|
||
|
||
public struct InvalidClientState: Error {
|
||
public init() {}
|
||
}
|
||
|
||
public struct UnexpectedAppendCommand: Error {
|
||
public init() {}
|
||
}
|
||
|
||
public struct UnexpectedResponse: Error {
|
||
public var kind: Kind
|
||
public var activePromise: EventLoopPromise<Void>?
|
||
|
||
public init(
|
||
kind: Kind,
|
||
activePromise: EventLoopPromise<Void>? = nil
|
||
) {
|
||
self.kind = kind
|
||
self.activePromise = activePromise
|
||
}
|
||
|
||
/// Used to give more context about where the unexpected response was encountered.
|
||
public enum Kind: Equatable, Sendable {
|
||
case commandCompletionWithUnknownTag(tag: Command.Tag)
|
||
case appendNotWaitingForTaggedResponse
|
||
case appendWaitingForTaggedResponse
|
||
case appendWithPendingContinuation
|
||
case expectingLiteralContinuationRequest
|
||
case taggedWhileExpectingContinuationRequest
|
||
case errorState
|
||
case authenticationChallenge
|
||
case idleWaitingForConfirmation
|
||
case idleStarted
|
||
case idleRunning
|
||
case authentication
|
||
case authenticationFinished
|
||
case authenticationWaitingForChallengeResponse
|
||
}
|
||
}
|
||
|
||
public struct UnexpectedChunk: Error {
|
||
public init() {}
|
||
}
|
||
|
||
public struct UnexpectedContinuationRequest: Error {
|
||
public var kind: Kind
|
||
|
||
public init(
|
||
kind: Kind
|
||
) {
|
||
self.kind = kind
|
||
}
|
||
|
||
/// Used to give more context about where the unexpected continuation request was encountered.
|
||
public enum Kind: Equatable, Sendable {
|
||
case append
|
||
case append2
|
||
case authentication
|
||
case idle
|
||
case normal
|
||
}
|
||
}
|
||
|
||
public struct DuplicateCommandTag: Error {
|
||
public var tag: Command.Tag
|
||
|
||
public init(tag: Command.Tag) {
|
||
self.tag = tag
|
||
}
|
||
}
|
||
|
||
public struct InvalidCommandForState: Error, Equatable {
|
||
public var command: CommandStreamPart
|
||
|
||
public init(_ command: CommandStreamPart) {
|
||
self.command = command
|
||
}
|
||
}
|
||
|
||
extension InvalidCommandForState: CustomStringConvertible, CustomDebugStringConvertible {
|
||
/// A textual representation of the error with all _personally identifiable information_ in
|
||
/// ``command`` redacted.
|
||
///
|
||
/// `command` can carry sensitive data — e.g. an `AUTHENTICATE` continuation response holding
|
||
/// credentials — so the default (reflective) description is overridden to route ``command``
|
||
/// through ``CommandStreamPart/descriptionWithoutPII(_:)`` and avoid leaking it into logs.
|
||
public var description: String {
|
||
"InvalidCommandForState(\(CommandStreamPart.descriptionWithoutPII([self.command])))"
|
||
}
|
||
|
||
public var debugDescription: String {
|
||
self.description
|
||
}
|
||
}
|
||
|
||
struct OutgoingChunk: Equatable {
|
||
var bytes: ByteBuffer
|
||
var promise: EventLoopPromise<Void>?
|
||
var shouldSucceedPromise: Bool
|
||
|
||
static func == (lhs: OutgoingChunk, rhs: OutgoingChunk) -> Bool {
|
||
lhs.shouldSucceedPromise == rhs.shouldSucceedPromise && lhs.bytes == rhs.bytes
|
||
&& lhs.promise?.futureResult === rhs.promise?.futureResult
|
||
}
|
||
}
|
||
|
||
/// What the handler does for a command part the state machine released.
|
||
enum OutboundAction: Equatable {
|
||
/// Write the chunk.
|
||
case write(OutgoingChunk)
|
||
/// Succeed the promise without writing anything: the part has nothing left to do on the wire,
|
||
/// e.g. `DONE` for an `IDLE` the server rejected.
|
||
case succeed(EventLoopPromise<Void>?)
|
||
|
||
static func == (lhs: OutboundAction, rhs: OutboundAction) -> Bool {
|
||
switch (lhs, rhs) {
|
||
case (.write(let lhs), .write(let rhs)):
|
||
lhs == rhs
|
||
case (.succeed(let lhs), .succeed(let rhs)):
|
||
lhs?.futureResult === rhs?.futureResult
|
||
case (.write, _), (.succeed, _):
|
||
false
|
||
}
|
||
}
|
||
|
||
/// The chunk to write, or `nil` if this is not a write.
|
||
var chunk: OutgoingChunk? {
|
||
guard case .write(let chunk) = self else { return nil }
|
||
return chunk
|
||
}
|
||
}
|
||
|
||
// TODO: See note below.
|
||
// This state machine could potentially be improved by
|
||
// splitting into 2. One that manages command logic
|
||
// (can this command be sent), and one that handles
|
||
// continuation logic once a command has been given the
|
||
// ok.
|
||
struct ClientStateMachine {
|
||
struct ActiveEncodeContext: Equatable {
|
||
private var buffer: CommandEncodeBuffer
|
||
private var promise: EventLoopPromise<Void>?
|
||
|
||
init(buffer: CommandEncodeBuffer, promise: EventLoopPromise<Void>?) {
|
||
self.buffer = buffer
|
||
self.promise = promise
|
||
}
|
||
|
||
mutating func drop() -> EventLoopPromise<Void>? {
|
||
defer {
|
||
self.promise = nil
|
||
self.buffer = .init(buffer: ByteBuffer(), capabilities: .init(), loggingMode: false)
|
||
}
|
||
return self.promise
|
||
}
|
||
|
||
mutating func nextChunk() -> OutgoingChunk {
|
||
let chunk = self.buffer.buffer.nextChunk()
|
||
let promise = self.promise
|
||
return .init(bytes: chunk.bytes, promise: promise, shouldSucceedPromise: !chunk.waitForContinuation)
|
||
}
|
||
|
||
static func == (
|
||
lhs: ClientStateMachine.ActiveEncodeContext,
|
||
rhs: ClientStateMachine.ActiveEncodeContext
|
||
) -> Bool {
|
||
lhs.buffer == rhs.buffer && lhs.promise?.futureResult == rhs.promise?.futureResult
|
||
}
|
||
}
|
||
|
||
enum ContinuationRequestAction: Equatable {
|
||
case sendChunks([OutgoingChunk])
|
||
/// Write the chunks — a `DONE` held back for the confirmation, and what was queued
|
||
/// behind it — then forward `.idleStarted`.
|
||
case fireIdleStarted([OutgoingChunk])
|
||
case fireAuthenticationChallenge
|
||
}
|
||
|
||
enum State: Equatable {
|
||
/// We're expecting either a tagged or untagged response
|
||
case expectingNormalResponse
|
||
|
||
/// We're in some part of the idle flow
|
||
case idle(ClientStateMachine.Idle)
|
||
|
||
/// The server rejected IDLE instead of confirming it. Like `.expectingNormalResponse`,
|
||
/// except that the `DONE` the client may still send for that IDLE is absorbed: it has
|
||
/// nothing to end. The next command sent leaves this state.
|
||
case idleRejected
|
||
|
||
/// We're in some part of the authentication flow
|
||
case authenticating(ClientStateMachine.Authentication)
|
||
|
||
/// We're in some part of the appending flow
|
||
case appending(ClientStateMachine.Append)
|
||
|
||
/// We've sent a command that requires a continuation request
|
||
/// for example `A1 LOGIN {1}\r\n\\ {1}\r\n\\`, and
|
||
/// we're waiting for the continuation request from the server
|
||
/// before sending another chunk.
|
||
case expectingLiteralContinuationRequest(ActiveEncodeContext)
|
||
|
||
/// An error has occurred and the connection should
|
||
/// now be closed.
|
||
case error
|
||
}
|
||
|
||
var encodingOptions: ClientEncodingOptions
|
||
|
||
var state: State = .expectingNormalResponse
|
||
private var activeCommandTags: Set<Command.Tag> = []
|
||
private var allocator: ByteBufferAllocator!
|
||
|
||
// We mark where we should write up to at the next opportunity
|
||
// using the `flush` method called from the channel handler.
|
||
private var queuedCommands: MarkedCircularBuffer<(CommandStreamPart, EventLoopPromise<Void>?)> = .init(
|
||
initialCapacity: 16
|
||
)
|
||
|
||
init(encodingOptions: IMAPClientHandler.EncodingOptions) {
|
||
self.encodingOptions = ClientEncodingOptions(
|
||
userOptions: encodingOptions
|
||
)
|
||
}
|
||
|
||
mutating func handlerAdded(_ allocator: ByteBufferAllocator) {
|
||
self.allocator = allocator
|
||
}
|
||
|
||
/// Tells the state machine that a continuation request has been received from the network.
|
||
/// Returns the next batch of chunks to write.
|
||
mutating func receiveContinuationRequest(_ req: ContinuationRequest) throws -> ContinuationRequestAction {
|
||
do {
|
||
return try self._receiveContinuationRequest(req)
|
||
} catch {
|
||
self.state = .error
|
||
throw error
|
||
}
|
||
}
|
||
|
||
private mutating func _receiveContinuationRequest(_ req: ContinuationRequest) throws -> ContinuationRequestAction {
|
||
switch self.state {
|
||
case .appending:
|
||
return try self.receiveContinuationRequest_appending(request: req)
|
||
case .expectingLiteralContinuationRequest:
|
||
return try self.receiveContinuationRequest_expectingLiteralContinuationRequest(request: req)
|
||
case .authenticating:
|
||
return try self.receiveContinuationRequest_authenticating(request: req)
|
||
case .idle:
|
||
return try self.receiveContinuationRequest_idle(request: req)
|
||
case .expectingNormalResponse, .idleRejected, .error:
|
||
throw UnexpectedContinuationRequest(kind: .normal)
|
||
}
|
||
}
|
||
|
||
/// Tells the state machine that some response has been received. Returns what to do for the
|
||
/// command parts the response released, e.g. those queued behind a `DONE` for an IDLE the
|
||
/// server rejected.
|
||
mutating func receiveResponse(_ response: Response) throws -> [OutboundAction] {
|
||
do {
|
||
return try self._receiveResponse(response)
|
||
} catch {
|
||
self.state = .error
|
||
throw error
|
||
}
|
||
}
|
||
|
||
mutating func _receiveResponse(_ response: Response) throws -> [OutboundAction] {
|
||
if let tag = response.tag {
|
||
guard self.activeCommandTags.remove(tag) != nil else {
|
||
throw UnexpectedResponse(
|
||
kind: .commandCompletionWithUnknownTag(tag: tag)
|
||
)
|
||
}
|
||
}
|
||
|
||
switch self.state {
|
||
case .idle(let idleStateMachine):
|
||
switch try idleStateMachine.receiveResponse(response) {
|
||
case .continueIdling:
|
||
break
|
||
case .rejected:
|
||
return try self.idleWasRejected()
|
||
}
|
||
case .authenticating(var authStateMachine):
|
||
try authStateMachine.receiveResponse(response)
|
||
self.state = .expectingNormalResponse
|
||
case .appending(var appendStateMachine):
|
||
switch try appendStateMachine.receiveResponse(response) {
|
||
case .doneAppending:
|
||
self.state = .expectingNormalResponse
|
||
case .continueAppending:
|
||
self.state = .appending(appendStateMachine)
|
||
}
|
||
case .error:
|
||
throw UnexpectedResponse(
|
||
kind: .errorState
|
||
)
|
||
case .expectingNormalResponse, .idleRejected, .expectingLiteralContinuationRequest:
|
||
// If we’re expecting a Continuation Request, we should still
|
||
// allow all normal responses. They may arrive due to timing.
|
||
// The server may have sent these before we sent the data that
|
||
// moved us into this state.
|
||
switch response {
|
||
case .untagged, .fetch:
|
||
// we expected a normal response and received a normal
|
||
// response, nothing to see here
|
||
break
|
||
case .tagged:
|
||
// If we’re expecting a Continuation Request, and we received a command
|
||
// completion, we need to make sure that it didn’t complete the command
|
||
// that we are still in the process of sending. We can’t really do that
|
||
// here due to how ClientStateMachine is structured, but we’ll at least
|
||
// check that there’s _some_ command running.
|
||
if case .expectingLiteralContinuationRequest(var context) = self.state {
|
||
guard !self.activeCommandTags.isEmpty else {
|
||
let promise = context.drop()
|
||
throw UnexpectedResponse(
|
||
kind: .taggedWhileExpectingContinuationRequest,
|
||
activePromise: promise
|
||
)
|
||
}
|
||
}
|
||
case .fatal:
|
||
// if the server has sent a fatal then we shouldn't be able to do anything else
|
||
self.state = .error
|
||
case .authenticationChallenge:
|
||
// We should be in a substate
|
||
throw UnexpectedResponse(
|
||
kind: .authenticationChallenge
|
||
)
|
||
case .idleStarted:
|
||
// We should be in a substate
|
||
throw UnexpectedResponse(
|
||
kind: .idleStarted
|
||
)
|
||
}
|
||
}
|
||
return []
|
||
}
|
||
|
||
/// Tells the state machine that the client would like to send a command.
|
||
/// We then return any chunks that can be written.
|
||
mutating func sendCommand(
|
||
_ command: CommandStreamPart,
|
||
promise: EventLoopPromise<Void>? = nil
|
||
) throws -> OutboundAction? {
|
||
guard
|
||
self.state != .error
|
||
else { throw InvalidClientState() }
|
||
|
||
// The server rejected the IDLE this DONE would end, so there's nothing to write.
|
||
if self.state == .idleRejected, command == .idleDone {
|
||
self.state = .expectingNormalResponse
|
||
return .succeed(promise)
|
||
}
|
||
|
||
if let tag = command.tag {
|
||
let (inserted, _) = self.activeCommandTags.insert(tag)
|
||
guard inserted else {
|
||
throw DuplicateCommandTag(tag: tag)
|
||
}
|
||
}
|
||
self.queuedCommands.append((command, promise))
|
||
|
||
// Sends the oldest queued command; its promise is never completed if that throws. See #858.
|
||
if let result = try self.sendNextCommand() {
|
||
// There can only be one chunk
|
||
// 1. if first has a continuation then we will be in the continuation state
|
||
// 2. if first doesn't have a continuation then there won't be a next chunk
|
||
precondition(result.chunks.count == 1)
|
||
return .write(result.chunks.first!)
|
||
}
|
||
return nil
|
||
}
|
||
|
||
/// Mark the back of the current command queue, and write up to and including
|
||
/// this point next time we receive a continuation request or send a command.
|
||
/// Note that we might not actually reach the mark as we may encounter a command
|
||
/// that requires a continuation request.
|
||
///
|
||
/// Returns what can be written right away: commands a continuation request released before
|
||
/// they were flushed, e.g. a `DONE` written before the server's `+`, but flushed after it.
|
||
mutating func flush() throws -> [OutgoingChunk] {
|
||
self.queuedCommands.mark()
|
||
guard self.state != .error, !self.isWaitingForContinuationRequest, !self.queuedCommands.isEmpty else {
|
||
return []
|
||
}
|
||
do {
|
||
// Promises dequeued before a throw are never completed; see #858.
|
||
return try self.extractSendableChunks().chunks
|
||
} catch {
|
||
self.state = .error
|
||
throw error
|
||
}
|
||
}
|
||
|
||
/// Returns all of the promises for the writes that have not yet completed.
|
||
/// These should probably be failed.
|
||
mutating func channelInactive() -> [EventLoopPromise<Void>] {
|
||
var activeEncodeContext: ActiveEncodeContext?
|
||
switch self.state {
|
||
case .expectingNormalResponse, .idleRejected, .error, .appending, .authenticating, .idle:
|
||
break
|
||
case .expectingLiteralContinuationRequest(let _activeEncodeContext):
|
||
activeEncodeContext = _activeEncodeContext
|
||
}
|
||
|
||
// we don't care what state we were in, all we want is
|
||
// to move to the error state so that nothing else is sent
|
||
self.state = .error
|
||
|
||
var promises: [EventLoopPromise<Void>] = []
|
||
if let promise = activeEncodeContext?.drop() {
|
||
promises.append(promise)
|
||
}
|
||
|
||
promises.append(contentsOf: self.queuedCommands.compactMap(\.1))
|
||
return promises
|
||
}
|
||
}
|
||
|
||
// MARK: - Receive
|
||
|
||
extension ClientStateMachine {
|
||
private mutating func receiveContinuationRequest_appending(
|
||
request: ContinuationRequest
|
||
) throws -> ContinuationRequestAction {
|
||
guard case .appending(var appendingStateMachine) = self.state
|
||
else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
try appendingStateMachine.receiveContinuationRequest(request)
|
||
self.state = .appending(appendingStateMachine)
|
||
return try .sendChunks(self.extractSendableChunks().chunks)
|
||
}
|
||
|
||
private mutating func receiveContinuationRequest_expectingLiteralContinuationRequest(
|
||
request: ContinuationRequest
|
||
) throws -> ContinuationRequestAction {
|
||
guard case .expectingLiteralContinuationRequest(let context) = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
|
||
self.state = .expectingNormalResponse
|
||
// Promises dequeued before a throw are never completed; see #858.
|
||
let result = try self.extractSendableChunks(currentContext: context)
|
||
|
||
// safe to bang as if we've successfully received a
|
||
// continuation request then MUST be something to send
|
||
if let nextContext = result.nextContext { // we've found another continuation
|
||
self.state = .expectingLiteralContinuationRequest(nextContext)
|
||
} else {
|
||
self.state = .expectingNormalResponse
|
||
}
|
||
return .sendChunks(result.chunks)
|
||
}
|
||
|
||
private mutating func receiveContinuationRequest_authenticating(
|
||
request: ContinuationRequest
|
||
) throws -> ContinuationRequestAction {
|
||
guard case .authenticating(var authenticatingStateMachine) = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
|
||
switch request {
|
||
case .responseText:
|
||
// no valid base 64, so we can assume it was empty
|
||
try authenticatingStateMachine.receiveContinuationRequest(.data(ByteBuffer()))
|
||
self.state = .authenticating(authenticatingStateMachine)
|
||
case .data(let byteBuffer):
|
||
try authenticatingStateMachine.receiveContinuationRequest(.data(byteBuffer))
|
||
self.state = .authenticating(authenticatingStateMachine)
|
||
}
|
||
return .fireAuthenticationChallenge
|
||
}
|
||
|
||
private mutating func receiveContinuationRequest_idle(
|
||
request: ContinuationRequest
|
||
) throws -> ContinuationRequestAction {
|
||
guard case .idle(var idleStateMachine) = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
|
||
// A continuation when in idle state means it's been confirmed
|
||
try idleStateMachine.receiveContinuationRequest(request)
|
||
self.state = .idle(idleStateMachine)
|
||
// A DONE held back for the confirmation, and what was queued behind it, can go out now.
|
||
// Promises dequeued before a throw are never completed; see #858.
|
||
return try .fireIdleStarted(self.extractSendableChunks().chunks)
|
||
}
|
||
|
||
/// The server rejected IDLE, so a `DONE` for it has nothing to end: drop a held one, and send
|
||
/// what was queued behind it.
|
||
private mutating func idleWasRejected() throws -> [OutboundAction] {
|
||
var actions: [OutboundAction] = []
|
||
if self.queuedCommands.first?.0 == .idleDone {
|
||
let (_, promise) = self.queuedCommands.popFirst()!
|
||
actions.append(.succeed(promise))
|
||
self.state = .expectingNormalResponse
|
||
} else {
|
||
self.state = .idleRejected
|
||
}
|
||
// Promises dequeued before a throw are never completed; see #858.
|
||
return try actions + self.extractSendableChunks().chunks.map(OutboundAction.write)
|
||
}
|
||
}
|
||
|
||
// MARK: - Send
|
||
|
||
extension ClientStateMachine {
|
||
private mutating func sendTaggedCommand(
|
||
_ command: TaggedCommand,
|
||
promise: EventLoopPromise<Void>?
|
||
) -> SendableChunks {
|
||
guard case .expectingNormalResponse = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
|
||
let buffer = self.makeEncodeBuffer(.tagged(command))
|
||
var context = ActiveEncodeContext(buffer: buffer, promise: promise)
|
||
|
||
switch command.command {
|
||
case .idleStart:
|
||
// Traps if another command, e.g. the previous IDLE, still awaits its tagged response,
|
||
// instead of failing the connection; see #858.
|
||
self.guardAgainstMultipleRunningCommands()
|
||
self.state = .idle(Idle(tag: command.tag))
|
||
return .init(chunks: [context.nextChunk()], nextContext: nil)
|
||
case .authenticate:
|
||
self.guardAgainstMultipleRunningCommands()
|
||
self.state = .authenticating(Authentication())
|
||
return .init(chunks: [context.nextChunk()], nextContext: nil)
|
||
default:
|
||
let chunk = context.nextChunk()
|
||
|
||
// if we're meant to succeed the promise then there can't be any next context
|
||
guard chunk.shouldSucceedPromise else {
|
||
self.state = .expectingLiteralContinuationRequest(context)
|
||
return .init(chunks: [chunk], nextContext: context)
|
||
}
|
||
precondition(context.nextChunk().bytes.readableBytes == 0)
|
||
self.state = .expectingNormalResponse
|
||
return .init(chunks: [chunk], nextContext: nil)
|
||
}
|
||
}
|
||
|
||
private mutating func sendAppendCommand(
|
||
_ command: AppendCommand,
|
||
promise: EventLoopPromise<Void>?
|
||
) throws -> SendableChunks {
|
||
guard case .expectingNormalResponse = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
guard let tag = command.tag else {
|
||
throw UnexpectedAppendCommand()
|
||
}
|
||
|
||
// no other commands can be running when we start appending
|
||
self.state = .appending(Append(tag: tag))
|
||
|
||
// TODO: This assumes that the append command doesn't require a continuation - fix this in another PR
|
||
let buffer = self.makeEncodeBuffer(.append(command))
|
||
var context = ActiveEncodeContext(buffer: buffer, promise: promise)
|
||
return .init(chunks: [context.nextChunk()], nextContext: nil)
|
||
}
|
||
|
||
/// Iterate through the current command queue until we reached the marked position
|
||
/// or encounter a command that requires a continuation request to complete.
|
||
|
||
struct SendableChunks {
|
||
var chunks: [OutgoingChunk]
|
||
var nextContext: ActiveEncodeContext?
|
||
}
|
||
|
||
private mutating func extractSendableChunks(currentContext: ActiveEncodeContext? = nil) throws -> SendableChunks {
|
||
var results: [OutgoingChunk] = []
|
||
if var currentContext = currentContext {
|
||
let chunk = currentContext.nextChunk()
|
||
guard chunk.shouldSucceedPromise else {
|
||
self.state = .expectingLiteralContinuationRequest(currentContext)
|
||
return .init(chunks: [chunk], nextContext: currentContext)
|
||
}
|
||
results.append(chunk)
|
||
}
|
||
|
||
while self.queuedCommands.hasMark, let sendableChunk = try self.sendNextCommand() {
|
||
results.append(contentsOf: sendableChunk.chunks)
|
||
if let context = sendableChunk.nextContext {
|
||
return .init(chunks: results, nextContext: context)
|
||
}
|
||
}
|
||
|
||
return .init(chunks: results, nextContext: nil)
|
||
}
|
||
|
||
/// Throws an error if more than one command is running, otherwise does nothing.
|
||
/// End users are required to ensure command pipelining compatibility.
|
||
private func guardAgainstMultipleRunningCommands() {
|
||
precondition(self.activeCommandTags.count == 1)
|
||
}
|
||
|
||
private func makeEncodeBuffer(_ command: CommandStreamPart? = nil) -> CommandEncodeBuffer {
|
||
let byteBuffer = self.allocator.buffer(capacity: 128)
|
||
var encodeBuffer = CommandEncodeBuffer(
|
||
buffer: byteBuffer,
|
||
options: self.encodingOptions.encodingOptions,
|
||
loggingMode: false
|
||
)
|
||
if let command = command {
|
||
encodeBuffer.writeCommandStream(command)
|
||
}
|
||
return encodeBuffer
|
||
}
|
||
|
||
var isWaitingForContinuationRequest: Bool {
|
||
switch self.state {
|
||
case .appending(let sub):
|
||
sub.isWaitingForContinuationRequest
|
||
case .idle(let sub):
|
||
sub.isWaitingForContinuationRequest
|
||
case .expectingLiteralContinuationRequest:
|
||
true
|
||
case .expectingNormalResponse, .idleRejected, .authenticating, .error:
|
||
false
|
||
}
|
||
}
|
||
|
||
private mutating func sendNextCommand() throws -> SendableChunks? {
|
||
guard !isWaitingForContinuationRequest else { return nil }
|
||
|
||
guard let (command, promise) = self.queuedCommands.popFirst() else {
|
||
preconditionFailure("You can't send a non-existent command")
|
||
}
|
||
|
||
switch self.state {
|
||
case .expectingNormalResponse:
|
||
return try self.sendNextCommand_expectingNormalResponse(command: command, promise: promise)
|
||
case .idleRejected:
|
||
// The next command ends the tolerance for a late DONE; a DONE behind it is out of context.
|
||
self.state = .expectingNormalResponse
|
||
return try self.sendNextCommand_expectingNormalResponse(command: command, promise: promise)
|
||
case .idle:
|
||
return self.sendNextCommand_idle(command: command, promise: promise)
|
||
case .authenticating:
|
||
return self.sendNextCommand_authenticating(command: command, promise: promise)
|
||
case .appending:
|
||
return self.sendNextCommand_appending(command: command, promise: promise)
|
||
case .expectingLiteralContinuationRequest:
|
||
// if we're waiting for a continuation request
|
||
// the by definition we can't do anything
|
||
return nil
|
||
case .error:
|
||
preconditionFailure("Already in error state, make sure to handle errors appropriately.")
|
||
}
|
||
}
|
||
|
||
/// If we're "expecting a normal response" then we aren't waiting for a continuation request. However, the
|
||
/// command we want to send may require a continuation itself. We begin by writing the command to
|
||
/// an encode buffer to isolate any required continuations, and then send every chunk until we run out of chunks
|
||
/// to send, or we find a chunk that requires a continuation request.
|
||
private mutating func sendNextCommand_expectingNormalResponse(
|
||
command: CommandStreamPart,
|
||
promise: EventLoopPromise<Void>?
|
||
) throws -> SendableChunks {
|
||
guard case .expectingNormalResponse = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
|
||
switch command {
|
||
case .idleDone, .continuationResponse:
|
||
// These can only arrive here if a malformed or forwarded command is fed to the state
|
||
// machine out of context (e.g. a spurious `.continuationResponse` parsed from
|
||
// untrusted bytes). Throw rather than crash the process.
|
||
throw InvalidCommandForState(command)
|
||
case .tagged(let tc):
|
||
return self.sendTaggedCommand(tc, promise: promise)
|
||
case .append(let ac):
|
||
return try self.sendAppendCommand(ac, promise: promise)
|
||
}
|
||
}
|
||
|
||
/// When idle we need to first defer to the idle state machine to make sure we can send the
|
||
/// the next part of the authentication. If we can, then just send the message. There's no need
|
||
/// to wait for a continuation request.
|
||
private mutating func sendNextCommand_idle(
|
||
command: CommandStreamPart,
|
||
promise: EventLoopPromise<Void>?
|
||
) -> SendableChunks {
|
||
guard case .idle(var idleStateMachine) = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
// Traps instead of failing the connection; see #858.
|
||
guard command == .idleDone else {
|
||
preconditionFailure("Invalid command when idle \(command)")
|
||
}
|
||
|
||
idleStateMachine.sendCommand(command)
|
||
self.state = .expectingNormalResponse
|
||
var encodeBuffer = self.makeEncodeBuffer(command)
|
||
let chunk = encodeBuffer.buffer.nextChunk()
|
||
precondition(!chunk.waitForContinuation)
|
||
return .init(
|
||
chunks: [.init(bytes: chunk.bytes, promise: promise, shouldSucceedPromise: true)],
|
||
nextContext: nil
|
||
)
|
||
}
|
||
|
||
/// When authenticating we need to first defer to the authentication state machine to make sure
|
||
/// can send the next part of the authentication. If we can, then just send the message. There's
|
||
/// no need to wait for a continuation request.
|
||
private mutating func sendNextCommand_authenticating(
|
||
command: CommandStreamPart,
|
||
promise: EventLoopPromise<Void>?
|
||
) -> SendableChunks {
|
||
guard case .authenticating(var authenticatingStateMachine) = self.state else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
guard case .continuationResponse(let data) = command else {
|
||
preconditionFailure("Continuation responses only")
|
||
}
|
||
|
||
authenticatingStateMachine.sendCommand(command)
|
||
self.state = .authenticating(authenticatingStateMachine)
|
||
var encodeBuffer = self.makeEncodeBuffer(.continuationResponse(data))
|
||
let chunk = encodeBuffer.buffer.nextChunk()
|
||
precondition(!chunk.waitForContinuation)
|
||
return .init(
|
||
chunks: [.init(bytes: chunk.bytes, promise: promise, shouldSucceedPromise: true)],
|
||
nextContext: nil
|
||
)
|
||
}
|
||
|
||
/// When appending we need to first defer to the appending state machine to see if we can actually
|
||
/// send a command given our current state. If we can then we need to check what kind of command
|
||
/// is being sent. If we're beginning an append or catenation then we need to wait for a continuation
|
||
/// request, otherwise we can send the command and continue.
|
||
private mutating func sendNextCommand_appending(
|
||
command: CommandStreamPart,
|
||
promise: EventLoopPromise<Void>?
|
||
) -> SendableChunks? {
|
||
guard case .appending(var appendingStateMachine) = self.state
|
||
else {
|
||
preconditionFailure("Invalid state: \(self.state)")
|
||
}
|
||
guard case .append(let command) = command else {
|
||
preconditionFailure("Append commands only in this state")
|
||
}
|
||
|
||
// If we're pending a continuation (e.g. after sending a message literal header)
|
||
// then we can't write the command yet.
|
||
guard !appendingStateMachine.isWaitingForContinuationRequest else {
|
||
return nil
|
||
}
|
||
|
||
// Workaround: Using non-synchronizing literals is broken for APPEND.
|
||
var encodingOptions = self.encodingOptions.encodingOptions
|
||
encodingOptions.useSynchronizingLiteral = true
|
||
encodingOptions.useNonSynchronizingLiteralPlus = false
|
||
encodingOptions.useNonSynchronizingLiteralMinus = false
|
||
|
||
var encodeBuffer = CommandEncodeBuffer(
|
||
buffer: ByteBuffer(),
|
||
options: encodingOptions,
|
||
encodedAtLeastOneCatenateElement: appendingStateMachine.hasCatenatedAtLeastOneObject,
|
||
loggingMode: false
|
||
)
|
||
encodeBuffer.writeCommandStream(.append(command))
|
||
|
||
appendingStateMachine.sendCommand(.append(command))
|
||
let chunk = encodeBuffer.buffer.nextChunk()
|
||
self.state = .appending(appendingStateMachine)
|
||
|
||
// We always need append commands to be sent instantly so we can receive continuations
|
||
// so the write promise should always be succeeded.
|
||
return .init(
|
||
chunks: [.init(bytes: chunk.bytes, promise: promise, shouldSucceedPromise: true)],
|
||
nextContext: nil
|
||
)
|
||
}
|
||
}
|