mirror of
https://github.com/apple/swift-nio-imap
synced 2026-11-22 04:30:43 +00:00
250 lines
7.8 KiB
Swift
250 lines
7.8 KiB
Swift
//===----------------------------------------------------------------------===//
|
|
//
|
|
// 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 IMAPCommands
|
|
#if canImport(FoundationEssentials)
|
|
import FoundationEssentials
|
|
#else
|
|
import Foundation
|
|
#endif
|
|
import NIO
|
|
import NIOIMAP
|
|
|
|
/// The result of selecting a mailbox, containing its metadata.
|
|
struct SelectInfo: Hashable, Sendable {
|
|
/// The name of the selected mailbox.
|
|
var mailbox: MailboxName
|
|
/// The text from the `OK` command completion.
|
|
var responseText: ResponseText
|
|
/// The flags defined for this mailbox.
|
|
var flags: [Flag]
|
|
/// The permanent flags that can be modified in this mailbox.
|
|
var permanentFlags: [PermanentFlag]
|
|
/// The total number of messages from the `EXISTS` response.
|
|
var messageCount: Int
|
|
/// The next UID the server assigns to a new message.
|
|
var uidNext: UID
|
|
/// The UID validity value for this mailbox.
|
|
var uidValidity: UIDValidity
|
|
|
|
/// Creates a `SelectInfo` with all required fields.
|
|
init(
|
|
mailbox: MailboxName,
|
|
responseText: ResponseText,
|
|
flags: [Flag],
|
|
permanentFlags: [PermanentFlag],
|
|
messageCount: Int,
|
|
uidNext: UID,
|
|
uidValidity: UIDValidity
|
|
) {
|
|
self.mailbox = mailbox
|
|
self.responseText = responseText
|
|
self.flags = flags
|
|
self.permanentFlags = permanentFlags
|
|
self.messageCount = messageCount
|
|
self.uidNext = uidNext
|
|
self.uidValidity = uidValidity
|
|
}
|
|
}
|
|
|
|
extension SelectInfo {
|
|
init(
|
|
temp: Temporary,
|
|
response: TaggedResponse
|
|
) throws {
|
|
let responseText = try response.getOK()
|
|
guard
|
|
let flags = temp.flags
|
|
else { throw Error.missingSelectField("flags") }
|
|
guard
|
|
let permanentFlags = temp.permanentFlags
|
|
else { throw Error.missingSelectField("permanent flags") }
|
|
guard
|
|
let messageCount = temp.messageCount
|
|
else { throw Error.missingSelectField("message count") }
|
|
guard
|
|
let uidNext = temp.uidNext
|
|
else { throw Error.missingSelectField("UIDNEXT") }
|
|
guard
|
|
let uidValidity = temp.uidValidity
|
|
else { throw Error.missingSelectField("UIDVALIDITY") }
|
|
self.init(
|
|
mailbox: temp.mailbox,
|
|
responseText: responseText,
|
|
flags: flags,
|
|
permanentFlags: permanentFlags,
|
|
messageCount: messageCount,
|
|
uidNext: uidNext,
|
|
uidValidity: uidValidity
|
|
)
|
|
}
|
|
|
|
/// The in-progress version that gets updated while `SELECT` runs.
|
|
struct Temporary: Hashable, Sendable {
|
|
var mailbox: MailboxName
|
|
var flags: [Flag]?
|
|
var permanentFlags: [PermanentFlag]?
|
|
/// From `<n> EXISTS`
|
|
var messageCount: Int?
|
|
var uidNext: UID?
|
|
var uidValidity: UIDValidity?
|
|
}
|
|
|
|
enum Error: Swift.Error {
|
|
/// The `SELECT` response was missing a required untagged field. The associated
|
|
/// value names the field (e.g. `"UIDNEXT"`).
|
|
case missingSelectField(String)
|
|
}
|
|
}
|
|
|
|
/// Controls behavior when the mailbox does not exist during selection.
|
|
enum SelectCreateOption: Hashable, Sendable {
|
|
/// Fails selection if the mailbox does not exist.
|
|
case fail
|
|
/// Creates the mailbox with the given parameters if it does not exist.
|
|
case create([CreateParameter])
|
|
}
|
|
|
|
private enum FirstResult {
|
|
case success(SelectInfo)
|
|
case create([CreateParameter])
|
|
}
|
|
|
|
extension ConnectionProtocol {
|
|
/// Selects the given mailbox.
|
|
func select(
|
|
createMailbox: SelectCreateOption,
|
|
mailbox: MailboxPath
|
|
) async throws -> SelectInfo {
|
|
try await select(
|
|
mailbox: mailbox.name,
|
|
createMailbox: createMailbox
|
|
)
|
|
}
|
|
|
|
/// Selects the given mailbox, optionally creating it first.
|
|
func select(
|
|
mailbox: MailboxName,
|
|
createMailbox: SelectCreateOption
|
|
) async throws -> SelectInfo {
|
|
let info = try await selectOrCreate(
|
|
createMailbox: createMailbox,
|
|
mailbox: mailbox
|
|
)
|
|
writeStatus(
|
|
"Did select mailbox '\(mailbox)'. Message count: \(info.messageCount), UIDNEXT: \(info.uidNext), UIDVALIDITY: \(info.uidValidity)"
|
|
)
|
|
return info
|
|
}
|
|
|
|
private func selectOrCreate(
|
|
createMailbox: SelectCreateOption,
|
|
mailbox: MailboxName
|
|
) async throws -> SelectInfo {
|
|
let parameters: [CreateParameter]
|
|
switch try await trySelect(
|
|
createMailbox: createMailbox,
|
|
mailbox: mailbox
|
|
) {
|
|
case .success(let info):
|
|
return info
|
|
case .create(let p):
|
|
parameters = p
|
|
}
|
|
|
|
// Try to create:
|
|
let createText = try await send(.create(mailbox, parameters)) { tag, responses in
|
|
writeStatus("Did send CREATE with tag \(tag)")
|
|
return try await responses.waitForCompletion()
|
|
}.getOK()
|
|
writeStatus("Did CREATE: \(createText)")
|
|
// Re-try SELECT:
|
|
let (info, response) = try await sendSelect(
|
|
mailbox: mailbox
|
|
)
|
|
return try SelectInfo(
|
|
temp: info,
|
|
response: response
|
|
)
|
|
}
|
|
|
|
/// Attempts a `SELECT` and either returns the result, or — if the mailbox does not
|
|
/// exist and the caller opted in to creation — returns the parameters needed to create it.
|
|
private func trySelect(
|
|
createMailbox: SelectCreateOption,
|
|
mailbox: MailboxName
|
|
) async throws -> FirstResult {
|
|
let (info, response) = try await sendSelect(
|
|
mailbox: mailbox
|
|
)
|
|
// The only branch that diverts from the normal "construct SelectInfo" path is
|
|
// a `NO` response when the caller opted in to creating the mailbox.
|
|
// Every other state — `.ok`, `.bad`, or `.no` with `.fail` — goes through
|
|
// `SelectInfo.init`, which surfaces success or throws the underlying error.
|
|
if case .create(let parameters) = createMailbox,
|
|
case .no(let text) = response.state
|
|
{
|
|
writeStatus("Unable to SELECT mailbox — will try to create (\(text))")
|
|
return .create(parameters)
|
|
}
|
|
return try .success(
|
|
SelectInfo(
|
|
temp: info,
|
|
response: response
|
|
)
|
|
)
|
|
}
|
|
|
|
private func sendSelect(
|
|
mailbox: MailboxName
|
|
) async throws -> (SelectInfo.Temporary, TaggedResponse) {
|
|
try await send(.select(mailbox)) { _, responses in
|
|
var info = SelectInfo.Temporary(mailbox: mailbox)
|
|
let response = try await responses.forEach { response in
|
|
switch response {
|
|
case .untagged(let untagged):
|
|
info.update(untagged)
|
|
default:
|
|
break
|
|
}
|
|
}
|
|
return (info, response)
|
|
}
|
|
}
|
|
}
|
|
|
|
extension SelectInfo.Temporary {
|
|
mutating func update(_ untagged: ResponsePayload) {
|
|
switch untagged {
|
|
case .mailboxData(.flags(let f)):
|
|
flags = f
|
|
case .mailboxData(.exists(let count)):
|
|
messageCount = count
|
|
case .conditionalState(.ok(let text)):
|
|
switch text.code {
|
|
case .permanentFlags(let f):
|
|
permanentFlags = f
|
|
case .uidNext(let uid):
|
|
uidNext = uid
|
|
case .uidValidity(let v):
|
|
uidValidity = v
|
|
default:
|
|
break
|
|
}
|
|
default:
|
|
break
|
|
}
|
|
}
|
|
}
|