Files
swift-nio-imap/Sources/NIOIMAPCore/EncodeBuffer.swift
T
Franz Busch 2cd1c5582a [CI] Adopt GitHub Actions (#775)
* [CI] Adopt GitHub Actions

# Motivation

We want to adopt GitHub actions in all of our Swift repositories to replace our current Jenkins CI.

# Modification

This PR adopts the reusable workflows from NIO and the swiftlang organization to ensure soundness and test coverage. Additionally, this PR enables a sematic label check and adds a `release.yml` to make releasing this package easy.

# Result

Modern CI and release flow.
2024-10-30 13:24:35 +00:00

213 lines
8.3 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
//
//===----------------------------------------------------------------------===//
import struct NIO.ByteBuffer
import struct NIO.ByteBufferView
import struct NIO.CircularBuffer
/// A buffer that handles encoding of Swift types into IMAP commands/responses that
/// will be sent/recieved by clients and servers.
@_spi(NIOIMAPInternal) public struct EncodeBuffer: Hashable, Sendable {
/// Used to define if the buffer should act as a client or server.
public enum Mode: Hashable, Sendable {
/// Act as a client using the given `CommandEncodingOptions`.
case client(options: CommandEncodingOptions)
/// Act as a server using the given `ResponseEncodingOptions`.
case server(streamingAttributes: Bool, options: ResponseEncodingOptions)
}
public var loggingMode: Bool
internal var mode: Mode
@usableFromInline internal var buffer: ByteBuffer
@usableFromInline internal var stopPoints: CircularBuffer<Int> = []
init(_ buffer: ByteBuffer, mode: Mode, loggingMode: Bool) {
self.buffer = buffer
self.mode = mode
self.loggingMode = loggingMode
}
}
extension EncodeBuffer {
/// Creates a new `EncodeBuffer` suitable for a client to write commands.
/// - parameter buffer: An initial `ByteBuffer` to write to. Note that this is copied and not taken as `inout`.
/// - parameter options: Configuration to use when writing.
/// - returns: A new `EncodeBuffer` configured for client use.
static func clientEncodeBuffer(
buffer: ByteBuffer,
options: CommandEncodingOptions,
loggingMode: Bool
) -> EncodeBuffer {
EncodeBuffer(buffer, mode: .client(options: options), loggingMode: loggingMode)
}
/// Creates a new `EncodeBuffer` suitable for a client to write commands.
/// - parameter buffer: An initial `ByteBuffer` to write to. Note that this is copied and not taken as `inout`.
/// - parameter options: Configuration to use when writing.
/// - returns: A new `EncodeBuffer` configured for client use.
static func clientEncodeBuffer(buffer: ByteBuffer, capabilities: [Capability], loggingMode: Bool) -> EncodeBuffer {
clientEncodeBuffer(
buffer: buffer,
options: CommandEncodingOptions(capabilities: capabilities),
loggingMode: loggingMode
)
}
/// Creates a new `EncodeBuffer` suitable for a client to write commands.
/// - parameter buffer: An initial `ByteBuffer` to write to. Note that this is copied and not taken as `inout`.
/// - parameter options: Configuration to use when writing.
/// - returns: A new `EncodeBuffer` configured for server use.
static func serverEncodeBuffer(
buffer: ByteBuffer,
options: ResponseEncodingOptions,
loggingMode: Bool
) -> EncodeBuffer {
EncodeBuffer(buffer, mode: .server(streamingAttributes: false, options: options), loggingMode: loggingMode)
}
/// Creates a new `EncodeBuffer` suitable for a client to write commands.
/// - parameter buffer: An initial `ByteBuffer` to write to. Note that this is copied and not taken as `inout`.
/// - parameter options: Configuration to use when writing.
/// - returns: A new `EncodeBuffer` configured for server use.
static func serverEncodeBuffer(buffer: ByteBuffer, capabilities: [Capability], loggingMode: Bool) -> EncodeBuffer {
serverEncodeBuffer(
buffer: buffer,
options: ResponseEncodingOptions(capabilities: capabilities),
loggingMode: loggingMode
)
}
}
extension EncodeBuffer {
/// Call the closure with a buffer, return the result as a String.
///
/// Used for implementing ``CustomDebugStringConvertible`` conformance.
static func makeDescription(_ closure: (inout EncodeBuffer) -> Void) -> String {
var options = CommandEncodingOptions.rfc3501
options.useQuotedString = true
options.useSynchronizingLiteral = false
options.useNonSynchronizingLiteralPlus = true
var buffer = EncodeBuffer.clientEncodeBuffer(buffer: ByteBuffer(), options: options, loggingMode: false)
closure(&buffer)
return String(bestEffortDecodingUTF8Bytes: buffer.buffer.readableBytesView)
}
}
extension EncodeBuffer {
/// Represents a piece of data that is ready to be written to the network.
public struct Chunk: Hashable, Sendable {
/// The data that is ready to be written.
public var bytes: ByteBuffer
/// Is a continuation request expected before this data can be written?
public var waitForContinuation: Bool
}
@_spi(NIOIMAPInternal) var hasChunks: Bool {
self.stopPoints.count > 0
}
/// Gets the next chunk that is ready to be written to the network.
/// - returns: The next chunk that is ready to be written.
public mutating func nextChunk() -> Chunk {
self.nextChunk(allowEmptyChunk: true)
}
/// Gets the next chunk that is ready to be written to the network.
/// *NOTE*: Use This function with caution. You probably shouldn't be using it, using nextChunk() instead.
/// - returns: The next chunk that is ready to be written.
@_spi(NIOIMAPInternal) public mutating func nextChunk(allowEmptyChunk: Bool) -> Chunk {
switch self.mode {
case .client:
guard let stopPoint = self.stopPoints.popFirst() else {
precondition(allowEmptyChunk || self.buffer.readableBytes > 0, "No next chunk to send.")
return .init(
bytes: self.buffer.readSlice(length: self.buffer.readableBytes)!,
waitForContinuation: false
)
}
return .init(
bytes: self.buffer.readSlice(length: stopPoint - self.buffer.readerIndex)!,
waitForContinuation: stopPoint != self.buffer.writerIndex
)
case .server:
return .init(bytes: self.buffer.readSlice(length: self.buffer.readableBytes)!, waitForContinuation: false)
}
}
/// Marks the end of the current `Chunk`.
@discardableResult
public mutating func markStopPoint() -> Int {
if case .client = mode {
stopPoints.append(buffer.writerIndex)
}
return 0
}
}
extension EncodeBuffer {
/// Writes a raw `String` to the buffer.
/// - parameter string: The string to write.
/// - returns: The number of bytes written - always `string.utf8.count`.
@discardableResult
@inlinable
public mutating func writeString(_ string: String) -> Int {
self.buffer.writeString(string)
}
/// Writes raw bytes to the buffer.
/// - parameter buffer: The bytes to write.
/// - returns: The number of bytes written - always equal to the size of `bytes`.
@discardableResult
@inlinable
public mutating func writeBytes<Bytes: Sequence>(_ bytes: Bytes) -> Int where Bytes.Element == UInt8 {
guard loggingMode else {
return self.buffer.writeBytes(bytes)
}
return self.buffer.writeString("[\(Array(bytes).count) bytes]")
}
/// Writes a `ByteBuffer` to the buffer.
/// - parameter buffer: The `ByteBuffer` to write.
/// - returns: The number of bytes written - always equal to `buffer.readableBytes`.
@discardableResult
@inlinable
public mutating func writeBuffer(_ buffer: inout ByteBuffer) -> Int {
guard loggingMode else {
return self.buffer.writeBuffer(&buffer)
}
return self.buffer.writeString("[\(buffer.readableBytes) bytes]")
}
/// Erases all data from the buffer.
@inlinable
public mutating func clear() {
self.stopPoints.removeAll()
self.buffer.clear()
}
}
extension EncodeBuffer {
mutating func withoutLoggingMode<R>(_ closure: (inout EncodeBuffer) -> R) -> R {
let old = self.loggingMode
defer {
self.loggingMode = old
}
self.loggingMode = false
return closure(&self)
}
}