From 6c8cfaddccb3728c82b1ebb8efa57d8078e76a9e Mon Sep 17 00:00:00 2001 From: Daniel Eggert Date: Fri, 25 Sep 2026 16:16:41 +0100 Subject: [PATCH] Add a imperative IMAP client and an `imap-tool` CLI (#841) --- .github/workflows/main.yml | 8 +- .github/workflows/pull_request.yml | 16 +- Examples/IMAPTool/Package.swift | 71 ++ Examples/IMAPTool/Sources/IMAPTool/main.swift | 17 + .../IMAPToolLib/Commands/AppendCommand.swift | 174 +++ .../IMAPToolLib/Commands/ConnectionInfo.swift | 176 +++ .../Commands/DeleteMessagesCommand.swift | 223 ++++ .../Commands/DownloadCommand.swift | 93 ++ .../Commands/ExpressibleByArgument.swift | 70 ++ .../Commands/IdentifyCommand.swift | 92 ++ .../IMAPToolLib/Commands/IdleCommand.swift | 110 ++ .../IMAPToolLib/Commands/Mailbox.swift | 362 ++++++ .../Commands/MessageFlagCommand.swift | 185 +++ .../Commands/MessageInfoCommand.swift | 66 ++ .../Commands/MoveMessageCommand.swift | 131 +++ .../IMAPToolLib/Commands/RootCommand.swift | 91 ++ .../Commands/SearchMessagesCommand.swift | 106 ++ .../SearchMessagesCommand_Predicate.swift | 228 ++++ .../IMAPToolLib/Message/AsyncReadFile.swift | 88 ++ .../IMAPToolLib/Message/EmailMessage.swift | 140 +++ .../Message/InternetMessageDateParsing.swift | 382 ++++++ .../Message/MessageCreationOptions.swift | 33 + .../IMAPToolLib/Message/MessageFlag.swift | 103 ++ .../Message/MessageHeaderParsing.swift | 63 + .../IMAPToolLib/Message/MessageInfo.swift | 139 +++ .../IMAPToolLib/Message/MiniMIME.swift | 150 +++ .../Message/UIDsAndMessageIDs.swift | 122 ++ .../IMAPToolLib/Misc/ConnectionProtocol.swift | 52 + .../Sources/IMAPToolLib/Misc/Data.swift | 39 + .../IMAPToolLib/Misc/DirectoryWalk.swift | 96 ++ .../Misc/SeededRandomNumberGenerator.swift | 119 ++ .../Sources/IMAPToolLib/Misc/Span.swift | 23 + .../Misc/StableMailboxNameSorting.swift | 30 + .../IMAPToolLib/Misc/TokenBucket.swift | 87 ++ .../IMAPToolLib/Operations/Append.swift | 323 ++++++ .../IMAPToolLib/Operations/Append_Files.swift | 422 +++++++ .../IMAPToolLib/Operations/Authenticate.swift | 221 ++++ .../IMAPToolLib/Operations/BatchSize.swift | 83 ++ .../Operations/CreateMailbox.swift | 98 ++ .../Operations/DeleteMailbox.swift | 36 + .../Operations/DeleteMessages.swift | 65 ++ .../IMAPToolLib/Operations/Download.swift | 301 +++++ .../Operations/DownloadDirectory.swift | 438 +++++++ .../Operations/ExistingMailboxHierarchy.swift | 199 ++++ .../IMAPToolLib/Operations/Fetch.swift | 251 ++++ .../Operations/FetchBatch+Fixed.swift | 38 + .../FetchBatch+FromBoundaries.swift | 190 +++ .../Operations/FetchBatch+Partial.swift | 109 ++ .../IMAPToolLib/Operations/FetchBatch.swift | 147 +++ .../IMAPToolLib/Operations/FetchQuery.swift | 127 ++ .../IMAPToolLib/Operations/Identify.swift | 53 + .../IMAPToolLib/Operations/Identity.swift | 108 ++ .../IMAPToolLib/Operations/IdleEvents.swift | 232 ++++ .../IMAPToolLib/Operations/ListStatus.swift | 390 +++++++ .../IMAPToolLib/Operations/MoveMessage.swift | 110 ++ .../Operations/RenameMailbox.swift | 39 + .../IMAPToolLib/Operations/Search.swift | 270 +++++ .../Operations/Search_Predicate.swift | 281 +++++ .../Operations/SelectMailbox.swift | 249 ++++ .../IMAPToolLib/Operations/UpdateFlags.swift | 81 ++ .../Sources/IMAPToolLib/Output/Bar.swift | 78 ++ .../Sources/IMAPToolLib/Output/Bin.swift | 95 ++ .../IMAPToolLib/Output/Histogram.swift | 89 ++ .../Sources/IMAPToolLib/Output/Output.swift | 202 ++++ .../Sources/IMAPToolLib/Output/Print.swift | 56 + .../IMAPToolLib/Output/ResultFormat.swift | 89 ++ .../IMAPToolLib/Output/Statistics.swift | 30 + .../Sources/IMAPToolLib/Output/TTY.swift | 26 + .../IMAPToolLib/Output/TextEncoder.swift | 494 ++++++++ .../Output/ThroughputEstimator.swift | 101 ++ .../Commands/ArgumentParsingTests.swift | 396 +++++++ .../Commands/ExpressibleByArgumentTests.swift | 181 +++ .../Commands/MailboxCommandTests.swift | 288 +++++ .../Commands/MessageFlagCommandTests.swift | 306 +++++ .../Commands/MessageFlagTests.swift | 290 +++++ .../Commands/MoveMessageCommandTests.swift | 201 ++++ .../Commands/SearchMessagesCommandTests.swift | 739 ++++++++++++ ...SearchMessagesCommand_PredicateTests.swift | 310 +++++ .../Commands/TerminationInfoTests.swift | 77 ++ .../Commands/UIDsAndMessageIDsTests.swift | 79 ++ .../Tests/IMAPToolLibTests/Helpers.swift | 123 ++ .../InternetMessageDateParsingTests.swift | 373 ++++++ .../Message/MiniMIMETests.swift | 224 ++++ .../Operations/AppendTests.swift | 439 +++++++ .../Operations/Append_FilesTests.swift | 581 ++++++++++ .../Operations/AsyncReadFileTests.swift | 72 ++ .../Operations/AuthenticationTests.swift | 470 ++++++++ .../Operations/BatchSizeTests.swift | 84 ++ .../Operations/CreateMailboxTests.swift | 208 ++++ .../Operations/DeleteMailboxTests.swift | 100 ++ .../Operations/DeleteMessagesTests.swift | 64 ++ .../Operations/DownloadDirectoryTests.swift | 246 ++++ .../DownloadDirectoryWriterStallTests.swift | 90 ++ .../Operations/DownloadTests.swift | 224 ++++ .../Operations/EmailMessageTests.swift | 87 ++ .../ExistingMailboxHierarchyTests.swift | 162 +++ .../Operations/FetchBatchCountTests.swift | 65 ++ .../FetchBatchMakeBatchesTests.swift | 455 ++++++++ .../Operations/FetchBatchTests.swift | 336 ++++++ .../Operations/FetchTests.swift | 383 ++++++ .../Operations/IdentifyTests.swift | 62 + .../Operations/IdentityTests.swift | 36 + .../Operations/IdleEventsTests.swift | 204 ++++ .../Operations/ListStatusTests.swift | 431 +++++++ .../Operations/MessageInfoTests.swift | 81 ++ .../Operations/MoveMessageTests.swift | 218 ++++ .../Operations/RenameMailboxTests.swift | 187 +++ .../Operations/SearchEndToEndTests.swift | 557 +++++++++ .../Operations/SearchTests.swift | 208 ++++ .../Operations/Search_PredicateTests.swift | 226 ++++ .../Operations/SelectMailboxTests.swift | 169 +++ .../Operations/TestConnection.swift | 154 +++ .../Operations/TestServer.swift | 620 ++++++++++ .../Operations/ThroughputEstimatorTests.swift | 419 +++++++ .../Operations/UpdateFlagsTests.swift | 152 +++ .../IMAPToolLibTests/Output/BarTests.swift | 71 ++ .../IMAPToolLibTests/Output/BinTests.swift | 141 +++ .../Output/CondensedDurationTests.swift | 62 + .../Output/HistogramTests.swift | 99 ++ .../Output/TextEncoderBoolTests.swift | 43 + .../Output/TextEncoderTests.swift | 168 +++ .../Output/TextInterpolationTests.swift | 44 + .../ThroughputEstimatorInfinityTests.swift | 66 ++ .../StableMailboxNameSortingTests.swift | 151 +++ .../IMAPToolLibTests/TimeoutSupport.swift | 64 ++ .../IMAPToolLibTests/TokenBucketTests.swift | 182 +++ Examples/README.md | 14 +- Package.swift | 50 +- README.md | 187 ++- Sources/IMAPCommands/AppendWriter.swift | 302 +++++ .../IMAPCommands/CommandStreamPartQueue.swift | 307 +++++ Sources/IMAPCommands/CompletedCommand.swift | 81 ++ Sources/IMAPCommands/Configuration.swift | 200 ++++ Sources/IMAPCommands/ContinuationWriter.swift | 41 + Sources/IMAPCommands/Debug.swift | 89 ++ Sources/IMAPCommands/EventLoopGroup.swift | 32 + .../IMAPCommands.docc/GettingStarted.md | 159 +++ .../IMAPCommands.docc/IMAPCommands.md | 71 ++ Sources/IMAPCommands/IMAPConnection.swift | 1023 +++++++++++++++++ .../IMAPCommands/IMAPConnectionError.swift | 93 ++ Sources/IMAPCommands/IMAPCredential.swift | 180 +++ Sources/IMAPCommands/OutboundQueue.swift | 515 +++++++++ Sources/IMAPCommands/Response.swift | 118 ++ Sources/IMAPCommands/Tag.swift | 79 ++ Sources/IMAPCommands/WriteWeight.swift | 69 ++ .../NIOIMAP/NIOIMAP.docc/GettingStarted.md | 65 ++ Sources/NIOIMAP/NIOIMAP.docc/NIOIMAP.md | 56 + .../Grammar/Response/ResponsePayload.swift | 2 - .../NIOIMAPCore.docc/NIOIMAPCore.md | 7 +- .../IMAPCommandsTests/AppendWriterTests.swift | 319 +++++ .../CommandStreamPartQueueTests.swift | 200 ++++ .../ConfigurationTests.swift | 101 ++ .../ConnectionTestSupport.swift | 277 +++++ Tests/IMAPCommandsTests/CredentialTests.swift | 177 +++ .../IMAPCommandsTests/ErrorSurfaceTests.swift | 128 +++ .../IMAPConnectionCompositionTests.swift | 263 +++++ .../IMAPConnectionLifecycleTests.swift | 395 +++++++ .../LoggerMetadataTests.swift | 86 ++ .../OutboundQueueCloseDuringAppendTests.swift | 78 ++ .../OutboundQueueTests.swift | 70 ++ .../IMAPCommandsTests/WireTracingTests.swift | 92 ++ .../Grammar/CommandType/SetQuota+Tests.swift | 2 +- .../Grammar/Mailbox/MailboxInfo+Tests.swift | 2 +- .../Quota/QuotaRootResponse+Tests.swift | 4 +- 164 files changed, 28347 insertions(+), 61 deletions(-) create mode 100644 Examples/IMAPTool/Package.swift create mode 100644 Examples/IMAPTool/Sources/IMAPTool/main.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/AppendCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/ConnectionInfo.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/DeleteMessagesCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/DownloadCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/ExpressibleByArgument.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdentifyCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdleCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/Mailbox.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageFlagCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageInfoCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/MoveMessageCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/RootCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand_Predicate.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/AsyncReadFile.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/EmailMessage.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/InternetMessageDateParsing.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageCreationOptions.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageFlag.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageHeaderParsing.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageInfo.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/MiniMIME.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Message/UIDsAndMessageIDs.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/ConnectionProtocol.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/Data.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/DirectoryWalk.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/SeededRandomNumberGenerator.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/Span.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/StableMailboxNameSorting.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Misc/TokenBucket.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append_Files.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Authenticate.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/BatchSize.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/CreateMailbox.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMailbox.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMessages.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Download.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/DownloadDirectory.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/ExistingMailboxHierarchy.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Fetch.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Fixed.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+FromBoundaries.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Partial.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchQuery.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identify.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identity.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/IdleEvents.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/ListStatus.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/MoveMessage.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/RenameMailbox.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search_Predicate.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/SelectMailbox.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Operations/UpdateFlags.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Bar.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Bin.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Histogram.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Output.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Print.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/ResultFormat.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/Statistics.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/TTY.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/TextEncoder.swift create mode 100644 Examples/IMAPTool/Sources/IMAPToolLib/Output/ThroughputEstimator.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ArgumentParsingTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ExpressibleByArgumentTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MailboxCommandTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagCommandTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MoveMessageCommandTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommandTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommand_PredicateTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/TerminationInfoTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/UIDsAndMessageIDsTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Helpers.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/InternetMessageDateParsingTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Message/MiniMIMETests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AppendTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Append_FilesTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AsyncReadFileTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AuthenticationTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/BatchSizeTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/CreateMailboxTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMailboxTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMessagesTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryWriterStallTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/EmailMessageTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ExistingMailboxHierarchyTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchCountTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchMakeBatchesTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentifyTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentityTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdleEventsTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ListStatusTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MessageInfoTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MoveMessageTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/RenameMailboxTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchEndToEndTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Search_PredicateTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SelectMailboxTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ThroughputEstimatorTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/UpdateFlagsTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BarTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BinTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/CondensedDurationTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/HistogramTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/TextEncoderBoolTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/TextEncoderTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/TextInterpolationTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/Output/ThroughputEstimatorInfinityTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/StableMailboxNameSortingTests.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/TimeoutSupport.swift create mode 100644 Examples/IMAPTool/Tests/IMAPToolLibTests/TokenBucketTests.swift create mode 100644 Sources/IMAPCommands/AppendWriter.swift create mode 100644 Sources/IMAPCommands/CommandStreamPartQueue.swift create mode 100644 Sources/IMAPCommands/CompletedCommand.swift create mode 100644 Sources/IMAPCommands/Configuration.swift create mode 100644 Sources/IMAPCommands/ContinuationWriter.swift create mode 100644 Sources/IMAPCommands/Debug.swift create mode 100644 Sources/IMAPCommands/EventLoopGroup.swift create mode 100644 Sources/IMAPCommands/IMAPCommands.docc/GettingStarted.md create mode 100644 Sources/IMAPCommands/IMAPCommands.docc/IMAPCommands.md create mode 100644 Sources/IMAPCommands/IMAPConnection.swift create mode 100644 Sources/IMAPCommands/IMAPConnectionError.swift create mode 100644 Sources/IMAPCommands/IMAPCredential.swift create mode 100644 Sources/IMAPCommands/OutboundQueue.swift create mode 100644 Sources/IMAPCommands/Response.swift create mode 100644 Sources/IMAPCommands/Tag.swift create mode 100644 Sources/IMAPCommands/WriteWeight.swift create mode 100644 Sources/NIOIMAP/NIOIMAP.docc/GettingStarted.md create mode 100644 Sources/NIOIMAP/NIOIMAP.docc/NIOIMAP.md create mode 100644 Tests/IMAPCommandsTests/AppendWriterTests.swift create mode 100644 Tests/IMAPCommandsTests/CommandStreamPartQueueTests.swift create mode 100644 Tests/IMAPCommandsTests/ConfigurationTests.swift create mode 100644 Tests/IMAPCommandsTests/ConnectionTestSupport.swift create mode 100644 Tests/IMAPCommandsTests/CredentialTests.swift create mode 100644 Tests/IMAPCommandsTests/ErrorSurfaceTests.swift create mode 100644 Tests/IMAPCommandsTests/IMAPConnectionCompositionTests.swift create mode 100644 Tests/IMAPCommandsTests/IMAPConnectionLifecycleTests.swift create mode 100644 Tests/IMAPCommandsTests/LoggerMetadataTests.swift create mode 100644 Tests/IMAPCommandsTests/OutboundQueueCloseDuringAppendTests.swift create mode 100644 Tests/IMAPCommandsTests/OutboundQueueTests.swift create mode 100644 Tests/IMAPCommandsTests/WireTracingTests.swift diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index adb731e7..d66555e8 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -14,6 +14,8 @@ jobs: name: Unit tests uses: apple/swift-nio/.github/workflows/unit_tests.yml@main with: + # `Package.swift` requires Swift 6.2, so the older matrix entries cannot build this + # package and are not configured here. linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error" linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error" linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error" @@ -38,7 +40,7 @@ jobs: strategy: fail-fast: false matrix: - example: [CLI, Proxy, Fuzzer, PerformanceTester] + example: [IMAPTool, CLI, Proxy, Fuzzer, PerformanceTester] container: image: swift:6.2 steps: @@ -49,5 +51,5 @@ jobs: - name: Build run: swift build --package-path "Examples/${{ matrix.example }}" - name: Test - if: matrix.example == 'CLI' - run: swift test --package-path "Examples/CLI" + if: matrix.example == 'CLI' || matrix.example == 'IMAPTool' + run: swift test --package-path "Examples/${{ matrix.example }}" diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index 8aa212a6..3e763b38 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -18,6 +18,8 @@ jobs: name: Unit tests uses: apple/swift-nio/.github/workflows/unit_tests.yml@main with: + # `Package.swift` requires Swift 6.2, so the older matrix entries cannot build this + # package and are not configured here. linux_6_2_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error" linux_6_3_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error" linux_nightly_main_arguments_override: "--explicit-target-dependency-import-check error" @@ -41,7 +43,13 @@ jobs: uses: apple/swift-nio/.github/workflows/macos_tests.yml@main with: runner_pool: general - build_scheme: swift-nio-imap + # Xcode auto-generates the schemes for this package (`.swiftpm` is not checked in). + # A package with two or more products gets one scheme per product plus an aggregate + # `-Package` scheme; a package with a single product gets just one scheme, + # named ``. Since this package vends both `NIOIMAP` and `IMAPCommands`, the + # aggregate scheme is `swift-nio-imap-Package`. Verify with `xcodebuild -list` in a + # clean checkout if the product list ever changes. + build_scheme: swift-nio-imap-Package # macos_tests.yml requires explicit disable of 6.1. swift_6_1_enabled: false swift_6_2_build_arguments_override: "-Xswiftc -Xfrontend -Xswiftc -require-explicit-sendable -Xswiftc -warnings-as-errors" @@ -53,7 +61,7 @@ jobs: strategy: fail-fast: false matrix: - example: [CLI, Proxy, Fuzzer, PerformanceTester] + example: [IMAPTool, CLI, Proxy, Fuzzer, PerformanceTester] container: image: swift:6.2 steps: @@ -64,5 +72,5 @@ jobs: - name: Build run: swift build --package-path "Examples/${{ matrix.example }}" - name: Test - if: matrix.example == 'CLI' - run: swift test --package-path "Examples/CLI" + if: matrix.example == 'CLI' || matrix.example == 'IMAPTool' + run: swift test --package-path "Examples/${{ matrix.example }}" diff --git a/Examples/IMAPTool/Package.swift b/Examples/IMAPTool/Package.swift new file mode 100644 index 00000000..27c26c7d --- /dev/null +++ b/Examples/IMAPTool/Package.swift @@ -0,0 +1,71 @@ +// swift-tools-version:6.2 +// The swift-tools-version declares the minimum version of Swift required to build this package. +// 6.2 to match the root package, which this example depends on by path. + +import PackageDescription + +let package = Package( + name: "imap-tool-example", + platforms: [ + .macOS(.v15) + ], + products: [ + .library(name: "IMAPToolLib", targets: ["IMAPToolLib"]), + .executable(name: "imap-tool", targets: ["IMAPTool"]), + ], + dependencies: [ + .package(name: "swift-nio-imap", path: "../.."), + .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "1.7.0")), + .package(url: "https://github.com/apple/swift-async-algorithms", from: "1.1.0"), + .package(url: "https://github.com/apple/swift-collections", "1.4.0"..<"2.0.0"), + .package(url: "https://github.com/apple/swift-nio", from: "2.64.0"), + .package(url: "https://github.com/apple/swift-system", from: "1.6.0"), + .package(url: "https://github.com/apple/swift-numerics", from: "1.0.0"), + ], + targets: [ + .target( + name: "IMAPToolLib", + dependencies: [ + .product(name: "NIOIMAP", package: "swift-nio-imap"), + .product(name: "IMAPCommands", package: "swift-nio-imap"), + .product(name: "ArgumentParser", package: "swift-argument-parser"), + .product(name: "AsyncAlgorithms", package: "swift-async-algorithms"), + .product(name: "SystemPackage", package: "swift-system"), + .product(name: "NIO", package: "swift-nio"), + .product(name: "_NIOFileSystem", package: "swift-nio"), + .product(name: "NIOConcurrencyHelpers", package: "swift-nio"), + .product(name: "OrderedCollections", package: "swift-collections"), + .product(name: "DequeModule", package: "swift-collections"), + ], + swiftSettings: [ + // `IMAPCommands`' closure-taking APIs are caller-isolated, and so are this + // library's operations that wrap them. + .enableUpcomingFeature("NonisolatedNonsendingByDefault") + ] + ), + .executableTarget( + name: "IMAPTool", + dependencies: [ + .target(name: "IMAPToolLib"), + .product(name: "ArgumentParser", package: "swift-argument-parser"), + ], + swiftSettings: [ + .enableUpcomingFeature("NonisolatedNonsendingByDefault") + ] + ), + .testTarget( + name: "IMAPToolLibTests", + dependencies: [ + .target(name: "IMAPToolLib"), + .product(name: "IMAPCommands", package: "swift-nio-imap"), + .product(name: "NIOIMAP", package: "swift-nio-imap"), + .product(name: "NIO", package: "swift-nio"), + .product(name: "Numerics", package: "swift-numerics"), + .product(name: "SystemPackage", package: "swift-system"), + ], + swiftSettings: [ + .enableUpcomingFeature("NonisolatedNonsendingByDefault") + ] + ), + ] +) diff --git a/Examples/IMAPTool/Sources/IMAPTool/main.swift b/Examples/IMAPTool/Sources/IMAPTool/main.swift new file mode 100644 index 00000000..98b9ce6a --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPTool/main.swift @@ -0,0 +1,17 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib + +await IMAPToolLib.main() diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/AppendCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/AppendCommand.swift new file mode 100644 index 00000000..99656c78 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/AppendCommand.swift @@ -0,0 +1,174 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP +import SystemPackage + +struct AppendCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "append", + abstract: "Upload messages to the server." + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "The mailbox to APPEND into.") + var mailbox: MailboxName = .inbox + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @ArgumentParser.Flag( + name: .customLong("skip-unreadable"), + inversion: .prefixedNo, + help: "Skip input files that can not be parsed as emails" + ) + var skipUnreadable = true + + @ArgumentParser.Flag( + name: .customLong("sort-by-date"), + inversion: .prefixedNo, + help: "Sort the input files by message date, upload oldest messages first" + ) + var sortByDate = true + + @ArgumentParser.Flag( + inversion: .prefixedNo, + help: "Create the mailbox if it does not exist" + ) + var createMailbox = false + + @Option( + name: .customLong("flag"), + help: .init( + "IMAP flag to set on uploaded messages.", + discussion: #""" + Allows specifying flags to be set on an appended message. + + This can be repeated multiple times to set multiple flags. + + Valid values: \#(MessageFlag.allCases.map { $0.rawValue }.joined(separator: ", ")) + """# + ) + ) + var flags: [MessageFlag] = [] + + @Argument( + help: .init( + "Message file or directory with messages.", + discussion: #""" + Specify one or multiple messages to be uploaded. + + Each path can either be a path to an RFC 5288 email message or a path to directory containing RFC 5288 email messages. + + Note: the messages must have a valid 'date' header. + """#, + valueName: "path" + ), + completion: .file(extensions: ["eml", "emlx", "message"]) + ) + var input: [String] = [] + + func run() async throws { + guard + !input.isEmpty + else { + throw ValidationError("Need to specify at least one input (file).") + } + + struct Result: Encodable { + var id: Identity + var messages: [Message] + + struct Message: Encodable { + var filename: String + var id: String + var uid: UInt32? + } + } + + let result: Result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + id, + connection in + let uids = try await connection.append( + messages: input.map { FilePath($0) }, + options: appendOptions, + into: mailbox + ) + return Result( + id: id, + messages: uids.map { + Result.Message( + filename: $0.filePath.lastComponent.map { String(decoding: $0) } ?? "", + id: String($0.messageID), + uid: $0.uid.map { UInt32($0) } + ) + } + ) + } + + writeResult(result: result, format: outputFormat) + } +} + +extension AppendCommand { + var appendOptions: Set { + return Set( + skipUnreadable: skipUnreadable, + sortByDate: sortByDate, + createMailbox: createMailbox, + flags: imapFlags + ) + } + + var imapFlags: [NIOIMAP.Flag] { + flags + .reduce(into: Set()) { + $0.formUnion($1.flagsToSet) + } + .sorted(by: { "\($0)" < "\($1)" }) + } +} + +extension Set { + init( + skipUnreadable: Bool, + sortByDate: Bool, + createMailbox: Bool, + flags: [NIOIMAP.Flag] = [] + ) { + self = [] + if skipUnreadable { + self.insert(.skipErrors) + } + if sortByDate { + self.insert(.sort) + } + if createMailbox { + self.insert(.createMailbox([])) + } + if !flags.isEmpty { + self.insert(.flags(flags)) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ConnectionInfo.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ConnectionInfo.swift new file mode 100644 index 00000000..9a871d19 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ConnectionInfo.swift @@ -0,0 +1,176 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +import Synchronization +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +/// Command-line arguments for establishing an IMAP connection and authenticating. +public struct ConnectionInfo: ParsableArguments, Sendable { + public init() {} + + init( + server: String? = nil, + sasl: String? = nil, + disableSASLIR: Bool = false, + forceLogin: Bool = false, + username: String? = nil, + ) { + self.server = server + self.sasl = sasl + self.disableSASLIR = disableSASLIR + self.forceLogin = forceLogin + self.username = username + } + + @Option(help: "The server to connect to.") + var server: String? + + @Option(help: "Use SASL to authenticate (for example, 'plain:foobar').") + var sasl: String? + + @Flag(name: .customLong("disable-sasl-ir"), help: "Disable the use of SASL-IR (RFC 4959).") + var disableSASLIR: Bool = false + + @Flag(help: "Use the LOGIN command instead of AUTHENTICATE.") + var forceLogin: Bool = false + + var authenticationMethod: AuthenticationMethod { + forceLogin ? .login : .automatic + } + + @Option(help: ArgumentHelp("Use LOGIN or AUTH PLAIN to authenticate.", valueName: "user:password")) + var username: String? + + /// An opaque account identifier resolved by the embedding tool. + /// + /// `IMAPToolLib` itself does not know how to resolve accounts. An embedder + /// can install an ``ConnectionInfo/accountResolver`` that maps this + /// identifier to a connection configuration and credential (for example, + /// by looking it up in the system's account store). When no resolver is + /// installed this option is inert. + @Option( + help: ArgumentHelp( + "An account identifier resolved by the embedding tool.", + visibility: .private + ) + ) + var account: String? + + @Flag( + name: .customLong("connection-logging"), + help: ArgumentHelp( + "Log connection (debug) activity.", + visibility: .private + ) + ) + var _connectionLogging: Bool = false + + var connectionLogging: IMAPConnection.Configuration.Logging { + _connectionLogging ? .logging : .noLogging + } + + public mutating func validate() throws { + // A SASL response carries no password, so there is nothing to put in a LOGIN. + // `--account` can resolve to a SASL credential too, but only at connect time; + // ``IMAPConnection/login(credential:capabilities:method:)`` catches that case. + if forceLogin, sasl != nil { + throw ValidationError("'--force-login' needs a username and password, so it can not be used with '--sasl'.") + } + _ = try self.makeConfiguration() + } + + /// The resolved connection endpoint and credential for an account identifier. + /// + /// Only the connection endpoint is provided here; the `logging` setting is + /// applied by ``ConnectionInfo`` itself so that `--connection-logging` keeps + /// working for account-based connections. + public struct ResolvedAccount: Sendable { + public var hostname: String + public var port: UInt16 + public var useTLS: Bool + public var credential: IMAPCredential + + public init(hostname: String, port: UInt16, useTLS: Bool, credential: IMAPCredential) { + self.hostname = hostname + self.port = port + self.useTLS = useTLS + self.credential = credential + } + } + + /// A closure that resolves an account identifier (see ``ConnectionInfo/account``) + /// into a connection endpoint and credential, or returns `nil` if the + /// identifier is unknown. + public typealias AccountResolver = @Sendable (_ identifier: String) throws -> ResolvedAccount? + + private static let _accountResolver = Mutex(nil) + + /// Installs a resolver used to turn an ``ConnectionInfo/account`` identifier into a + /// connection endpoint and credential. Passing `nil` removes any installed resolver. + /// + /// This is the seam an embedding tool uses to support account-based authentication + /// (for example, tokens sourced from the system account store) without `IMAPToolLib` + /// having to know anything about where those accounts come from. + public static func setAccountResolver(_ resolver: AccountResolver?) { + _accountResolver.withLock { $0 = resolver } + } + + private func resolveAccount() throws -> ResolvedAccount? { + guard let account else { return nil } + guard let resolver = Self._accountResolver.withLock({ $0 }) else { + throw ValidationError("No account resolver is installed for '--account \(account)'.") + } + guard let resolved = try resolver(account) else { + throw ValidationError("Unknown account '\(account)'.") + } + return resolved + } + + /// Creates a ``IMAPConnection.Configuration`` from the parsed server argument. + func makeConfiguration() throws -> IMAPConnection.Configuration { + if let resolved = try resolveAccount() { + return IMAPConnection.Configuration( + hostname: resolved.hostname, + port: resolved.port, + useTLS: resolved.useTLS, + logging: connectionLogging + ) + } + guard let text = server else { + throw ValidationError("Need to specify either a server name or an account.") + } + do { + return try IMAPConnection.Configuration( + serverText: text, + logging: connectionLogging + ) + } catch { + throw ValidationError("\(error)") + } + } + + /// Creates a ``IMAPCredential`` from the parsed authentication arguments. + func makeCredential() throws -> IMAPCredential { + if let resolved = try resolveAccount() { + return resolved.credential + } + return try IMAPCredential(url: self.server, sasl: self.sasl, username: self.username) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DeleteMessagesCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DeleteMessagesCommand.swift new file mode 100644 index 00000000..522a4f1d --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DeleteMessagesCommand.swift @@ -0,0 +1,223 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP +import SystemPackage + +struct DeleteMessagesCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "delete-messages", + abstract: "Delete messages." + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: .customLong("mailbox"), + help: """ + The mailbox to delete messages from. + """ + ) + var mailboxName: MailboxName = .inbox + + @ArgumentParser.Flag( + name: .customLong("all"), + help: ArgumentHelp( + "Delete all messages in the mailbox", + discussion: #""" + This will (permanently) delete all messages in the given mailbox. + Since this can lead to permanent data loss, this will either (a) + query the user to confirm this choice (if running in an interactive + shell), or (b) check for the existence of a file named + .imap-tool-allow-delete-all + in the current user’s home directory. + """# + ) + ) + var deleteAllMessages = false + + @Option( + help: #""" + A file to read message info from. This should be JSON as output by the \ + 'append' command. The JSON needs to be an array where each element has a \ + 'uid' value or an 'id' value, the latter being the message-id header of \ + the messages to be deleted. + """#, + completion: .file(extensions: ["json"]) + ) + var messages: String? + + func run() async throws { + switch action { + case .deleteSpecific(filePath: let path): + let ids = try UIDsAndMessageIDs.parse(filePath: path) + guard !ids.isEmpty else { + writeStatus("No UIDs / Message-IDs found.") + return + } + try await deleteSpecificMessages(ids: ids) + case .deleteAll: + try await deleteAllMessages() + case .fail(let text): + exitWithErrorMessage(text) + } + } +} + +extension DeleteMessagesCommand { + enum Action: Equatable { + case deleteAll + case deleteSpecific(filePath: String) + case fail(Output) + } + + var action: Action { + switch (deleteAllMessages, messages) { + case (false, let messages?): + return .deleteSpecific(filePath: messages) + case (true, nil): + return .deleteAll + case (true, .some): + return .fail("Can not specify both --all and a file to read message info from.") + case (false, nil): + return .fail("Need to specify a file to read message info from.") + } + } +} + +// MARK: - Delete All Messages + +extension DeleteMessagesCommand { + func deleteAllMessages() async throws { + struct Result: Encodable { + var count: Int + } + + let result: Result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + id, + connection in + let info = try await connection.select( + mailbox: mailboxName, + createMailbox: .fail + ) + + writeStatus("Mailbox has \(info.messageCount) messages.") + + guard + 0 < info.messageCount + else { return Result(count: 0) } + + await checkDeleteAllSafeguards( + mailbox: mailboxName, + messageCount: info.messageCount + ) + + try await connection.deleteAllMessages() + + return Result( + count: info.messageCount + ) + } + + writeResult( + result: result, + format: outputFormat + ) + + } + + func checkDeleteAllSafeguards( + mailbox: MailboxName, + messageCount: Int + ) async { + if standardInputIsTTY { + writeStatus( + "You are about to delete \(messageCount) messages in mailbox '\(mailbox)'. Please type the exact message count to confirm.", + terminator: "" + ) + guard + let input = readLine() + else { exitWithErrorMessage("EOF") } + guard + input == "\(messageCount)" + else { exitWithErrorMessage("'\(input)' != '\(messageCount)'") } + } else { + guard + let home = ProcessInfo.processInfo.environment["HOME"] + else { exitWithErrorMessage("HOME not set") } + let path = FilePath(home).appending(".imap-tool-allow-delete-all") + do { + _ = try await Data( + asyncContentsOf: path, + length: 1 + ) + } catch { + exitWithErrorMessage("Safeguard file '\(path)' does not exist.") + } + } + } +} + +// MARK: - Delete Specific Messages + +extension DeleteMessagesCommand { + func deleteSpecificMessages( + ids: UIDsAndMessageIDs + ) async throws { + struct Result: Encodable { + var uids: [UID] + } + + let result: Result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + id, + connection in + + let info = try await connection.select( + mailbox: mailboxName, + createMailbox: .fail + ) + + let allUIDs = try await connection.findMessageIDs( + selectInfo: info, + capabilities: id.capabilities, + ids: ids + ) + + try await connection.deleteMessages( + uids: allUIDs + ) + + return Result( + uids: Array(allUIDs) + ) + } + + writeResult( + result: result, + format: outputFormat + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DownloadCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DownloadCommand.swift new file mode 100644 index 00000000..5b8a9318 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/DownloadCommand.swift @@ -0,0 +1,93 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP +import SystemPackage + +struct DownloadCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "download", + abstract: "Download raw messages.", + discussion: #""" + This downloads the raw message data for messages in the specified mailbox on the server into a local directory. + + Previously downloaded messages already in the directory are skipped, allowing downloads to be resumed. + + Passing --delete-unknown deletes any local message files that no longer exist on the server. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option( + name: .customLong("mailbox"), + help: """ + The mailbox to get messages from. + """ + ) + var mailbox: MailboxName = .inbox + + @OptionGroup() + var fetchQueryGroup: FetchQueryGroup + + @ArgumentParser.Flag( + name: .customLong("delete-unknown"), + inversion: .prefixedNo, + help: "Delete downloaded messages that do not exist on the server." + ) + var deleteUnknown: Bool = false + + @Option( + help: ArgumentHelp( + #"The directory to download into."#, + valueName: "directory" + ), + completion: .directory + ) + var destination: FilePath + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + func run() async throws { + let query = try fetchQueryGroup.makeFetchQuery() + + try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { id, connection -> Void in + let info = try await connection.select( + mailbox: mailbox, + createMailbox: .fail + ) + _ = try await connection.download( + mailboxMessageCount: info.messageCount, + capabilities: id.capabilities, + uidValidity: info.uidValidity, + query: query, + into: destination, + deleteUnknown: deleteUnknown + ) + } + + // Write an empty result. Allows for future expansion. + struct Result: Encodable {} + writeResult(result: Result(), format: outputFormat) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ExpressibleByArgument.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ExpressibleByArgument.swift new file mode 100644 index 00000000..1b73a6cf --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/ExpressibleByArgument.swift @@ -0,0 +1,70 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import NIOIMAP +import SystemPackage + +extension NIOIMAP.MailboxName: ArgumentParser.ExpressibleByArgument { + public init?(argument: String) { + do { + let path = try MailboxPath.makeRootMailbox(displayName: argument) + self = path.name + } catch { + return nil + } + } + + public var defaultValueDescription: String { "INBOX" } +} + +extension FilePath: ArgumentParser.ExpressibleByArgument { + public init?(argument: String) { + self.init(argument) + } + + public var defaultValueDescription: String { "path" } +} + +extension UID: ArgumentParser.ExpressibleByArgument { + public init?(argument: String) { + guard + let v = UInt32(argument), + let uid = UID(exactly: v) + else { return nil } + self = uid + } + + public var defaultValueDescription: String { "uid" } +} + +extension NIOIMAP.MessageID: ArgumentParser.ExpressibleByArgument { + public init?(argument: String) { + // Reject empty / whitespace-only input rather than producing an empty "<>" id. + guard argument.contains(where: { !$0.isWhitespace }) else { return nil } + // MessageID should be in the format with angle brackets + // If the user provides it without brackets, add them + let normalized: String + switch (argument.hasPrefix("<"), argument.hasSuffix(">")) { + case (true, true): normalized = argument + case (false, false): normalized = "<\(argument)>" + case (false, true), (true, false): return nil + } + // Reject a bracketed-but-empty id such as "<>". + guard normalized.count > 2 else { return nil } + self.init(normalized) + } + + public var defaultValueDescription: String { "" } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdentifyCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdentifyCommand.swift new file mode 100644 index 00000000..91dc9808 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdentifyCommand.swift @@ -0,0 +1,92 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +struct IdentifyCommand: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "id", + abstract: "Identify the server" + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + func run() async throws { + let config = try connectionInfo.makeConfiguration() + + let result = try await IMAPConnection.withConnection(configuration: config) { greeting, connection in + writeStatus("Server greeting: \(greeting.status)") + let r = try await connection.authenticate( + greeting: greeting, + connectionInfo: connectionInfo + ) + return try await connection.identify( + capabilities: r.capabilities + ) + } + + writeResult(result: result, format: outputFormat) + } +} + +extension IMAPConnection { + /// Authenticates the connection using the credentials from `connectionInfo`. + func authenticate( + greeting: IMAPConnection.Greeting, + connectionInfo: ConnectionInfo + ) async throws -> AuthenticationResult { + try await authenticate( + greeting: greeting, + credential: try connectionInfo.makeCredential(), + disableSASLIR: connectionInfo.disableSASLIR, + method: connectionInfo.authenticationMethod + ) + } +} + +extension IMAPConnection { + /// Runs the given closure with an authenticated IMAP connection. + static func withAuthenticatedConnection( + info connectionInfo: ConnectionInfo, + _ body: @Sendable @escaping (Identity, IMAPConnection) async throws -> Result + ) async throws -> Result { + let config = try connectionInfo.makeConfiguration() + + return try await IMAPConnection.withConnection(configuration: config) { greeting, connection in + writeStatus("Connected to \(config.endpoint.hostname ?? ""), received greeting: '\(greeting.status)'") + let r = try await connection.authenticate( + greeting: greeting, + connectionInfo: connectionInfo + ) + let identity = try await connection.identify( + capabilities: r.capabilities + ) + + defer { + writeStatus("Closing connection to server.") + } + return try await body(identity, connection) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdleCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdleCommand.swift new file mode 100644 index 00000000..795bdee0 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/IdleCommand.swift @@ -0,0 +1,110 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP + +struct IdleCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "idle", + abstract: "Listen for IDLE (RFC 2177) updates.", + discussion: #""" + This writes each received event to standard output. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option(help: "Which delimiter to use to separate events in JSON output. Uses json-seq (RFC 7464) by default.") + var recordSeparator: RecordSeparator = .recordSeparator + + @Option( + name: .customLong("mailbox"), + help: """ + The mailbox to listen for updates on. + """ + ) + var mailboxName: MailboxName = .inbox + + func run() async throws { + try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { id, connection in + _ = try await connection.select( + mailbox: mailboxName, + createMailbox: .fail + ) + + let terminator: Data = { + switch outputFormat { + case .text: return Data("\n".utf8) + case .json: return Data(recordSeparator.separatorBytes) + } + }() + + try await connection.runIdle { _, events in + for try await event in events { + writeResult( + result: event, + format: outputFormat, + terminator: terminator + ) + } + } + } + } +} + +enum RecordSeparator: Equatable, Sendable { + /// 0x1e + case recordSeparator + /// 0x0a + case lineFeed + /// 0x0d + case carriageReturn +} + +extension RecordSeparator: ExpressibleByArgument { + init?(argument: String) { + switch argument.lowercased() { + case "1e", "rs", "recordseparator", "json-seq": + self = .recordSeparator + case "0a", "lf", "linefeed": + self = .lineFeed + case "0d", "cr", "carriagereturn": + self = .carriageReturn + default: + return nil + } + } +} + +extension RecordSeparator { + var separatorBytes: [UInt8] { + switch self { + case .recordSeparator: [0x1e] + case .lineFeed: [0x0a] + case .carriageReturn: [0x0d] + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/Mailbox.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/Mailbox.swift new file mode 100644 index 00000000..263e2c6d --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/Mailbox.swift @@ -0,0 +1,362 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +struct MailboxCommand: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "mailbox", + abstract: "Operations on mailboxes / maildirs", + subcommands: [ + List.self, + Create.self, + Delete.self, + Rename.self, + ], + defaultSubcommand: List.self, + aliases: ["maildir", "mailboxes", "maildirs"] + ) +} + +// MARK: List + +extension MailboxCommand { + struct List: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "list", + abstract: "List all mailboxes / maildirs" + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + func run() async throws { + let result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + info, + connection in + try await connection.listMailboxes( + capabilities: info.capabilities + ) + } + + writeResult( + result: result.map { MailboxInfoAndStatus.EncodableInfo($0) }, + format: outputFormat + ) + } + } +} + +// MARK: Create + +extension MailboxCommand { + struct Create: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "create", + abstract: "Create mailbox(es)", + discussion: #""" + This creates one or multiple mailboxes. + + Note that servers that support CREATE-SPECIAL-USE will let the user specify the so-called “special-use” attributes on the mailbox upon creation. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: .customLong("name") + ) + var names: [String] = [] + + @Option( + name: .customLong("name-json"), + help: .init( + "Mailbox path as a JSON", + discussion: #""" + Specify the mailbox with JSON. Using the 'path' key allows specifying a nested mailbox. Using the 'name' key, allow specifying a top-level mailbox. The 'specialUse' key can be used for CREATE-SPECIAL-USE. For example: `{path: ["foo", "bar"], specialUse: "trash"}`. + """#, + ) + ) + var paths: [MailboxNameWithSpecialUse] = [] + + func run() async throws { + let result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + info, + connection in + let list = try await connection.listMailboxes( + capabilities: info.capabilities + ) + + let existing = ExistingMailboxHierarchy(mailboxPaths: list.map { $0.path }) + let mailboxes = try existing.makeMailboxNamesForCreation(mailboxDisplayNamesWithSpecialUse) + + var result: [MailboxInfoAndStatus] = [] + for m in mailboxes { + result.append( + try await connection.createIfNeededAndList( + capabilities: info.capabilities, + mailbox: m + ) + ) + } + return result + } + + writeResult( + result: result.map { MailboxInfoAndStatus.EncodableInfo($0) }, + format: outputFormat + ) + } + } +} + +// MARK: - + +extension MailboxCommand.Create { + var mailboxDisplayNamesWithSpecialUse: [MailboxDisplayNameWithSpecialUse] { + names.map { + MailboxDisplayNameWithSpecialUse(namePath: [$0], parameters: []) + } + + paths.map { + MailboxDisplayNameWithSpecialUse($0) + } + } +} + +extension MailboxCommand.Create { + struct MailboxNameWithSpecialUse: Hashable, Sendable { + var namePath: [String] + var specialUse: SpecialUse? + + enum SpecialUse: String, Hashable, Sendable { + case archive + case drafts + case junk + case sent + case trash + } + } +} + +extension MailboxDisplayNameWithSpecialUse { + init( + _ other: MailboxCommand.Create.MailboxNameWithSpecialUse + ) { + self.init( + namePath: other.namePath, + parameters: other.specialUse.map { [CreateParameter($0)] } ?? [] + ) + } +} + +extension CreateParameter { + init( + _ other: MailboxCommand.Create.MailboxNameWithSpecialUse.SpecialUse + ) { + let attr: UseAttribute + switch other { + case .archive: attr = .archive + case .drafts: attr = .drafts + case .junk: attr = .junk + case .sent: attr = .sent + case .trash: attr = .trash + } + self = .attributes([attr]) + } +} + +// MARK: - + +extension MailboxCommand.Create.MailboxNameWithSpecialUse: ExpressibleByArgument { + fileprivate struct Raw: Decodable { + var name: String? + var path: [String]? + var specialUse: String? + } + + init?(argument: String) { + let decoder = JSONDecoder() + decoder.allowsJSON5 = true + decoder.assumesTopLevelDictionary = true + guard + let raw = try? decoder.decode(Raw.self, from: Data(argument.utf8)) + else { return nil } + // Path + let namePath: [String] + switch (raw.name, raw.path) { + case (let name?, nil): + namePath = [name] + case (nil, let path?): + namePath = path + case (.some, .some), (nil, nil): + return nil + } + // Special Use: + let specialUse: SpecialUse? + if let s = raw.specialUse { + guard + let ss = SpecialUse(rawValue: s) + else { return nil } + specialUse = ss + } else { + specialUse = nil + } + self.init( + namePath: namePath, + specialUse: specialUse + ) + } +} + +// MARK: Delete + +extension MailboxCommand { + struct Delete: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "delete", + abstract: "Delete mailbox(es)", + discussion: #""" + This deletes one or multiple mailboxes and all their contents. + + WARNING: This operation is irreversible and will permanently delete all messages in the specified mailboxes. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Argument( + help: .init( + "Mailbox name to be deleted", + valueName: "mailbox-name" + ) + ) + var names: [MailboxName] = [] + + func run() async throws { + guard !names.isEmpty else { + throw ValidationError("At least one mailbox name must be specified") + } + + let result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + info, + connection in + // Delete each mailbox: + for mailboxName in names { + try await connection.deleteMailbox( + capabilities: info.capabilities, + mailbox: mailboxName + ) + } + // List the mailboxes after the deletion: + return try await connection.listMailboxes( + capabilities: info.capabilities + ) + } + + writeResult( + result: result.map { MailboxInfoAndStatus.EncodableInfo($0) }, + format: outputFormat + ) + } + + mutating func validate() throws { + guard + !names.isEmpty + else { + throw ValidationError("Must specify at least one mailbox") + } + var previous = Set() + for name in names { + defer { previous.insert(name) } + guard + !previous.contains(name) + else { + let n = (try? MailboxPath(name: name))?.displayStringComponents().first ?? "" + throw ValidationError("Duplicate mailbox name '\(n)'") + } + } + } + } +} + +// MARK: Rename + +extension MailboxCommand { + struct Rename: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "rename", + abstract: "Rename a mailbox", + discussion: #""" + This renames a mailbox on the server. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: .long, + help: "Current (old) name of the mailbox" + ) + var oldName: MailboxName + + @Option( + name: .long, + help: "New name for the mailbox" + ) + var newName: MailboxName + + func run() async throws { + let result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + info, + connection in + try await connection.renameMailbox( + capabilities: info.capabilities, + old: oldName, + new: newName + ) + + return try await connection.listMailboxes( + capabilities: info.capabilities + ) + } + + writeResult( + result: result.map { MailboxInfoAndStatus.EncodableInfo($0) }, + format: outputFormat + ) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageFlagCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageFlagCommand.swift new file mode 100644 index 00000000..a07c7ad2 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageFlagCommand.swift @@ -0,0 +1,185 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP +import SystemPackage + +struct MessageFlagCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "flag", + abstract: "Set / unset IMAP flags on messages.", + aliases: ["flags"] + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "The mailbox containing the message(s).") + var mailbox: MailboxName = .inbox + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: [.customLong("flag"), .customLong("set")], + help: .init( + "IMAP flag to set on the message(s).", + discussion: #""" + Allows specifying flags to be set on messages. + + This can be repeated multiple times to set multiple flags. + + Valid values: \#(MessageFlag.allCases.map { $0.rawValue }.joined(separator: ", ")) + """# + ) + ) + var setFlags: [MessageFlag] = [] + + @Option( + name: [.customLong("unset"), .customLong("remove")], + help: .init( + "IMAP flag to unset on the message(s).", + discussion: #""" + Allows specifying flags to be unset on messages. + + This can be repeated multiple times to unset multiple flags. + + Valid values: \#(MessageFlag.allCases.map { $0.rawValue }.joined(separator: ", ")) + """# + ) + ) + var unsetFlags: [MessageFlag] = [] + + @Option( + name: .customLong("uid"), + help: "UIDs of messages to modify (can be specified multiple times)" + ) + var uids: [UID] = [] + @Option( + name: .customLong("message-id"), + help: "Message-ID of message to modify (can be specified multiple times)" + ) + var messageIDs: [MessageID] = [] + + @Option( + help: #""" + A file to read message info from. This should be JSON as output by the \ + 'append' command. The JSON needs to be an array where each element has a \ + 'uid' value or an 'id' value, the latter being the message-id header of \ + the messages to be deleted. + """#, + completion: .file(extensions: ["json"]) + ) + var messages: String? + + func validate() throws { + guard + !uids.isEmpty || !messageIDs.isEmpty || (messages != nil) + else { + throw ValidationError( + "Must specify at least one UID (--uid) or a file to read UIDs and/or message-id from (--messages)." + ) + } + } + + func run() async throws { + let ids = try UIDsAndMessageIDs( + filePath: messages, + uids: uids, + messageIDs: messageIDs + ) + guard + !ids.isEmpty + else { + writeStatus("No messages to update,") + return + } + + try await run( + ids: ids, + changes: imapFlags + ) + } + + func run( + ids: UIDsAndMessageIDs, + changes: IMAPToolLib.FlagChanges + ) async throws { + try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { id, connection in + let info = try await connection.select( + mailbox: mailbox, + createMailbox: .fail + ) + + let allUIDs = try await connection.findMessageIDs( + selectInfo: info, + capabilities: id.capabilities, + ids: ids + ) + + guard + !allUIDs.isEmpty + else { return } + + try await connection.updateFlags( + uids: allUIDs, + changes: changes + ) + } + + struct EmptyResult: Encodable {} + + writeResult(result: EmptyResult(), format: outputFormat) + } +} + +extension MessageFlagCommand { + var imapFlags: IMAPToolLib.FlagChanges { + IMAPToolLib.FlagChanges( + setFlags: setFlags, + unsetFlags: unsetFlags + ) + } +} + +extension IMAPToolLib.FlagChanges { + init( + setFlags: [MessageFlag], + unsetFlags: [MessageFlag] + ) { + let a = + setFlags + .reduce(into: Set()) { + $0.formUnion($1.flagsToSet) + } + let b = + unsetFlags + .reduce(into: Set()) { + $0.formUnion($1.flagsToUnset) + } + self.init(set: [], unset: []) + self.set = a.subtracting(b) + .sorted(by: { "\($0)" < "\($1)" }) + self.unset = b.subtracting(a) + .sorted(by: { "\($0)" < "\($1)" }) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageInfoCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageInfoCommand.swift new file mode 100644 index 00000000..bc3e6242 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MessageInfoCommand.swift @@ -0,0 +1,66 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +struct MessageInfoCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "message-info", + abstract: "Get information about messages." + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option( + name: .customLong("mailbox"), + help: """ + The mailbox to get messages from. + """ + ) + var mailbox: MailboxName = .inbox + + @OptionGroup() + var fetchQueryGroup: FetchQueryGroup + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + func run() async throws { + let query = try fetchQueryGroup.makeFetchQuery() + + let result: [MessageInfo] = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { + id, + connection in + let info = try await connection.select( + mailbox: mailbox, + createMailbox: .fail + ) + return try await connection.fetchMessageInfo( + mailboxMessageCount: info.messageCount, + capabilities: id.capabilities, + query: query + ) + } + + writeResult(result: result, format: outputFormat) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MoveMessageCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MoveMessageCommand.swift new file mode 100644 index 00000000..6a26fa22 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/MoveMessageCommand.swift @@ -0,0 +1,131 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +struct MoveMessageCommand: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "move-message", + abstract: "Move messages between mailboxes", + discussion: #""" + This command moves messages from one mailbox to another. + + If the server supports the MOVE extension (RFC 6851), it will use the UID MOVE command. Otherwise, it will fall back to UID COPY and then delete the source. + """# + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: [.customLong("source"), .customLong("from")], + help: "Source mailbox containing the message(s)" + ) + var sourceMailbox: MailboxName + + @Option( + name: [.customLong("destination"), .customLong("to")], + help: "Destination mailbox for the message(s)" + ) + var destinationMailbox: MailboxName + + @Option( + name: .customLong("uid"), + help: "UID of message to move (can be specified multiple times)" + ) + var uids: [UID] = [] + + @Option( + name: .customLong("message-id"), + help: "Message-ID of message to move (can be specified multiple times)" + ) + var messageIDs: [MessageID] = [] + + @Option( + help: #""" + A file to read message info from. This should be JSON as output by the \ + 'append' command. The JSON needs to be an array where each element has a \ + 'uid' value or an 'id' value, the latter being the message-id header of \ + the messages to be moved. + """#, + completion: .file(extensions: ["json"]) + ) + var messages: String? + + func validate() throws { + guard + !uids.isEmpty || !messageIDs.isEmpty || (messages != nil) + else { + throw ValidationError( + "Must specify at least one UID (--uid), Message-ID (--message-id), or a file to read from (--messages)." + ) + } + } + + func run() async throws { + let ids = try UIDsAndMessageIDs( + filePath: messages, + uids: uids, + messageIDs: messageIDs + ) + guard !ids.isEmpty else { + writeStatus("No messages to move.") + return + } + + struct Result: Encodable { + var uids: [UID] + } + + let result = try await IMAPConnection.withAuthenticatedConnection(info: connectionInfo) { info, connection in + // Select the source mailbox + let selectInfo = try await connection.select( + mailbox: sourceMailbox, + createMailbox: .fail + ) + + let allUIDs = try await connection.findMessageIDs( + selectInfo: selectInfo, + capabilities: info.capabilities, + ids: ids + ) + + guard !allUIDs.isEmpty else { + writeStatus("No messages found to move.") + return Result(uids: []) + } + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: info.capabilities, + uids: allUIDs, + to: destinationMailbox + ) + + return Result(uids: Array(allUIDs)) + } + + writeResult(result: result, format: outputFormat) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/RootCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/RootCommand.swift new file mode 100644 index 00000000..f273972f --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/RootCommand.swift @@ -0,0 +1,91 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +/// The subcommands provided by `IMAPToolLib`. +/// +/// This is exposed so that an embedding tool can build its own root command +/// that combines these built-in subcommands with additional ones. +public let builtinSubcommands: [any ParsableCommand.Type] = [ + AppendCommand.self, + DeleteMessagesCommand.self, + DownloadCommand.self, + IdentifyCommand.self, + IdleCommand.self, + MailboxCommand.self, + MessageInfoCommand.self, + MessageFlagCommand.self, + MoveMessageCommand.self, + SearchMessagesCommand.self, +] + +struct RootCommand: AsyncParsableCommand { + static let configuration = CommandConfiguration( + commandName: "imap-tool", + subcommands: builtinSubcommands + ) +} + +/// Describes how the CLI should terminate for an error thrown while parsing or +/// running a command. +/// +/// ArgumentParser signals `--help`, `--version`, and other "clean" exits by +/// throwing. Those must be written to standard output with a `0` exit code, +/// whereas genuine parsing/validation errors belong on standard error with a +/// non-zero exit code (e.g. `EX_USAGE`). +struct TerminationInfo: Equatable { + var message: String + /// A clean exit (help/version) — print to standard output and exit `0`. + var isCleanExit: Bool + var code: Int32 +} + +func terminationInfo(for error: any Swift.Error) -> TerminationInfo { + let exitCode = RootCommand.exitCode(for: error) + return TerminationInfo( + message: RootCommand.fullMessage(for: error), + isCleanExit: exitCode == .success, + code: exitCode.rawValue + ) +} + +/// Parses command-line arguments and runs the specified IMAP tool subcommand. +public func main() async { + do { + var command = try RootCommand.parseAsRoot() + if var asyncCommand = command as? AsyncParsableCommand { + try await asyncCommand.run() + } else { + try command.run() + } + } catch { + let info = terminationInfo(for: error) + if info.isCleanExit { + // Help / version / other clean exits belong on standard output. + if !info.message.isEmpty { + writeStandardOutput(info.message + "\n") + } + } else if !info.message.isEmpty { + writeStatus("\(info.message)") + flushStatus() + } + _exit(info.code) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand.swift new file mode 100644 index 00000000..29c113a1 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand.swift @@ -0,0 +1,106 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP + +struct SearchMessagesCommand: AsyncParsableCommand, Sendable { + static let configuration = CommandConfiguration( + commandName: "search", + abstract: "Search for messages", + discussion: #""" + This command searches for messages in a mailbox based on various criteria such as date ranges, flags, and subjects. + """#, + aliases: [ + "search-messages", + "search-message", + ] + ) + + @OptionGroup() + var connectionInfo: ConnectionInfo + + @Option(help: "How to format the result.") + var outputFormat: ResultFormat = .text + + @Option( + name: .customLong("mailbox"), + help: "The mailbox to search in" + ) + var mailbox: MailboxName = .inbox + + @OptionGroup() + var predicate: Predicate + + @ArgumentParser.Flag( + name: .customLong("fetch-message-info"), + help: "Fetch message info for the found UIDs" + ) + var shouldFetchMessageInfo: Bool = false + + func run() async throws { + // Get the search criteria: + let searchKey = try SearchKey(predicate) + writeStatus("Searching for messages with \(searchKey)") + + struct Result: Encodable { + var imapQuery: String + var uids: [UID] + var messageInfo: [MessageInfo]? + } + + let result: Result = try await IMAPConnection.withAuthenticatedConnection( + info: connectionInfo + ) { info, connection -> Result in + let mailboxInfo = try await connection.select( + mailbox: mailbox, + createMailbox: .fail + ) + + let uids = try await connection.search( + capabilities: info.capabilities, + key: searchKey + ) + + let messageInfo: [MessageInfo]? + if shouldFetchMessageInfo { + messageInfo = try await connection.fetchMessageInfo( + mailboxMessageCount: mailboxInfo.messageCount, + capabilities: info.capabilities, + query: .uids(uids) + ) + } else { + messageInfo = nil + } + + return Result( + imapQuery: String(reflecting: searchKey), + uids: uids.map { $0 }, + messageInfo: messageInfo + ) + } + + writeResult( + result: result, + format: outputFormat + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand_Predicate.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand_Predicate.swift new file mode 100644 index 00000000..deb76472 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Commands/SearchMessagesCommand_Predicate.swift @@ -0,0 +1,228 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +extension SearchMessagesCommand { + /// Command-line arguments that specify the search predicate. + struct Predicate: ParsableArguments, Sendable { + init() {} + + init( + olderThanDays: Int? = nil, + newerThanDays: Int? = nil, + subject: String? = nil, + fromAddress: String? = nil, + toAddress: String? = nil, + ccAddress: String? = nil, + text: String? = nil, + messageSizeSmallerThan: Int? = nil, + messageSizeLargerThan: Int? = nil, + messageID: String? = nil, + emailID: String? = nil, + threadID: String? = nil, + flags: [MessageFlag] = [] + ) { + self.olderThanDays = olderThanDays + self.newerThanDays = newerThanDays + self.subject = subject + self.fromAddress = fromAddress + self.toAddress = toAddress + self.ccAddress = ccAddress + self.text = text + self.messageSizeSmallerThan = messageSizeSmallerThan + self.messageSizeLargerThan = messageSizeLargerThan + self.messageID = messageID + self.emailID = emailID + self.threadID = threadID + self.flags = flags + } + + @Option( + name: .customLong("older-than-days"), + help: "Match messages older than N days" + ) + var olderThanDays: Int? + + @Option( + name: .customLong("newer-than-days"), + help: "Match messages newer than N days" + ) + var newerThanDays: Int? + + @Option( + name: .customLong("subject"), + help: "Match messages with this subject" + ) + var subject: String? + + @Option( + name: .customLong("from"), + help: "Match messages from this sender" + ) + var fromAddress: String? + + @Option( + name: .customLong("to"), + help: "Match messages to this recipient" + ) + var toAddress: String? + + @Option( + name: .customLong("cc"), + help: "Match messages with this CC recipient" + ) + var ccAddress: String? + + @Option( + name: .customLong("text"), + help: "Match messages containing this text" + ) + var text: String? + + @Option( + name: .customLong("message-size-smaller-than"), + help: "Match messages smaller than N bytes" + ) + var messageSizeSmallerThan: Int? + + @Option( + name: .customLong("message-size-larger-than"), + help: "Match messages larger than N bytes" + ) + var messageSizeLargerThan: Int? + + @Option( + name: .customLong("message-id"), + help: "Match message by IMAP Message-ID" + ) + var messageID: String? + + @Option( + name: .customLong("email-id"), + help: "Match message by RFC 8474 Email ID" + ) + var emailID: String? + + @Option( + name: .customLong("thread-id"), + help: "Match messages by RFC 8474 Thread ID" + ) + var threadID: String? + + @Option( + name: .customLong("flag"), + help: .init( + "Match messages with this flag.", + discussion: #""" + Match messages with this flag set. + + This can be repeated multiple times. + + Valid values: \#(MessageFlag.allCases.map { $0.rawValue }.joined(separator: ", ")) + """# + ) + ) + var flags: [MessageFlag] = [] + } +} + +extension SearchKey { + /// Create a ``SearchKey`` from command line arguments. + init( + _ other: SearchMessagesCommand.Predicate + ) throws { + try self.init(SearchKey.Predicate(other)) + } +} + +extension SearchKey.Predicate { + /// Convert to a `SearchKey.Predicate`. + init( + _ other: SearchMessagesCommand.Predicate + ) throws { + // Combine all flags + var flagsSet: Set = [] + var flagsNotSet: Set = [] + for flag in other.flags { + let toSearch = flag.flagsToSearch + flagsSet.formUnion(toSearch.set) + flagsNotSet.formUnion(toSearch.notSet) + } + guard + flagsSet.isDisjoint(with: flagsNotSet) + else { + let a = flagsSet.intersection(flagsNotSet) + let invalid = other + .flags + .filter { flag in + !flag.flagsToSearch.set.isDisjoint(with: a) || !flag.flagsToSearch.notSet.isDisjoint(with: a) + } + guard + !invalid.isEmpty + else { throw ValidationError("Invalid flag combination") } + throw ValidationError("Invalid combination of flags {\(invalid.map { "\($0)" }.joined(separator: ", "))}") + } + + // Parse string IDs to typed IDs + let emailID: EmailID? + if let emailIDString = other.emailID { + guard let parsed = EmailID(emailIDString) else { + throw ValidationError("Invalid email-id: \(emailIDString)") + } + emailID = parsed + } else { + emailID = nil + } + + let threadID: ThreadID? + if let threadIDString = other.threadID { + guard let parsed = ThreadID(threadIDString) else { + throw ValidationError("Invalid thread-id: \(threadIDString)") + } + threadID = parsed + } else { + threadID = nil + } + + if let o = other.olderThanDays, let n = other.newerThanDays { + guard + o < n + else { throw ValidationError("Messages can not be older than \(o) and newer than \(n) at the same time.") } + } + + self.init( + olderThanDays: other.olderThanDays, + newerThanDays: other.newerThanDays, + subject: other.subject, + from: other.fromAddress, + to: other.toAddress, + cc: other.ccAddress, + text: other.text, + messageSizeSmallerThan: other.messageSizeSmallerThan, + messageSizeLargerThan: other.messageSizeLargerThan, + messageID: other.messageID.map { MessageID($0) }, + emailID: emailID, + threadID: threadID, + flagsSet: flagsSet, + flagsNotSet: flagsNotSet + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/AsyncReadFile.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/AsyncReadFile.swift new file mode 100644 index 00000000..5f946f1c --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/AsyncReadFile.swift @@ -0,0 +1,88 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOCore +import NIOFileSystem +import SystemPackage +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +private let tokenBucket = TokenBucket(tokens: 20) + +extension Data { + /// Reads the contents of the file at the given path asynchronously. + init( + asyncContentsOf filePath: FilePath, + length: Int = .max + ) async throws { + let buffer = try await read( + filePath: filePath, + length: length + ) + self.init(buffer.readableBytesView) + } +} + +extension ByteBuffer { + /// Reads the contents of the file at the given path asynchronously. + init( + asyncContentsOf filePath: FilePath, + length: Int = .max + ) async throws { + self = try await read( + filePath: filePath, + length: length + ) + } +} + +private func read( + filePath: FilePath, + length: Int +) async throws -> ByteBuffer { + // Use the TokenBucket to limit concurrency. + try await tokenBucket.withToken { + try await readWithToken( + filePath: filePath, + length: length + ) + } +} + +private func readWithToken( + filePath: FilePath, + length: Int +) async throws -> ByteBuffer { + try await FileSystem.shared.withFileHandle(forReadingAt: filePath) { handle in + guard length != .max else { + return try await handle.readToEnd(maximumSizeAllowed: .unlimited) + } + // `length` is an upper bound, not the exact size to read: callers use it to + // look at just the start of a message. Reading in chunks lets us stop early + // rather than pulling a whole (potentially huge) file into memory. + var result = ByteBuffer() + for try await var chunk in handle.readChunks() { + let remaining = length - result.readableBytes + guard chunk.readableBytes < remaining else { + result.writeImmutableBuffer(chunk.readSlice(length: remaining)!) + break + } + result.writeImmutableBuffer(chunk) + } + return result + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/EmailMessage.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/EmailMessage.swift new file mode 100644 index 00000000..cd1d0e15 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/EmailMessage.swift @@ -0,0 +1,140 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP +import SystemPackage + +/// An RFC 5322 email message stored as raw data. +public struct EmailMessage: Hashable, Sendable { + var data: Data +} + +extension EmailMessage { + init(filePath: FilePath) async throws { + let input = try await Data( + asyncContentsOf: filePath + ) + // This is not entirely clean, but we want to avoid uploading + // messages with Unix file endings to an IMAP server. + guard + EmailMessage.headerIsCRLFClean(input) + else { + self = EmailMessage.convertingLineEndings(input) + return + } + self.init(data: input) + } +} + +extension EmailMessage { + /// Checks whether the message header uses CRLF line endings. + static func headerIsCRLFClean(_ input: Data) -> Bool { + let bytes = input.span + // Only the first four line breaks are inspected, and only near the start. + let limit = min(bytes.count, 10_000) + var position = 0 + var lineBreakCount = 0 + while lineBreakCount < 4, position < limit { + guard let index = bytes.firstIndexOfLineBreak(in: position.. EmailMessage { + // Convert to CRLF: + var output = Data(capacity: input.count) + let bytes = input.span + var position = 0 + while let ending = bytes.locateLineEnding(from: position) { + output.append(bytes.extracting(position.. { + /// Returns the index of the first CR or LF within `range`, or `nil` if there is none. + func firstIndexOfLineBreak(in range: Range) -> Int? { + for index in range where self[index] == 0x0D || self[index] == 0x0A { + return index + } + return nil + } + + /// Locates the next line ending at or after `start`, returning the range it + /// occupies. A CRLF pair is reported as a single two-byte ending. + func locateLineEnding(from start: Int) -> Range? { + guard let lf = firstIndexOfLineEnding(from: start) else { return nil } + // Include a preceding CR, so that CRLF is treated as one ending. + if start < lf, self[lf - 1] == 0x0D { + return (lf - 1)..<(lf + 1) + } + return lf..<(lf + 1) + } + + private func firstIndexOfLineEnding(from start: Int) -> Int? { + for index in start..) { + span.withUnsafeBufferPointer { append(contentsOf: $0) } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/InternetMessageDateParsing.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/InternetMessageDateParsing.swift new file mode 100644 index 00000000..3760d703 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/InternetMessageDateParsing.swift @@ -0,0 +1,382 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import NIOIMAP +#if canImport(Darwin) +import locale_h +import time_h +import xlocale +#endif + +extension InternetMessageDate { + /// Parses the date string. + /// + /// Performs a lenient parse as needed. It is better to return a slightly wrong date than no date at all. + func parse() -> Foundation.Date? { + return parseWithoutFoundation() ?? parseWithFoundation() + } + + /// Creates an RFC 822 formatted `DateString` from the given `Date` and `Calendar`. + /// + /// Uses the calendar’s `timeZone` to format the time zone output. + init(from date: Foundation.Date, calendar: Calendar) { + self.init(date.formatAsRFC822(calendar: calendar)) + } +} + +// MARK: - Internal Formatting + +#if canImport(Darwin) +extension Foundation.Date { + private func makeDarwinTM(calendar: Calendar) -> tm { + let components = calendar.dateComponents( + [.second, .minute, .hour, .day, .month, .year, .weekday, .timeZone], + from: self + ) + var t = tm() + t.tm_sec = Int32(components.second ?? 0) // seconds after the minute [0-60] + t.tm_min = Int32(components.minute ?? 0) // minutes after the hour [0-59] + t.tm_hour = Int32(components.hour ?? 0) // hours since midnight [0-23] + t.tm_mday = Int32(components.day ?? 1) // day of the month [1-31] + t.tm_mon = Int32(components.month ?? 1) - 1 // months since January [0-11] + t.tm_year = Int32(components.year ?? 100) - 1900 // years since 1900 + t.tm_wday = Int32(components.weekday ?? 1) - 1 // days since Sunday [0-6] + t.tm_isdst = -1 // Disables `%z` output -- because we can’t use it. + if let zone = components.timeZone { + t.tm_gmtoff = zone.secondsFromGMT(for: self) // offset from UTC in seconds + } + return t + } + + func formatAsRFC822(calendar: Calendar) -> String { + var output = [UInt8](repeating: 0, count: 80) + let byteCount = output.withUnsafeMutableBufferPointer { outputBuffer -> Int in + var t = makeDarwinTM(calendar: calendar) + return outputBuffer.withMemoryRebound(to: Int8.self) { outputBuffer -> Int in + let byteCount = strftime_l( + outputBuffer.baseAddress!, + outputBuffer.count, + "%a, %d %b %Y %H:%M:%S %z", + &t, + posixLocale + ) + guard byteCount != 0 else { return 0 } + // Print the GMT offset: + let offsetInMinutes = t.tm_gmtoff / 60 + let offsetValue = (offsetInMinutes / 60) * 100 + (offsetInMinutes % 60) + let byteCount2 = snprintf( + ptr: outputBuffer.baseAddress! + byteCount, + outputBuffer.count - byteCount, + "%+05d", + CInt(offsetValue) + ) + return byteCount + Int(byteCount2) + } + } + guard byteCount != 0, byteCount <= output.count else { fatalError() } + return output.withUnsafeBufferPointer { outputBuffer -> String in + String(cString: outputBuffer.baseAddress!) + } + } +} + +nonisolated(unsafe) let posixLocale: locale_t = newlocale(0x3f, nil, nil) +#else +extension Foundation.Date { + /// Formats the date as an RFC 822 date-time using `Foundation.DateFormatter`. + /// + /// This mirrors the Darwin `strftime`-based implementation. `DateFormatter` + /// is backed by ICU on non-Darwin platforms, and its `en_US_POSIX` locale is + /// independent of the process's C locale, so the output is stable regardless + /// of the environment's `LANG`/`LC_*` settings. The single `Z` produces the + /// numeric `±HHMM` offset RFC 822 requires. + func formatAsRFC822(calendar: Calendar) -> String { + let formatter = DateFormatter() + formatter.locale = Locale(identifier: "en_US_POSIX") + formatter.calendar = calendar + formatter.timeZone = calendar.timeZone + formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss Z" + return formatter.string(from: self) + } +} +#endif + +// MARK: - Internal Parsing + +extension InternetMessageDate { + /// Parsing without bridging into Foundation is much more performant because: + /// 1. we avoid bridging the bytes into a String and then NSString. + /// 2. we can parse almost entirely without doing allocations. + func parseWithoutFoundation() -> Foundation.Date? { + #if canImport(Darwin) + String(self).withCString { input -> Foundation.Date? in + for format in strptimeDateFormats { + if let date = scan(zeroTerminated: input, format: format) { + // Don’t return for dates before 1972. Those happen when + // a year without century is parsed as a 72 BC instead of 1972 BC. + if -900_000_000 < date.timeIntervalSinceReferenceDate { + return date + } + } + } + return nil + } + #else + // The `strptime_l`-based fast path is Darwin-only (glibc doesn't provide + // `strptime_l`). On other platforms the Foundation path handles parsing. + return nil + #endif + } + + func parseWithFoundation() -> Foundation.Date? { + let string = String(self).strippingTrailingTimeZoneName() + // Strict: + for formatter in FoundationFormatters() { + formatter.isLenient = false + if let date = formatter.date(from: string) { + return date + } + } + // Lenient: + for formatter in FoundationFormatters() { + formatter.isLenient = true + if let date = formatter.date(from: string) { + return date + } + } + return nil + } +} + +extension String { + /// Drops a trailing parenthesised time-zone name, e.g. the `(GMT)` in + /// `"Sat, 5 Sep 2020 02:25:49 +0000 (GMT)"`. + /// + /// Such a name is redundant next to the numeric offset that precedes it, but + /// `DateFormatter` has no pattern for it and fails the whole parse. The + /// Darwin `strptime` path tolerates it via `zeroTerminatedRemainderIsTimeZoneName`; + /// stripping it here gives the Foundation path the same tolerance on every platform. + fileprivate func strippingTrailingTimeZoneName() -> String { + let trimmed = self.trimmingCharacters(in: .whitespacesAndNewlines) + guard trimmed.hasSuffix(")"), let open = trimmed.lastIndex(of: "(") else { return self } + let name = trimmed[trimmed.index(after: open).., format: String) -> Foundation.Date? { + return format.withCString { formatBuffer -> Foundation.Date? in + var t = tm() + guard let r = strptime_l(inputBuffer, formatBuffer, &t, nil) else { return nil } + if !format.contains("%z") { + // Without an offset in the input the date is a local wall-clock time, and + // `strptime` leaves `tm_isdst` at 0 — asserting "standard time". `mktime` + // then reads a summer date such as "19 Aug 2003 14:49" as CET rather than + // CEST, an hour off. -1 tells `mktime` to work out DST from the date itself. + t.tm_isdst = -1 + } + let time = mktime(&t) + let date = Date(timeIntervalSince1970: TimeInterval(time)) + if r.pointee == 0 { + return date + } + // We still have more that we can parse. + // If we have already parsed a “time zone offset from UTC”, skip + // any remaining “time zone name”: + guard format.contains("%z") && zeroTerminatedRemainderIsTimeZoneName(remainder: r) else { + return nil + } + return date + } +} + +private func zeroTerminatedRemainderIsTimeZoneName(remainder: UnsafeMutablePointer) -> Bool { + let s = Scanner(string: String(cString: remainder)) + _ = s.scanUpToString("(") + guard + s.scanString("(") != nil, + s.scanCharacters(from: .uppercaseLetters) != nil, + s.scanString(")") != nil + else { return false } + _ = s.scanCharacters(from: .whitespacesAndNewlines) + guard s.isAtEnd else { return false } + return true +} +#endif + +/// Returns the same formatter repeatedly, each time configured with a different format. +private struct FoundationFormatters: Sequence { + func makeIterator() -> Iterator { + return Iterator() + } + + struct Iterator: IteratorProtocol { + var formats = foundationDateFormats.makeIterator() + + mutating func next() -> DateFormatter? { + guard let format = formats.next() else { return nil } + let formatter = makeFormatter() + formatter.dateFormat = format + return formatter + } + + /// Creates a `DateFormatter` and caches it in the current thread’s thread dictionary. + func makeFormatter() -> DateFormatter { + let key = "IMAP.protocol.dateFormatter" as NSString + if let f = Thread.current.threadDictionary[key] as? DateFormatter { + return f + } + // See also: + // https://developer.apple.com/library/archive/qa/qa1480/_index.html + let f = DateFormatter() + f.locale = Locale(identifier: "en_US_POSIX") + f.timeZone = TimeZone(secondsFromGMT: 0) + Thread.current.threadDictionary[key] = f + return f + } + } +} + +// From RFC 2822, section 3.3 +// https://tools.ietf.org/html/rfc2822#section-3.3 +// +// 3.3. Date and Time Specification +// +// Date and time occur in several header fields. This section specifies +// the syntax for a full date and time specification. Though folding +// white space is permitted throughout the date-time specification, it +// is RECOMMENDED that a single space be used in each place that FWS +// appears (whether it is required or optional); some older +// implementations may not interpret other occurrences of folding white +// space correctly. +// +// date-time = [ day-of-week "," ] date FWS time [CFWS] +// +// day-of-week = ([FWS] day-name) / obs-day-of-week +// +// day-name = "Mon" / "Tue" / "Wed" / "Thu" / +// "Fri" / "Sat" / "Sun" +// +// date = day month year +// +// year = 4*DIGIT / obs-year +// +// month = (FWS month-name FWS) / obs-month +// +// month-name = "Jan" / "Feb" / "Mar" / "Apr" / +// "May" / "Jun" / "Jul" / "Aug" / +// "Sep" / "Oct" / "Nov" / "Dec" +// +// day = ([FWS] 1*2DIGIT) / obs-day +// +// time = time-of-day FWS zone +// +// time-of-day = hour ":" minute [ ":" second ] +// +// hour = 2DIGIT / obs-hour +// +// minute = 2DIGIT / obs-minute +// +// second = 2DIGIT / obs-second +// +// zone = (( "+" / "-" ) 4DIGIT) / obs-zone + +private let foundationDateFormats: [String] = [ + // Ordered by empirical frequency in real-world mailboxes; the uncommon formats + // are here because they show up in practice despite being illegal per RFC 5322. + + // date-time with the optional day-of-week and seconds + // Note that in all the following format strings the year is specified with a single + // y instead of 4. That's because yyyy will interpret "13" as 0013 instead of 2013. + // While 2 digit dates are illegal, we're trying to be lenient here. + "EEE',' d MMM y HH':'mm':'ss ZZZ", + + // date-time with the optional day-of-week and seconds, and obs-zone + // This doesn't really work; obs-zone is the "specific non-location format" but only + // for UTC and the United States. All other zones are covered by the military format, + // but NSDateFormatter doesn't appear to support that. + "EEE',' d MMM y HH':'mm':'ss zzz", + + // this one's just plain illegal, but appeared in ~5% of a real-world sample + "EEE MMM d HH':'mm':'ss zzz y", + + // date-time without the optional day-of-week and with seconds + "d MMM y HH':'mm':'ss ZZZ", + + // date-time without the optional day-of-week, and with seconds and obs-zone + "d MMM y HH':'mm':'ss zzz", + + // date-time with the optional day-of-week and without seconds + "EEE',' d MMM y HH':'mm ZZZ", + + // date-time with the optional day-of-week and obs-zone, and without seconds + "EEE',' d MMM y HH':'mm zzz", + + // date-time without the optional day-of-week or seconds + "d MMM y HH':'mm ZZZ", + + // date-time without the optional day-of-week or seconds, and with obs-zone + "d MMM y HH':'mm zzz", + + // Illegal formats: + + "'\"'dd'-'MMM'-'y HH':'mm':'ss ZZZ'\"'", + "EEE MMM d HH':'mm':'ss y", + "y'-'MM'-'d HH':'mm':'ss ZZZ", + "EEE',' d MMM y HH':'mm':'ss", + "d MMM y HH':'mm':'ss", + "MM'/'d HH':'mm a", + "MM'/'d'/'y HH':'mm a", + "MMM d',' y HH':'mm':'ss a vvvv", + "EEE',' MMM d y HH':'mm':'ss ZZZ", + "EEE',' MMM d',' y HH':'mm zzz", + "EEE MMM d',' y HH':'mm':'ss vvvv", + "MMMM d',' y HH':'mm':'ss zzz", + // Uses `h` (1-12) rather than `HH` (0-23) because of the trailing AM/PM + // marker: ICU ignores `a` when it's paired with a 24-hour field, which made + // "3:22 PM" parse as 03:22. Darwin's `strptime` applies the marker either + // way, so this only ever misparsed on non-Darwin platforms. + "EEE',' MMM d',' y 'at' h':'mm a", +] + +#if canImport(Darwin) +private let strptimeDateFormats: [String] = [ + // These are the same ones from above, with those using "zzz" removed. + // "zzz" corresponds to time zone specifiers like "EST", but + // these abbreviations are not unique, and as such strptime_l() + // refuses to parse these. "EST" might be "Eastern Standard Time", + // "Australian Eastern Standard Time", or "European Summer Time". + + " %a, %d %b %Y %H:%M:%S %z ", + " %d %b %Y %H:%M:%S %z ", + " %a, %d %b %Y %H:%M %z ", + " %d %b %Y %H:%M %z ", + " \"%d-%b-%Y %H:%M:%S %z\" ", + " %a %b %d %H:%M:%S %Y ", + " %Y-%m-%d %H:%M:%S %z ", + " %a, %d %b %Y %H:%M:%S ", + " %d %b %Y %H:%M:%S ", + " %m/%d %H:%M %p ", + " %m/%d/%Y %H:%M %p ", + " %a, %b %d %Y %H:%M:%S %z ", + " %a, %b %d, %Y at %H:%M %p ", +] +#endif diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageCreationOptions.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageCreationOptions.swift new file mode 100644 index 00000000..02eb3f9b --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageCreationOptions.swift @@ -0,0 +1,33 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +/// Options that control message generation for testing and seeding. +struct MessageCreationOptions: ParsableArguments { + init() {} + + /// The number of messages to create or use. + @Option(help: "Number of messages to create or use.") + var messageCount: Int = 43 + + /// The seed for deterministic message generation. + @Option(help: "A seed for message generation.") + var messageSeed: SeededRandomNumberGenerator.Seed = .default +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageFlag.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageFlag.swift new file mode 100644 index 00000000..ff8f7c65 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageFlag.swift @@ -0,0 +1,103 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import NIOIMAP + +enum MessageFlag: String, Hashable, CaseIterable, ExpressibleByArgument { + /// `\Answered` + case answered + /// `\Flagged` + case flagged + /// `\Deleted` + case deleted + /// `\Seen` + case seen + /// `\Draft` + case draft + + case red + case orange + case yellow + case green + case blue + case purple + case gray +} + +extension MessageFlag { + var flagsToSearch: FlagsToSearch { + switch self { + case .answered, .flagged, .deleted, .seen, .draft: + return FlagsToSearch( + set: flagsToSet, + notSet: [] + ) + case .red, .orange, .yellow, .green, .blue, .purple, .gray: + let allColorBits: Set = [.mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + return FlagsToSearch( + set: flagsToSet, + notSet: allColorBits.subtracting(flagsToSet) + ) + } + } + + struct FlagsToSearch: Sendable, Hashable { + var set: Set + var notSet: Set + } +} + +extension MessageFlag { + var flagsToSet: Set { + switch self { + case .answered: [.answered] + case .flagged: [.flagged] + case .deleted: [.deleted] + case .seen: [.seen] + case .draft: [.draft] + case .red: [.flagged] + case .orange: [.flagged, .mailFlagBit0] + case .yellow: [.flagged, .mailFlagBit1] + case .green: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + case .blue: [.flagged, .mailFlagBit2] + case .purple: [.flagged, .mailFlagBit0, .mailFlagBit2] + case .gray: [.flagged, .mailFlagBit1, .mailFlagBit2] + } + } + + var flagsToUnset: Set { + switch self { + case .answered: [.answered] + case .flagged: [.flagged] + case .deleted: [.deleted] + case .seen: [.seen] + case .draft: [.draft] + case .red, + .orange, + .yellow, + .green, + .blue, + .purple, + .gray: + [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + } + } +} + +extension NIOIMAP.Flag { + static var mailFlagBit0: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit0") } + static var mailFlagBit1: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit1") } + static var mailFlagBit2: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit2") } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageHeaderParsing.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageHeaderParsing.swift new file mode 100644 index 00000000..07fcfcc6 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageHeaderParsing.swift @@ -0,0 +1,63 @@ +//===----------------------------------------------------------------------===// +// +// 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 Synchronization +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +/// Parses the small set of message headers that `IMAPToolLib` needs when +/// appending messages to a mailbox. +/// +/// `IMAPToolLib` ships with a minimal, dependency-free implementation +/// (``MiniMIMEHeaderParser``). An embedding tool can install a richer parser +/// (for example, one backed by a full MIME parser) via +/// ``MessageHeaderParser/current``. +public protocol MessageHeaderParsing: Sendable { + /// Parses just the `Date` header from the given message data. + func dateHeader(_ data: Data) -> InternetMessageDate? + + /// Parses the headers needed to append the given message. + func headersOfInterest(_ data: Data) -> EmailMessage.HeadersOfInterest? +} + +/// The minimal header parser used by default. It does not handle header folding +/// (continuation lines) and only understands `Date` and `Message-ID`. +struct MiniMIMEHeaderParser: MessageHeaderParsing { + init() {} + + func dateHeader(_ data: Data) -> InternetMessageDate? { + MIMEMessage.data(data).dateHeader() + } + + func headersOfInterest(_ data: Data) -> EmailMessage.HeadersOfInterest? { + MIMEMessage.data(data).headersOfInterest() + } +} + +/// The message header parser used throughout `IMAPToolLib`. +/// +/// Defaults to ``MiniMIMEHeaderParser``. Embedders can replace it before running +/// any command. +public enum MessageHeaderParser { + private static let _current = Mutex(MiniMIMEHeaderParser()) + + public static var current: any MessageHeaderParsing { + get { _current.withLock { $0 } } + set { _current.withLock { $0 = newValue } } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageInfo.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageInfo.swift new file mode 100644 index 00000000..39c194de --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MessageInfo.swift @@ -0,0 +1,139 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +/// A summary of a fetched message, including its envelope and flags. +struct MessageInfo: Sendable, Hashable, Encodable { + /// The UID of the message. + var uid: UID + /// The RFC 2822 date string from the envelope. + var date: String? + /// The date as seconds since the Unix epoch. + var dateSeconds: Double? + /// The subject line of the message. + var subject: String? + /// The sender of the message. + var from: String? + /// The primary recipients of the message. + var to: String? + /// The carbon-copy recipients of the message. + var cc: String? + /// The `Message-ID` header value. + var messageID: String? + /// The `In-Reply-To` header value. + var inReplyTo: String? + /// The flags set on the message. + var flags: [String] + + func encode(to encoder: Encoder) throws { + var c = encoder.container(keyedBy: CodingKeys.self) + try c.encode(UInt32(uid), forKey: .uid) + try c.encodeIfPresent(date, forKey: .date) + try c.encodeIfPresent(dateSeconds, forKey: .dateSeconds) + try c.encodeIfPresent(subject, forKey: .subject) + try c.encodeIfPresent(from, forKey: .from) + try c.encodeIfPresent(to, forKey: .to) + try c.encodeIfPresent(cc, forKey: .cc) + try c.encodeIfPresent(messageID, forKey: .messageID) + try c.encodeIfPresent(inReplyTo, forKey: .inReplyTo) + try c.encode(flags, forKey: .flags) + } + + enum CodingKeys: String, CodingKey { + case uid + case date + case dateSeconds + case subject + case from + case to + case cc + case messageID + case inReplyTo + case flags + } +} + +extension MessageInfo { + init?( + uid: UID, + attributes: [MessageAttribute] + ) { + var uid: UID = uid + var envelope: Envelope? + var flags: [Flag]? + + for attribute in attributes { + switch attribute { + case .uid(let u): + uid = u + case .envelope(let e): + envelope = e + case .flags(let f): + flags = f + default: + break + } + } + guard + let envelope, + let flags + else { return nil } + self.init(uid: uid, envelope: envelope, flags: flags) + } + + init(uid: UID, envelope: Envelope, flags: [Flag]) { + self.uid = uid + let date = envelope.date.map { String($0) } + self.date = date + if let date, let seconds = InternetMessageDate(date).parse() { + self.dateSeconds = seconds.timeIntervalSince1970 + } + self.subject = envelope.subject.map { String(buffer: $0) } + self.from = envelope.from.isEmpty ? nil : String(envelope.from) + self.to = envelope.to.isEmpty ? nil : String(envelope.to) + self.cc = envelope.cc.isEmpty ? nil : String(envelope.cc) + self.messageID = envelope.messageID.map { String($0) } + self.inReplyTo = envelope.inReplyTo.map { String($0) } + self.flags = flags.map { String($0) } + } +} + +extension String { + fileprivate init(_ list: [EmailAddressListElement]) { + self = + list + .map { + String($0) + } + .joined(separator: ", ") + } + + fileprivate init(_ listElement: EmailAddressListElement) { + switch listElement { + case .singleAddress(let address): + switch (address.personName, address.mailbox, address.host) { + case (let name?, let mailbox?, let host?): + self = "\"\(String(buffer: name))\" <\(String(buffer: mailbox))@\(String(buffer: host))>" + case (_, let mailbox?, let host?): + self = "\(String(buffer: mailbox))@\(String(buffer: host))" + default: + self = "<>" + } + case .group(let group): + let groupName = String(buffer: group.groupName) + self = "\"\(groupName)\": {\(String(group.children))}" + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Message/MiniMIME.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MiniMIME.swift new file mode 100644 index 00000000..f0e170c9 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Message/MiniMIME.swift @@ -0,0 +1,150 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOCore +import NIOIMAP + +// Does not handle header folding (continuation lines). +enum MIMEMessage { + case data(Data) + case byteBuffer(ByteBuffer) + + func dateHeader() -> InternetMessageDate? { + withContiguousBytes { buffer in + var result: InternetMessageDate? + enumerateHeaderLines(in: buffer) { name, value in + if caseInsensitiveEqual(name, "date") { + result = InternetMessageDate(trimmedString(value)) + return false + } + return true + } + return result + } + } + + func messageIDHeader() -> MessageID? { + withContiguousBytes { buffer in + var result: MessageID? + enumerateHeaderLines(in: buffer) { name, value in + if caseInsensitiveEqual(name, "message-id") { + result = MessageID(trimmedString(value)) + return false + } + return true + } + return result + } + } + + func headersOfInterest() -> EmailMessage.HeadersOfInterest? { + withContiguousBytes { buffer in + var date: InternetMessageDate? + var messageID: MessageID? + enumerateHeaderLines(in: buffer) { name, value in + if caseInsensitiveEqual(name, "date") { + date = InternetMessageDate(trimmedString(value)) + } else if caseInsensitiveEqual(name, "message-id") { + messageID = MessageID(trimmedString(value)) + } + return date == nil || messageID == nil + } + guard let date, let messageID else { return nil } + return EmailMessage.HeadersOfInterest(messageID: messageID, date: date) + } + } +} + +// MARK: - Internal + +extension MIMEMessage { + func withContiguousBytes(_ body: (Span) -> R) -> R { + switch self { + case .data(let data): + return body(data.span) + case .byteBuffer(let buffer): + return buffer.withUnsafeReadableBytes { body($0.bindMemory(to: UInt8.self).span) } + } + } + + /// Iterates header lines, calling `body` with the header name and value + /// portions of each line. Stops at the first empty line (end of headers) + /// or when `body` returns `false`. + func enumerateHeaderLines( + in buffer: Span, + body: (_ name: Span, _ value: Span) -> Bool + ) { + var position = 0 + let count = buffer.count + + while position < count { + let lineStart = position + while position < count && buffer[position] != UInt8(ascii: "\n") { + position += 1 + } + var lineEnd = position + if lineEnd > lineStart && buffer[lineEnd - 1] == UInt8(ascii: "\r") { + lineEnd -= 1 + } + if position < count { + position += 1 + } + + if lineEnd == lineStart { return } + + // Find the colon separating name from value. + var colonIndex = lineStart + while colonIndex < lineEnd && buffer[colonIndex] != UInt8(ascii: ":") { + colonIndex += 1 + } + guard colonIndex < lineEnd else { continue } + + let name = buffer.extracting(lineStart.., + _ expected: StaticString + ) -> Bool { + guard buffer.count == expected.utf8CodeUnitCount else { return false } + return expected.withUTF8Buffer { expectedBytes in + for i in 0..= 0x41 && b <= 0x5A) ? b | 0x20 : b + if lower != expectedBytes[i] { return false } + } + return true + } + } + + private func trimmedString(_ buffer: Span) -> String { + var start = 0 + var end = buffer.count + while start < end && (buffer[start] == UInt8(ascii: " ") || buffer[start] == UInt8(ascii: "\t")) { + start += 1 + } + while end > start && (buffer[end - 1] == UInt8(ascii: " ") || buffer[end - 1] == UInt8(ascii: "\t")) { + end -= 1 + } + return buffer.extracting(start.. + + var isEmpty: Bool { + uids.isEmpty && messageIDs.isEmpty + } +} + +extension UIDsAndMessageIDs { + init( + filePath: String?, + uids: [UID], + messageIDs: [MessageID] + ) throws { + if let filePath { + self = try Self.parse(filePath: filePath) + } else { + self.init(uids: [], messageIDs: []) + } + self.uids.formUnion(UIDSet(uids)) + self.messageIDs.formUnion(messageIDs) + } +} + +extension UIDsAndMessageIDs { + static func parse( + filePath: String + ) throws -> UIDsAndMessageIDs { + let json = try Data(contentsOf: URL(filePath: filePath, directoryHint: .notDirectory)) + return try Self.parse(input: json) + } + + static func parse( + input: Data + ) throws -> UIDsAndMessageIDs { + var uids = UIDSet() + var ids = Set() + for m in try parseMessages(input: input) { + switch m { + case .uid(let uid): uids.insert(uid) + case .messageID(let id): ids.insert(id) + } + } + return UIDsAndMessageIDs( + uids: uids, + messageIDs: ids + ) + } + + enum MessageInfo { + case uid(UID) + case messageID(MessageID) + } + + static func parseMessages(input: Data) throws -> [MessageInfo] { + struct Messages: Decodable { + var messages: [Message] + + struct Message: Decodable { + var uid: UInt32? + var id: String? + } + } + + let decoder = JSONDecoder() + decoder.allowsJSON5 = true + let m = try decoder.decode(Messages.self, from: input) + return m.messages.compactMap { raw -> MessageInfo? in + if let u = raw.uid, let uid = UID(exactly: u) { + return .uid(uid) + } else if let id = raw.id { + guard + id.first == "<", + id.last == ">" + else { return nil } + return .messageID(MessageID(id)) + } else { + return nil + } + } + } +} + +extension ConnectionProtocol { + func findMessageIDs( + selectInfo: SelectInfo, + capabilities: [Capability], + ids: UIDsAndMessageIDs + ) async throws -> UIDSet { + guard + let key = SearchKey.messageID(ids.messageIDs) + else { return ids.uids } + + let new = try await search( + capabilities: capabilities, + key: key + ) + return ids.uids.union(new) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/ConnectionProtocol.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/ConnectionProtocol.swift new file mode 100644 index 00000000..0698689b --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/ConnectionProtocol.swift @@ -0,0 +1,52 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIO +import NIOIMAP + +/// A protocol for sending commands and receiving responses, enabling testability. +/// +/// In production, this is always an ``IMAPConnection``. In tests, a mock can send +/// simple commands without requiring `AUTHENTICATE` or `APPEND` support. +/// +/// ## Where the operations live +/// +/// The operations in `IMAPToolLib/Operations` are methods on the connection, so they read +/// as `connection.listMailboxes(capabilities:)`. Most are declared in an +/// `extension ConnectionProtocol`, and that is what keeps them testable: they reach the +/// server only through `send(_:_:)`, the single protocol requirement, so a mock that +/// implements `send` gets all of them for free. +/// +/// A few — `append`, `authenticate`, `runIdle` — are declared in an `extension IMAPConnection` +/// instead, because they use methods (`append`, `sendAuthenticate`, `sendIdle`) that are not +/// part of this protocol. Those methods deal with continuation-driven flows (literals, SASL +/// challenges, IDLE) that don't fit the simple "send a `Command`, consume the +/// `IMAPConnection.ResponseStream`" shape, so adding them here would complicate the mock +/// surface used by tests. +/// +/// ## Closure isolation +/// +/// The requirement mirrors `IMAPConnection.send(_:_:)`: the handler is +/// `nonisolated(nonsending)`, so it needs to be neither `@Sendable` nor `@escaping` and runs in +/// the caller's isolation domain. Unlike an `isolated (any Actor)?` parameter — which a protocol +/// requirement cannot give a default argument — this needs nothing at the call site. +protocol ConnectionProtocol: Sendable { + func send( + _ command: Command, + _ handler: nonisolated(nonsending) (IMAPConnection.Tag, IMAPConnection.ResponseStream) async throws -> Result + ) async throws -> Result +} + +extension IMAPConnection: ConnectionProtocol {} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Data.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Data.swift new file mode 100644 index 00000000..3ec961e3 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Data.swift @@ -0,0 +1,39 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO + +extension ByteBuffer { + init(_ other: Data) { + self.init() + // `Data` is a `Collection` of `UInt8`, so this needs no pointer access. + writeBytes(other) + } + + init(_ other: String) { + self.init(other.data(using: .utf8)!) + } +} + +extension Data { + init(_ other: ByteBuffer) { + // `readableBytesView` is a `Collection` of the buffer's readable bytes. + self.init(other.readableBytesView) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/DirectoryWalk.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/DirectoryWalk.swift new file mode 100644 index 00000000..9647da64 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/DirectoryWalk.swift @@ -0,0 +1,96 @@ +//===----------------------------------------------------------------------===// +// +// 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 SystemPackage +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif + +// MARK: - Directory walk helpers +// +// Both `DownloadDirectory` (`*.message` parsing) and `Append_Files` +// (regular-file enumeration) need to walk a directory and inspect each +// `dirent` entry. The pointer gymnastics around `d_name` (POSIX gives us a +// fixed-size C array; we want a Swift buffer) and the `opendir`/`readdir` +// iteration live here so the call sites can stay focused on their own logic. + +/// Calls `closure` once for each entry in `directory`. +/// +/// Iterates the directory with `opendir(3)` / `readdir(3)` / `closedir(3)`, +/// which are available on both Darwin and Glibc. Entries are returned in +/// directory order (unsorted). +/// +/// Throws `UnableToScanDirectory` if the directory can't be opened or if +/// reading an entry fails. +func scan( + directory: FilePath, + closure: (UnsafePointer) -> Void +) throws { + guard let dir = directory.withPlatformString({ opendir($0) }) else { + throw UnableToScanDirectory() + } + defer { closedir(dir) } + while true { + // `readdir` returns `nil` both at end-of-directory and on error. It + // leaves `errno` untouched at end-of-directory, so reset it first and + // check afterwards to tell the two apart. + errno = 0 + guard let entry = readdir(dir) else { + guard errno == 0 else { throw UnableToScanDirectory() } + break + } + closure(UnsafePointer(entry)) + } +} + +struct UnableToScanDirectory: Swift.Error {} + +/// If `entry` describes a regular file, invokes `body` with the file name as a +/// UTF-8 span (no NUL terminator) and returns its result. Returns `nil` if the +/// entry is not a regular file or if `body` itself returns `nil`. +/// +/// The span is only valid for the duration of `body` — copy out anything you +/// need to keep. +/// +/// - Note: On filesystems that don't report a `d_type` (returning `DT_UNKNOWN`), +/// entries are skipped. That doesn't occur on the local filesystems this tool +/// targets, but a fully general implementation would `stat` such entries. +func withRegularFileName( + dirent entry: UnsafePointer, + _ body: (Span) -> R? +) -> R? { + guard entry.pointee.d_type == DT_REG else { return nil } + // `d_name` is a fixed-size C array. Darwin also carries the exact length in + // `d_namlen`, but Glibc's `dirent` has no such field, so on other platforms + // we find the NUL terminator within the array ourselves. + let capacity = MemoryLayout.size(ofValue: entry.pointee.d_name) + return withUnsafePointer(to: entry.pointee.d_name) { pointer in + pointer.withMemoryRebound( + to: Unicode.UTF8.CodeUnit.self, + capacity: capacity + ) { rebound in + #if canImport(Darwin) + let count = Int(entry.pointee.d_namlen) + #else + var count = 0 + while count < capacity, rebound[count] != 0 { + count += 1 + } + #endif + return body(UnsafeBufferPointer(start: rebound, count: count).span) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/SeededRandomNumberGenerator.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/SeededRandomNumberGenerator.swift new file mode 100644 index 00000000..28b62485 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/SeededRandomNumberGenerator.swift @@ -0,0 +1,119 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +// `Scanner`/`CharacterSet` are not part of `FoundationEssentials`. +import Foundation + +/// Generates deterministic pseudo-random numbers from a fixed seed. +struct SeededRandomNumberGenerator: RandomNumberGenerator { + fileprivate struct State { + var state: UInt64 + var inc: UInt64 + } + + fileprivate var state: State + + /// Creates a generator with the given seed. + init(_ seed: Seed) { + self.state = State(state: seed.a, inc: seed.b) + } + + /// Creates a generator with two raw state values. + init(_ a: UInt64, _ b: UInt64) { + self.state = State(state: a, inc: b) + } + + /// Returns the next random `UInt64` value. + mutating func next() -> UInt64 { + UInt64(self.state.next()) << 32 | UInt64(self.state.next()) + } + + /// Returns the next random `UInt32` value. + mutating func next() -> UInt32 { + self.state.next() + } +} + +extension SeededRandomNumberGenerator.State { + /// Advances the state and returns the next random `UInt32` value. + mutating func next() -> UInt32 { + let oldstate = self.state + self.state = oldstate &* 6_364_136_223_846_793_005 &+ (inc | 1) + let xorshifted: UInt64 = ((oldstate >> 18) ^ oldstate) >> 27 + let rot: UInt64 = oldstate >> 59 + let irot = UInt64(bitPattern: -Int64(bitPattern: rot)) + let result: UInt64 = (xorshifted >> rot) | (xorshifted << (irot & 31)) + return UInt32(result & UInt64(UInt32.max)) + } +} + +extension SeededRandomNumberGenerator { + /// A pair of values that initializes the random number generator state. + struct Seed: Equatable { + /// The first state component. + var a: UInt64 + /// The second state component. + var b: UInt64 + + /// Creates a seed with the given state components. + init(a: UInt64, b: UInt64) { + self.a = a + self.b = b + } + } +} + +extension SeededRandomNumberGenerator.Seed: ExpressibleByArgument { + /// The default seed value. + static var `default`: SeededRandomNumberGenerator.Seed { + SeededRandomNumberGenerator.Seed(a: 0x3501_404A_0218_5150, b: 0xF23C_78DA_2C09_7E04) + } + + /// Creates a seed by parsing a hex-prefixed string argument. + init?(argument: String) { + guard + let a = SeededRandomNumberGenerator.Seed(hexPrefixed: argument) + else { return nil } + self = a + } + + init?(hexPrefixed string: String) { + let scanner = Scanner(string: string) + guard scanner.scanString("hex:") != nil else { return nil } + scanner.charactersToBeSkipped = CharacterSet(charactersIn: " _") + var values: [UInt8] = [] + while !scanner.isAtEnd { + guard + let a = scanner.scanCharacter(), + let b = scanner.scanCharacter(), + let c = UInt8(String([a, b]), radix: 16) + else { return nil } + values.append(c) + } + guard values.count == 16 else { return nil } + + var remaining = values[...] + func pop() -> UInt64 { + var r = 0 as UInt64 + for _ in 0..<8 { + r *= 256 + r += UInt64(remaining.popFirst()!) + } + return r + } + + self.init(a: pop(), b: pop()) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Span.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Span.swift new file mode 100644 index 00000000..ae9965e6 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/Span.swift @@ -0,0 +1,23 @@ +//===----------------------------------------------------------------------===// +// +// 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 Span { + /// Decodes the bytes as UTF-8, repairing any ill-formed sequences. + /// + /// `Span` is not a `Collection`, so `String(decoding:as:)` can’t take it + /// directly. This borrows the underlying buffer for the length of the call. + var utf8String: String { + withUnsafeBufferPointer { String(decoding: $0, as: UTF8.self) } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/StableMailboxNameSorting.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/StableMailboxNameSorting.swift new file mode 100644 index 00000000..f3a1e09b --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/StableMailboxNameSorting.swift @@ -0,0 +1,30 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +func stableCompare( + _ lhs: MailboxName, + _ rhs: MailboxName +) -> Bool { + switch (lhs.isInbox, rhs.isInbox) { + case (true, false): return true + case (true, true): return false + case (false, true): return false + case (false, false): break + } + // Byte-wise ordering, with a shorter name sorting before a longer one that + // shares its prefix — the same ordering `memcmp` plus a length tie-break gives. + return lhs.bytes.lexicographicallyPrecedes(rhs.bytes) +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Misc/TokenBucket.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/TokenBucket.swift new file mode 100644 index 00000000..08d6562c --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Misc/TokenBucket.swift @@ -0,0 +1,87 @@ +//===----------------------------------------------------------------------===// +// +// 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 DequeModule + +/// Lets us limit concurrency. +actor TokenBucket { + private var tokens: Int + private var waiters: Deque + private var nextWaiterID = 0 + + private struct Waiter { + var id: Int + var continuation: CheckedContinuation + } + + init(tokens: Int) { + self.tokens = tokens + self.waiters = Deque() + } + + func withToken( + _ body: () async throws -> ReturnType + ) async throws -> ReturnType { + try await self.getToken() + defer { + self.returnToken() + } + + return try await body() + } + + private func getToken() async throws { + if self.tokens > 0 { + self.tokens -= 1 + return + } + + let id = self.nextWaiterID + self.nextWaiterID += 1 + + // Park until a token is returned to us — but honor cancellation, so a + // cancelled task doesn't stay parked forever (and doesn't consume a + // token it never received). + try await withTaskCancellationHandler { + try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in + // If we were cancelled before parking, don't park at all. + if Task.isCancelled { + continuation.resume(throwing: CancellationError()) + return + } + self.waiters.append(Waiter(id: id, continuation: continuation)) + } + } onCancel: { + Task { await self.cancelWaiter(id: id) } + } + } + + private func cancelWaiter(id: Int) { + guard let index = self.waiters.firstIndex(where: { $0.id == id }) else { + // The waiter was already granted a token by `returnToken`; that + // path stays balanced via the holder's `defer returnToken()`. + return + } + let waiter = self.waiters.remove(at: index) + waiter.continuation.resume(throwing: CancellationError()) + } + + private func returnToken() { + if let nextWaiter = self.waiters.popFirst() { + nextWaiter.continuation.resume() + } else { + self.tokens += 1 + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append.swift new file mode 100644 index 00000000..d138ae97 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append.swift @@ -0,0 +1,323 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP +import NIO +import Synchronization +import SystemPackage + +extension IMAPConnection { + /// Uploads (`APPEND`s) the given messages into the given mailbox. + /// + /// Selects the target mailbox first to receive any updates to it. + func append( + messages: some AsyncSequence, any Swift.Error>, + into mailbox: MailboxName, + createMailbox: SelectCreateOption + ) async throws -> [AppendedMessageInfo] { + let info = try await select( + mailbox: mailbox, + createMailbox: createMailbox + ) + + var result: [AppendedMessageInfo] = [] + + var messageCount = 0 + for try await message in messages { + messageCount += 1 + + let uidAppend = try await append( + message: message, + into: mailbox + ) + let uid = singleAppendUIDFromResponse( + uidAppend: uidAppend, + uidValidity: info.uidValidity, + messageCount: messageCount + ) + result.append(AppendedMessageInfo(messageID: message.messageID, uid: uid, id: message.id)) + } + + writeStatus("Did append \(result.count) message(s)") + return result + } +} + +/// Metadata about a message that was successfully appended via `APPEND`. +struct AppendedMessageInfo: Sendable { + /// The RFC 2822 `Message-ID` header value of the appended message. + var messageID: MessageID + /// The server-assigned `UID` from the `APPENDUID` response code, or `nil` + /// if the server did not return one (e.g. no `UIDPLUS` support). + var uid: UID? + /// The caller-supplied identifier originally passed in via ``MessageToAppend/id``. + var id: ID +} + +/// Extracts the ``UID`` from the ``ResponseCodeAppend`` (`APPENDUID`, part of `UIDPLUS`). +/// +/// This helper assumes a single-message `APPEND`, and returns `nil` if the +/// `APPENDUID` response code contains anything other than exactly one UID. +/// It is therefore not suitable for `MULTIAPPEND` (RFC 3502) responses. +private func singleAppendUIDFromResponse( + uidAppend: ResponseCodeAppend?, + uidValidity: UIDValidity, + messageCount: Int +) -> UID? { + guard + let uidAppend + else { + writeStatus("[\(messageCount)] Server did not send APPENDUID for message") + return nil + } + guard + uidAppend.uidValidity == uidValidity + else { + writeStatus("[\(messageCount)] UIDVALIDITY in APPENDUID differs from mailbox UIDVALIDITY") + return nil + } + guard + uidAppend.uids.set.count == 1 + else { + writeStatus("[\(messageCount)] APPENDUID has \(uidAppend.uids.set.count) UIDs, only expected 1") + return nil + } + let uid = uidAppend.uids.min() + writeStatus("[\(messageCount)] New message has UID \(uid)") + return uid +} + +extension IMAPConnection { + /// Sends an `APPEND` for the given message. + func append( + message: MessageToAppend, + into mailbox: MailboxName + ) async throws -> ResponseCodeAppend? { + let options = AppendOptions( + flagList: message.flags ?? [], + internalDate: message.serverMessageDate + ) + + let tagged: TaggedResponse = try await append( + to: mailbox, + writing: { tag, writer in + writeStatus("Appending message \(message.messageID) with tag \(tag)") + try await writer.write( + message: AppendMessage( + options: options, + data: AppendData( + byteCount: message.byteCount + ) + ) + ) { writer in + for await bytes in message.data { + writeStatus("Sending \(bytes.readableBytes) message bytes") + try await writer.write(messageBytes: bytes) + } + } + }, + reading: { _, responses in + try await responses.waitForCompletion() + } + ) + guard + case .ok(let text) = tagged.state + else { + writeStatus("error: failed to append (\(tagged.state))") + throw FailedToAppendMessage(state: tagged.state) + } + guard + case .uidAppend(let c) = text.code + else { return nil } + return c + } +} + +struct FailedToAppendMessage: Equatable, Swift.Error { + var state: TaggedResponse.State +} + +extension AppendedMessageInfo where ID == FilePath { + /// The file path the message was loaded from. + var filePath: FilePath { id } +} + +// MARK: MessageToAppend + +/// A message to upload via `APPEND`, including its metadata and byte stream. +struct MessageToAppend: Sendable { + /// The total number of bytes in the message. + var byteCount: Int + /// A generic ID for this message, such as a file path or a counter. + var id: ID + /// The RFC 2822 `Message-ID` header value. + var messageID: MessageID + /// A sequence of bytes that make up the message. The total byte count must match `byteCount`. + var data: AsyncStream + /// The flags to set on the message, or `nil` to use defaults. + var flags: [Flag]? + /// The internal date to assign to the message on the server. + var serverMessageDate: ServerMessageDate? + /// The subject of the message, for display purposes. + var subject: String? +} + +struct UnableToParseMessageID: Swift.Error { + var id: ID +} + +extension MessageToAppend { + /// Creates a message to append from an already-parsed email message. + init( + message other: EmailMessage, + id: ID + ) throws { + guard + let headers = other.headersOfInterest + else { throw UnableToParseMessageID(id: id) } + let dataStream = AsyncStream( + ByteBuffer.self, + { continuation in + continuation.yield(with: .success(ByteBuffer(bytes: other.data))) + continuation.finish() + } + ) + self.init( + byteCount: other.data.count, + id: id, + messageID: headers.messageID, + data: dataStream, + flags: nil, + serverMessageDate: ServerMessageDate(headers.date), + subject: headers.subject + ) + } +} + +extension ServerMessageDate { + init?( + _ other: InternetMessageDate, + ) { + guard + let date = other.parse() + else { return nil } + + var calendar = Calendar(identifier: .gregorian) + calendar.timeZone = .gmt + + let c = calendar.dateComponents( + [ + .year, + .month, + .day, + .hour, + .minute, + .second, + .timeZone, + ], + from: date + ) + guard + let year = c.year, + let month = c.month, + let day = c.day, + let hour = c.hour, + let minute = c.minute, + let second = c.second, + let timeZone = c.timeZone, + let cc = ServerMessageDate.Components( + year: year, + month: month, + day: day, + hour: hour, + minute: minute, + second: second, + timeZoneMinutes: timeZone.secondsFromGMT() / 60 + ) + else { return nil } + self.init(cc) + } +} + +extension MessageToAppend: AsyncSequence { + struct AsyncIterator: AsyncIteratorProtocol { + typealias Element = NIOIMAP.AppendCommand + + var state: State + + enum State { + case beginMessage(MessageToAppend) + case messageBytes(AsyncStream.Iterator) + case endMessage + } + + mutating func next() async throws -> NIOIMAP.AppendCommand? { + try await next(isolation: #isolation) + } + + /// Both `next` overloads are implemented, and the isolation is forwarded to the wrapped + /// `AsyncStream` iterator, because neither iterator is `Sendable`: falling back to + /// `AsyncIteratorProtocol`'s default implementation of `next(isolation:)` — which calls + /// the `@concurrent` `next()` — would send them out of the caller's isolation domain. + mutating func next( + isolation actor: isolated (any Actor)? + ) async throws -> NIOIMAP.AppendCommand? { + switch state { + case .beginMessage(let message): + state = .messageBytes(message.data.makeAsyncIterator()) + return .beginMessage(message: AppendMessage(message)) + case .messageBytes(var data): + guard + let bytes = await data.next(isolation: actor) + else { + state = .endMessage + return .endMessage + } + state = .messageBytes(data) + return .messageBytes(bytes) + case .endMessage: + return nil + } + } + + init( + message: MessageToAppend + ) { + self.state = .beginMessage(message) + } + } + + func makeAsyncIterator() -> AsyncIterator { + AsyncIterator(message: self) + } +} + +extension AppendMessage { + init(_ message: MessageToAppend) { + self.init( + options: AppendOptions( + flagList: message.flags ?? [], + internalDate: message.serverMessageDate, + extensions: [:] + ), + data: AppendData(byteCount: message.byteCount) + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append_Files.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append_Files.swift new file mode 100644 index 00000000..69cd5a26 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Append_Files.swift @@ -0,0 +1,422 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIO +import NIOIMAP +import SystemPackage +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +extension IMAPConnection { + /// Uploads (`APPEND`s) the given messages into the given mailbox. + /// + /// Selects the target mailbox first to receive any updates to it. + func append( + messages: [FilePath], + options: Set, + into mailbox: MailboxName + ) async throws -> [AppendedMessageInfo] { + try await append( + messages: FileBasedMessageToAppendSequence( + paths: messages, + options: options + ), + into: mailbox, + createMailbox: SelectCreateOption(options) + ) + } +} + +/// Options that control the behavior of an `APPEND` operation. +enum AppendOption: Hashable, Sendable { + /// Skips files that fail to parse instead of aborting. + case skipErrors + /// Sorts messages by date before uploading. + case sort + /// Creates the target mailbox with the given parameters if it does not exist. + case createMailbox([CreateParameter]) + /// Sets these flags on all appended messages. + case flags([NIOIMAP.Flag]) +} + +extension SelectCreateOption { + init( + _ other: Set + ) { + for option in other { + if case .createMailbox(let parameters) = option { + self = .create(parameters) + return + } + } + self = .fail + } +} + +// MARK: - + +/// An async sequence that reads email message files from disk and yields them as `MessageToAppend` values. +struct FileBasedMessageToAppendSequence: AsyncSequence, Sendable { + typealias Element = MessageToAppend + typealias Failure = any Swift.Error + + /// The file paths to read messages from. + let paths: [FilePath] + /// The options controlling how messages are read and processed. + let options: Set + + /// Creates a new sequence from the given file paths and options. + init( + paths: [FilePath], + options: Set + ) { + self.paths = paths + self.options = options + } + + struct AsyncIterator: AsyncIteratorProtocol { + typealias Failure = any Swift.Error + + fileprivate let paths: [FilePath] + fileprivate let options: Set + var remainingPaths: ArraySlice? + private var sorted: Sorted = .initial + + fileprivate init( + paths: [FilePath], + options: Set + ) { + self.paths = paths + self.options = options + } + + private enum Sorted { + case initial + case isReading + case sorted([FilePathWithDate]) + } + + mutating func next() async throws -> MessageToAppend? { + let flags = extractFlags(from: options) + while true { + guard + let pathWithDate = try await nextPath() + else { return nil } + do { + var message = try await MessageToAppend( + message: EmailMessage(filePath: pathWithDate.filePath), + id: pathWithDate.filePath + ) + if !flags.isEmpty { + message.flags = flags + } + return message + } catch { + writeStatus("error: failed to read message \(pathWithDate.filePath)") + guard options.contains(.skipErrors) else { throw error } + } + } + } + + private func extractFlags(from options: Set) -> [NIOIMAP.Flag] { + for option in options { + if case .flags(let flags) = option { + return flags + } + } + return [] + } + + private mutating func nextPath() async throws -> FilePathWithDate? { + var remaining: ArraySlice + if let r = remainingPaths { + remaining = r + } else { + remaining = try await sortedPaths()[...] + } + guard let next = remaining.popFirst() else { return nil } + remainingPaths = remaining + return next + } + + private mutating func sortedPaths() async throws -> [FilePathWithDate] { + switch sorted { + case .initial: + sorted = .isReading + let paths = try await FileBasedMessageToAppendSequence.readAndSort( + paths: paths, + options: options + ) + sorted = .sorted(paths) + return paths + case .isReading: + fatalError("Recursively calling next() ?!?") + case .sorted(let array): + return array + } + } + } + + func makeAsyncIterator() -> AsyncIterator { + AsyncIterator( + paths: paths, + options: options + ) + } +} + +extension FileBasedMessageToAppendSequence { + struct IndexedFilePath: Hashable, Sendable { + /// The index of the input argument (the order in which files were passed to the imap-tool). + var originalIndex: UInt32 + /// If the input was a directory, this is the (relatively random) index within that directory. + var nestedIndex: UInt32 + var path: FilePathWithDate + + var sortIndex: UInt64 { + (UInt64(originalIndex) << 32) + UInt64(nestedIndex) + } + } + + /// The path of an email message file combined with its parsed `Date` header. + /// + /// This lets us sort input files based on their date. + struct FilePathWithDate: Hashable, Sendable, Comparable { + var filePath: FilePath + var date: Date + + static func < ( + lhs: FileBasedMessageToAppendSequence.FilePathWithDate, + rhs: FileBasedMessageToAppendSequence.FilePathWithDate + ) -> Bool { + lhs.date < rhs.date + } + } +} + +extension FileBasedMessageToAppendSequence { + /// Read an email message file, or all files inside a given directory. + /// + /// If `path` is a regular file, parse that file as a directory. If `path` is a directory, + /// parse the files inside it. + /// + /// We attempt to read `path` as a single message first; only if that fails do we fall back + /// to treating it as a directory. This skips an up-front `stat(2)` on the common case where + /// the argument is a regular email file — the read itself tells us whether `path` is a file + /// or directory, at the cost of a slightly less informative error when both interpretations + /// fail. + /// + /// - Parameters: + /// - originalIndex: Used for (later) sorting messages according to their + /// original input order. + static func readMessage( + path: FilePath, + originalIndex: Int + ) async -> [Result] { + do { + let result = try await readSingleMessage( + path: path, + originalIndex: originalIndex + ) + return [.success(result)] + } catch { + // Try to see if this is a directory: + guard let r = try? await readDirectory(directoryPath: path, originalIndex: originalIndex) else { + return [.failure(error)] + } + return r + } + } + + /// Returns an array with one entry for each file in the directory at the given path. + /// + /// Throws an error if the directory can not be scanned, for example because it does not exist. + static func readDirectory( + directoryPath: FilePath, + originalIndex: Int + ) async throws -> [Result] { + let paths = try allRegularFiles(in: directoryPath) + writeStatus("Did find \(paths.count) file(s) inside '\(directoryPath)'") + + var result: [Result] = [] + for (subIndex, path) in paths.enumerated() { + do { + var r = try await readSingleMessage( + path: path, + originalIndex: originalIndex + ) + r.nestedIndex = UInt32(subIndex) + result.append(.success(r)) + } catch { + result.append(.failure(error)) + } + } + return result + } + + /// Returns the paths of all regular files inside the directory. + /// + /// This does _not_ recurse into sub-directories. + static func allRegularFiles( + in directoryPath: FilePath, + ) throws -> [FilePath] { + var paths: [FilePath] = [] + + func add(dirent entry: UnsafePointer) { + let name = withRegularFileName(dirent: entry) { buffer -> FilePath.Component? in + // `FilePath.Component(platformString:)` requires a NUL-terminated buffer; + // `d_name` from `readdir` is not, so copy into a temp NUL-terminated buffer. + withUnsafeTemporaryAllocation( + of: CInterop.PlatformChar.self, + capacity: buffer.count + 1 + ) { temp in + for i in buffer.indices { + temp[i] = CInterop.PlatformChar(bitPattern: buffer[i]) + } + temp[buffer.count] = 0 + return temp.baseAddress.flatMap { FilePath.Component(platformString: $0) } + } + } + guard let name else { return } + paths.append(directoryPath.appending(name)) + } + + try scan( + directory: directoryPath, + closure: add(dirent:) + ) + + return paths + } + + static func readSingleMessage( + path: FilePath, + originalIndex: Int + ) async throws(UnableToParseFile) -> IndexedFilePath { + do { + // Read the first 100,000 bytes: + let data = try await Data( + asyncContentsOf: path, + length: 100_000 + ) + // Parse the date from it: + guard + let date = MessageHeaderParser.current.dateHeader(data) + else { + throw NoMessageDateInFile() + } + guard + let date = date.parse() + else { + throw UnableToParseDate(date: String(date)) + } + return IndexedFilePath( + originalIndex: UInt32(originalIndex), + nestedIndex: 0, + path: FilePathWithDate( + filePath: path, + date: date + ) + ) + } catch { + throw UnableToParseFile( + filePath: path, + underlying: error + ) + } + } +} + +extension FileBasedMessageToAppendSequence { + static func readAndSort( + paths: [FilePath], + options: Set + ) async throws -> [FilePathWithDate] { + try await withThrowingTaskGroup { group in + writeStatus("Reading and sorting \(paths.count) input path(s) by message date") + for (index, path) in paths.enumerated() { + group.addTask { + await readMessage( + path: path, + originalIndex: index + ) + } + } + + // Bin results by `originalIndex` so input order is preserved without sorting. + // Within each bin `nestedIndex` is in ascending order because `readDirectory` + // assigns it from `enumerated()`. + var bins: [[FilePathWithDate]] = Array(repeating: [], count: paths.count) + while true { + do { + guard + let nextBatch = try await group.next() + else { break } + for next in nextBatch { + switch next { + case .success(let s): + bins[Int(s.originalIndex)].append(s.path) + case .failure(let error): + writeErrorStatus(error: error) + guard options.contains(.skipErrors) else { throw error } + } + } + } catch { + writeStatus("error: \(error)") + guard options.contains(.skipErrors) else { throw error } + } + } + let inOrder = bins.flatMap { $0 } + guard options.contains(.sort) else { return inOrder } + return inOrder.sorted() + } + } +} + +extension FileBasedMessageToAppendSequence { + static func writeErrorStatus( + error: UnableToParseFile + ) { + switch error.underlying { + case is NoMessageDateInFile: + writeStatus("error: message is missing 'date' header ('\(error.filePath)')") + case let u as UnableToParseDate: + writeStatus( + "error: message 'date' header '\(u.date)' is not a valid RFC 5322 'date-time' ('\(error.filePath)')" + ) + default: + writeStatus("error: unable to parse file: \(error.underlying) ('\(error.filePath)')") + } + } + + struct NoMessageDateInFile: Swift.Error, Hashable {} + + struct UnableToParseDate: Swift.Error, Hashable { + var date: String + } + + struct UnableToParseFile: Swift.Error { + var filePath: FilePath + var underlying: any Swift.Error + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Authenticate.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Authenticate.swift new file mode 100644 index 00000000..04e47cae --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Authenticate.swift @@ -0,0 +1,221 @@ +//===----------------------------------------------------------------------===// +// +// 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 a successful IMAP authentication. +struct AuthenticationResult: Hashable, Sendable { + var responseText: String + var capabilities: [Capability] +} + +/// Which command to use to authenticate. +enum AuthenticationMethod: Hashable, Sendable { + /// Use `AUTHENTICATE` when the server advertises the credential’s SASL + /// mechanism, and fall back to `LOGIN` when it does not. + case automatic + /// Always try `LOGIN`, even when the server advertises the mechanism. Fails without + /// sending anything if the credential has no password, or if the server prohibits `LOGIN`. + case login +} + +extension IMAPConnection { + /// Authenticates the connection using the given credential. + func authenticate( + greeting: IMAPConnection.Greeting, + credential: IMAPCredential, + disableSASLIR: Bool, + method: AuthenticationMethod + ) async throws -> AuthenticationResult { + let preAuthCapabilities = try await capabilitiesFromCodeOrSendCommand( + text: try greeting.status.getOK() + ) + writeStatus("Pre-auth capabilities: \(preAuthCapabilities.map { String($0) }.sorted().joined(separator: " "))") + + // Authenticate. `AUTHENTICATE` requires the server to advertise the + // credential’s mechanism; `.login` overrides that and uses `LOGIN`. + let (mechanism, ir) = credential.makeAuthenticateCommand() + let useAuthenticate = + switch method { + case .automatic: preAuthCapabilities.contains(.authenticate(mechanism)) + case .login: false + } + + let authResult: TaggedResponse + if useAuthenticate { + authResult = try await authenticate( + saslMechanism: mechanism, + initialResponse: ir, + useSASL_IR: !disableSASLIR && preAuthCapabilities.contains(.saslIR) + ) + } else { + authResult = try await login( + credential: credential, + capabilities: preAuthCapabilities, + method: method + ) + } + + let text = try authResult.getOK() + writeStatus("Did authenticate: \(text.text)") + + let postAuthCapabilities = try await capabilitiesFromCodeOrSendCommand( + text: text + ) + writeStatus( + "Post-auth capabilities: \(postAuthCapabilities.map { String($0) }.sorted().joined(separator: " "))" + ) + + return AuthenticationResult( + responseText: text.text, + capabilities: postAuthCapabilities + ) + } + + private func capabilitiesFromCodeOrSendCommand( + text: ResponseText + ) async throws -> [Capability] { + if case .capability(let c) = text.code { + return c + } + // Get them from the server: + return try await getCapabilities() + } + + private func getCapabilities() async throws -> [Capability] { + try await send(.capability) { tag, responses in + var result: [Capability]? = nil + for try await r in responses { + switch r { + case .tagged(let r): + try r.checkOK() + case .untagged(.capabilityData(let c)): + result = c + default: + break + } + } + guard + let result + else { + throw AuthenticationError(message: "Server did not return Capabilities") + } + return result + } + } + + /// Sends `LOGIN`, or throws if either the credential or the server rules it out. + /// + /// The credential is checked first: when it can’t produce a `LOGIN` at all, saying so is + /// more useful than pointing at `LOGINDISABLED` for a command the user never asked for. + private func login( + credential: IMAPCredential, + capabilities: [Capability], + method: AuthenticationMethod + ) async throws -> TaggedResponse { + guard let loginCommand = credential.makeLoginCommand() else { + switch method { + case .login: + throw AuthenticationError( + message: "The given credential can only be used with AUTHENTICATE, not LOGIN." + ) + case .automatic: + throw AuthenticationError( + message: + "Server capabilities do not support the available credentials. Capabilities: \(capabilities.map { String($0) }.sorted().joined(separator: " "))" + ) + } + } + guard !capabilities.contains(.loginDisabled) else { + throw AuthenticationError( + message: "The server advertises LOGINDISABLED, which prohibits the LOGIN command." + ) + } + return try await send(loginCommand) { tag, responses in + writeStatus("Did send LOGIN command \(tag)") + return try await responses.waitForCompletion() + } + } + + private func authenticate( + saslMechanism mechanism: AuthenticationMechanism, + initialResponse ir: InitialResponse, + useSASL_IR supportsIR: Bool + ) async throws -> TaggedResponse { + try await sendAuthenticate( + mechanism: mechanism, + initialResponse: supportsIR ? ir : nil + ) { tag, responses, writer in + writeStatus( + "Did send AUTHENTICATE \(String(mechanism)) command \(tag) \(supportsIR ? "with" : "without") IR" + ) + return try await responses.forEach { response in + switch response { + case .authenticationChallenge: + guard !supportsIR else { + throw AuthenticationError(message: "Unexpected challenge.") + } + try await writer.writeContinuation(ir.data) + default: + return + } + } + } + } +} + +struct AuthenticationError: Equatable, Swift.Error { + var message: String +} + +// MARK: - + +extension ResponsePayload { + var capabilities: [Capability]? { + if case .conditionalState(.ok(let s)) = self, case .capability(let c)? = s.code { + return c + } else if case .capabilityData(let c) = self { + return c + } + return nil + } +} + +extension IMAPCredential { + func makeAuthenticateCommand() -> (AuthenticationMechanism, InitialResponse) { + let mechanism: AuthenticationMechanism + let data: Data + switch self { + case .username(let u, password: let p): + mechanism = .plain + data = Data([0]) + Data(u.utf8) + Data([0]) + Data(p.utf8) + case .sasl(mechanism: let m, response: let response): + mechanism = m + data = response + } + return (mechanism, InitialResponse(ByteBuffer(data))) + } + + func makeLoginCommand() -> Command? { + guard case .username(let u, password: let p) = self else { return nil } + return .login(username: u, password: p) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/BatchSize.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/BatchSize.swift new file mode 100644 index 00000000..d44e09fe --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/BatchSize.swift @@ -0,0 +1,83 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +/// Number of messages per batch when partitioning `FETCH` / `SEARCH` requests. +struct BatchSize: Hashable, Sendable { + /// Always positive. + let count: Int + + init?(_ count: Int) { + guard 0 < count else { return nil } + self.count = count + } +} + +extension BatchSize { + /// Floor for the batch size. + /// + /// When a server advertises a smaller `MESSAGELIMIT`, we still use this floor as + /// the batch size — the server's `MESSAGELIMIT` caps how many results may be + /// returned in a single response, not how many UIDs we may include in a request. + static let minimum: BatchSize = 1_000 + + /// `max(minimum, serverMessageLimit)`. + /// + /// Falls back to `minimum` if the server does not advertise `MESSAGELIMIT` (RFC 9738). + init(capabilities: [Capability]) { + guard + let value = capabilities.first(where: { $0.name == "MESSAGELIMIT" })?.value, + let parsed = UInt32(value), + let limit = Int(exactly: parsed).flatMap(BatchSize.init) + else { + self = .minimum + return + } + self = max(.minimum, limit) + } +} + +extension BatchSize { + /// Sequence numbers covered by the batch at `index`, for RFC 9394 `PARTIAL` ranges. + /// + /// Counted from the end of the mailbox (1 = newest). + /// E.g. for a size of 1,000: index 0 → `1...1000`, index 1 → `1001...2000`. + /// The end is clamped to `SequenceNumber.max`. + func partialRange(batch index: Int) -> ClosedRange { + let startOffset = Int64(index) * Int64(count) + let endOffset = Swift.min( + startOffset + Int64(count) - 1, + SequenceNumber.min.distance(to: .max) + ) + return SequenceNumber.min.advanced(by: startOffset)...SequenceNumber.min.advanced(by: endOffset) + } +} + +extension BatchSize: Comparable { + static func < (lhs: BatchSize, rhs: BatchSize) -> Bool { + lhs.count < rhs.count + } +} + +extension BatchSize: ExpressibleByIntegerLiteral { + init(integerLiteral value: Int) { + guard let size = BatchSize(value) else { preconditionFailure("BatchSize must be positive: \(value)") } + self = size + } +} + +extension BatchSize: CustomStringConvertible { + var description: String { "\(count)" } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/CreateMailbox.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/CreateMailbox.swift new file mode 100644 index 00000000..b5ec0dff --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/CreateMailbox.swift @@ -0,0 +1,98 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Creates the mailbox unless it already exists, then runs `LIST` and `STATUS` on it. + func createIfNeededAndList( + capabilities: [Capability], + mailbox: NewMailboxAction + ) async throws -> MailboxInfoAndStatus { + switch mailbox { + case .alreadyExists(let name): + return try await listAlreadyExisting( + capabilities: capabilities, + mailbox: name + ) + case .create(let name, let parameters): + return try await createAndList( + capabilities: capabilities, + mailbox: name, + parameters: parameters + ) + } + } + + /// Creates the mailbox and then runs `LIST` and `STATUS` on it. + func createAndList( + capabilities: [Capability], + mailbox: MailboxName, + parameters _parameters: [CreateParameter] + ) async throws -> MailboxInfoAndStatus { + let parameters: [CreateParameter] + if capabilities.contains(.createSpecialUse) { + parameters = _parameters + } else { + if !_parameters.isEmpty { + writeStatus("Server does not support CREATE-SPECIAL-USE") + } + parameters = [] + } + + let createText = try await send(.create(mailbox, parameters)) { tag, responses in + writeStatus("Did send CREATE mailbox '\(mailbox)' with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did CREATE mailbox '\(mailbox)': \(createText)") + + guard + let info = try await listMailbox( + capabilities: capabilities, + mailbox: mailbox + ) + else { throw NoListResponseAfterCreate(mailbox: mailbox) } + return info + } +} + +struct NoListResponseAfterCreate: Swift.Error { + var mailbox: MailboxName +} + +extension ConnectionProtocol { + private func listAlreadyExisting( + capabilities: [Capability], + mailbox: MailboxName, + ) async throws -> MailboxInfoAndStatus { + guard + let info = try await listMailbox( + capabilities: capabilities, + mailbox: mailbox + ) + else { throw NoListResponseForExistingMailbox(mailbox: mailbox) } + return info + } +} + +struct NoListResponseForExistingMailbox: Swift.Error { + var mailbox: MailboxName +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMailbox.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMailbox.swift new file mode 100644 index 00000000..f48c1db7 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMailbox.swift @@ -0,0 +1,36 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Deletes a mailbox from the server. + func deleteMailbox( + capabilities _: [Capability], + mailbox: MailboxName + ) async throws { + let text = try await send(.delete(mailbox)) { tag, responses in + writeStatus("Did send DELETE mailbox '\(mailbox)' with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did DELETE mailbox '\(mailbox)': \(text)") + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMessages.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMessages.swift new file mode 100644 index 00000000..af555c92 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DeleteMessages.swift @@ -0,0 +1,65 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Marks the specified messages as deleted and expunges them. + func deleteMessages( + uids: UIDSet + ) async throws { + guard !uids.isEmpty else { return } + guard + let command = Command.uidStore( + messages: uids, + modifiers: [], + data: StoreData.flags(StoreFlags.add(silent: true, list: [.deleted])) + ) + else { return } + try await send(command) { tag, responses in + return try await responses.waitForCompletion() + }.checkOK() + writeStatus("Did mark \(uids.count) UIDs as \\Deleted") + try await send(.expunge) { tag, responses in + return try await responses.waitForCompletion() + }.checkOK() + writeStatus("Did EXPUNGE") + } + + /// Marks all messages in the selected mailbox as deleted and expunges them. + func deleteAllMessages() async throws { + guard + let command = Command.uidStore( + messages: .all, + modifiers: [], + data: StoreData.flags(StoreFlags.add(silent: true, list: [.deleted])) + ) + else { return } + try await send(command) { tag, responses in + return try await responses.waitForCompletion() + }.checkOK() + writeStatus("Did mark as \\Deleted") + try await send(.expunge) { tag, responses in + return try await responses.waitForCompletion() + }.checkOK() + writeStatus("Did EXPUNGE") + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Download.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Download.swift new file mode 100644 index 00000000..4b02c8e9 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Download.swift @@ -0,0 +1,301 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import SystemPackage + +extension ConnectionProtocol { + /// Downloads messages specified by `query` into the directory at `root`. + /// + /// - Parameters: + /// - deleteUnknown: Whether to delete local message files that no longer exist on the server. + /// - Returns: All UIDs in the directory, including previously downloaded UIDs. + func download( + mailboxMessageCount: Int, + capabilities: [Capability], + uidValidity: UIDValidity, + query: FetchQuery, + into root: FilePath, + deleteUnknown: Bool + ) async throws -> UIDSet { + // Get all UIDs on the server: + let uids = try await allUIDs( + query: query, + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities + ) + writeStatus("Did find \(uids.count) UID(s) in mailbox") + + var directory = try DownloadDirectory.openDeletingInvalidFiles( + directory: root, + uidValidity: uidValidity, + deleteUnknown: deleteUnknown + ) + + // Delete local files no longer on the server: + if deleteUnknown { + directory.unlinkFiles(notIncludedIn: uids) + } + + try await download( + uids: uids, + into: &directory + ) + + return directory.downloadedUIDs + } + + /// Downloads a batch of UIDs with a concurrency limit. + func download( + uids allUIDs: UIDSet, + concurrencyLimit: Int = 11, + into _directory: inout DownloadDirectory, + ) async throws { + let directory = DownloadDirectory.Helper( + connection: self, + directory: _directory + ) + + // Loop over all UIDs and download them. + try await withThrowingTaskGroup( + of: Void.self, + returning: Void.self + ) { group in + let previouslyDownloadedUIDs = await directory.directory.downloadedUIDs + var remainingUIDs = allUIDs.subtracting(previouslyDownloadedUIDs) + if remainingUIDs.count != allUIDs.count { + writeStatus( + "Downloading \(remainingUIDs.count) remaining message(s) out of \(allUIDs.count) total message(s) — \(previouslyDownloadedUIDs.count) already downloaded" + ) + } else { + writeStatus("Downloading \(remainingUIDs.count) message(s)") + } + + func popNextUID() -> UID? { + guard + let uid = remainingUIDs.last + else { return nil } + remainingUIDs.remove(uid) + return uid + } + + func addTask() { + guard let uid = popNextUID() else { return } + group.addTask { + try await directory.download(uid: uid) + } + } + + for _ in 0.. { + let connection: C + var directory: DownloadDirectory + + init( + connection: C, + directory: DownloadDirectory + ) { + self.connection = connection + self.directory = directory + } + + func makeWriter( + uid: UID + ) throws -> DownloadDirectory.Writer { + try directory.makeWriter(uid: uid) + } + + func didDownload(uid: UID) { + directory.didDownload(uid: uid) + } + } +} + +extension DownloadDirectory.Helper { + func download(uid: UID) async throws { + let section = SectionSpecifier(part: [], kind: .complete) + let command = Command.uidFetch( + .set(UIDSetNonEmpty(range: uid...uid)), + [.uid, .bodySection(peek: true, section, nil)], + [] + ) + + let writer = try makeWriter(uid: uid) + let byteCount = try await connection.send(command) { tag, responses -> Int? in + writeStatus("Did send \(tag) UID FETCH \(uid) for complete message") + + var state = FetchState.waiting + + for try await response in responses { + let action = state.update( + uid: uid, + section: section, + response: response + ) + switch action { + case .none: + break + case .writeData(let data): + writer.write(data) + case .closeAndFail: + writer.closeAndFail() + case .closeAndSucceed: + writer.closeAndSucceed() + } + } + + // Wait for the writer to have completed. + await writer.waitForCompletion() + return state.byteCount + } + + guard + let byteCount + else { + writeStatus("Did not receive any data for UID \(uid) — message might have been deleted") + return + } + writeStatus("Did write \(byteCount) bytes for UID \(uid)") + directory.didDownload(uid: uid) + } +} + +/// Keeps track of where we are wrt. receiving `FetchResponse` for a particular message. +/// +/// State transitions, driven by `update(uid:section:response:)`: +/// +/// ``` +/// .fetch(.start) +/// waiting ─────────────────────────────────► didStart +/// +/// .simpleAttribute(.uid(matching)) +/// didStart ───────────────────────────────────────────► didMatchUID +/// +/// .streamingBegin(.body(section, nil)) +/// didMatchUID ──────────────────────────────────────────► didBeginStream +/// +/// .streamingBytes (→ writeData) +/// didBeginStream ◄─────self loop────────── +/// │ +/// │ .streamingEnd +/// └──────────────────────► didEndStream +/// +/// .finish (→ closeAndSucceed) +/// didEndStream ─────────────────────────► done +/// │ +/// │ anything else (→ closeAndFail) +/// └──────────────────────► failed +/// ``` +/// +/// Any unmatched `(state, response)` pair returns `.none` and leaves the state +/// untouched — the iterator simply waits for the next response. +private enum FetchState: Equatable, Sendable { + case waiting + case didStart + case didMatchUID + case didBeginStream(byteCount: Int) + case didEndStream(byteCount: Int) + case done(byteCount: Int) + case failed +} + +extension FetchState { + /// If writing completed (successfully), return the written byte count. + var byteCount: Int? { + guard + case .done(let c) = self + else { return nil } + return c + } + + enum UpdateAction: Sendable { + case none + case writeData(ByteBuffer) + case closeAndFail + case closeAndSucceed + } + + mutating func update( + uid: UID, + section: SectionSpecifier, + response: Response + ) -> UpdateAction { + guard case .fetch(let fetch) = response else { return .none } + switch (self, fetch) { + case (.waiting, .start): + self = .didStart + return .none + case (.didStart, .simpleAttribute(.uid(uid))): + self = .didMatchUID + return .none + case ( + .didMatchUID, + .streamingBegin(kind: StreamingKind.body(section: section, offset: nil), byteCount: let byteCount) + ): + self = .didBeginStream(byteCount: byteCount) + return .none + case (.didBeginStream, .streamingBytes(let bytes)): + return .writeData(bytes) + case (.didBeginStream(byteCount: let byteCount), .streamingEnd): + self = .didEndStream(byteCount: byteCount) + return .none + case (.didEndStream(byteCount: let byteCount), .finish): + self = .done(byteCount: byteCount) + return .closeAndSucceed + case (.didEndStream, _): + self = .failed + return .closeAndFail + default: + return .none + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DownloadDirectory.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DownloadDirectory.swift new file mode 100644 index 00000000..a3a5aadc --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/DownloadDirectory.swift @@ -0,0 +1,438 @@ +//===----------------------------------------------------------------------===// +// +// 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 SystemPackage +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif +import NIOCore +import NIOFileSystem +import NIOIMAP + +/// Tracks which message files exist in a download directory and determines file names for new downloads. +struct DownloadDirectory: Sendable { + let root: FilePath + let uidValidity: UIDValidity + private(set) var downloadedUIDs: UIDSet + private var tempFilePrefix = Int.random(in: 1_000...9_999) +} + +extension DownloadDirectory { + /// Opens the directory, deleting temporary files and files with a different UID validity. + /// + /// - Parameter directory: The path to an existing directory for downloading messages. + /// - Parameter uidValidity: The current UID validity of the mailbox on the server. + static func openDeletingInvalidFiles( + directory root: FilePath, + uidValidity: UIDValidity, + deleteUnknown: Bool + ) throws -> DownloadDirectory { + var dir = DownloadDirectory( + root: root, + uidValidity: uidValidity, + downloadedUIDs: UIDSet() + ) + try Self.withFilenames(in: root) { filename in + switch filename { + case .message(let uid, uidValidity): + dir.downloadedUIDs.insert(uid) + case .message(let uid, let other): + guard deleteUnknown else { break } + writeStatus("Deleting message with wrong UID validity \(other), UID \(uid)") + dir.unlink(file: filename) + case .temporary: + guard deleteUnknown else { break } + writeStatus("Deleting temporary message") + dir.unlink(file: filename) + } + } + if dir.downloadedUIDs.isEmpty { + writeStatus("Did find no previously downloaded messages") + } else { + writeStatus("Did find \(dir.downloadedUIDs.count) previously downloaded message(s)") + } + return dir + } +} + +// MARK: - + +extension DownloadDirectory { + /// Delete the given file in the directory. + func unlink(file: Filename) { + do { + try root.appending(file).unlink() + } catch { + writeStatus("error: failed to delete '\(String(decoding: FilePath.Component(file)))' (\(error))") + } + } + + mutating func unlinkFiles(notIncludedIn uids: UIDSet) { + let toDelete = downloadedUIDs.subtracting(uids) + guard !toDelete.isEmpty else { return } + writeStatus("Deleting \(toDelete.count) downloaded message(s) that no longer exist on the server") + for uid in toDelete { + unlink(file: .message(uid, uidValidity)) + } + downloadedUIDs.subtract(toDelete) + } +} + +extension FilePath { + func appending(_ filename: DownloadDirectory.Filename) -> FilePath { + appending(FilePath.Component(filename)) + } + + func unlink() throws { + try withPlatformString { path in + // Qualified because an unqualified `unlink` would resolve to this method. + #if canImport(Glibc) + let result = Glibc.unlink(path) + #elseif canImport(Darwin) + let result = Darwin.unlink(path) + #endif + guard + result == 0 + else { + let error = Errno(rawValue: errno) + throw error + } + } + } +} + +// MARK: - + +extension DownloadDirectory { + /// Writes a downloaded message to a temporary file, then moves it into place. + /// + /// Writing to `NIOFileSystem` is `async`, but callers hand over chunks synchronously as + /// they arrive off the connection. The chunks therefore go into a stream that a + /// detached task drains, and the file is opened, written, closed, and renamed entirely + /// inside that task. `waitForCompletion()` awaits it. + struct Writer: ~Copyable { + let uid: UID + private let continuation: AsyncStream.Continuation + private let task: Task + + /// A unit of work handed to the writing task. + fileprivate enum Chunk: Sendable { + case write(ByteBuffer) + /// Stop writing and discard the file. + case fail + } + + init( + uid: UID, + path: FilePath, + finalPath: FilePath + ) throws { + self.uid = uid + guard + let finalFilename = finalPath.lastComponent + else { throw InvalidFilePath(path: finalPath) } + let name = String(decoding: finalFilename) + + let (stream, continuation) = AsyncStream.makeStream(of: Chunk.self) + self.continuation = continuation + self.task = Task { + await Writer.run( + stream: stream, + path: path, + finalPath: finalPath, + name: name + ) + } + } + + /// Consumes `stream`, writing each chunk to the file at `path`. + /// + /// The file is renamed to `finalPath` only if the stream completes without a + /// `.fail` chunk and every write succeeds. + private static func run( + stream: AsyncStream, + path: FilePath, + finalPath: FilePath, + name: String + ) async { + do { + let didSucceed = try await FileSystem.shared.withFileHandle( + forWritingAt: path, + options: .newFile(replaceExisting: true) + ) { handle -> Bool in + var offset: Int64 = 0 + for await chunk in stream { + switch chunk { + case .write(let buffer): + offset += try await handle.write( + contentsOf: buffer.readableBytesView, + toAbsoluteOffset: offset + ) + case .fail: + return false + } + } + return true + } + guard didSucceed else { + await Writer.removeTemporaryFile(at: path) + return + } + try await FileSystem.shared.moveItem(at: path, to: finalPath) + } catch { + writeStatus("error: failed to write file '\(name)' (\(error))") + await Writer.removeTemporaryFile(at: path) + } + } + + /// Removes the partially written file, ignoring the case where it was never created. + private static func removeTemporaryFile(at path: FilePath) async { + do { + _ = try await FileSystem.shared.removeItem(at: path) + } catch { + writeStatus("error: failed to remove temporary file '\(path)' (\(error))") + } + } + + func write(_ buffer: ByteBuffer) { + continuation.yield(.write(buffer)) + } + + func closeAndFail() { + continuation.yield(.fail) + continuation.finish() + } + + func closeAndSucceed() { + continuation.finish() + } + + func close() { + continuation.finish() + } + + /// Waits for the file to be written, closed, and moved into place. + func waitForCompletion() async { + // Finishing is a no-op if the stream is already finished, but it makes sure + // the writing task can run to completion rather than waiting for more chunks. + continuation.finish() + await task.value + } + + deinit { + continuation.finish() + } + } + + /// Creates a `Writer` to write data for the given message. + func makeWriter( + uid: UID + ) throws -> Writer { + try Writer( + uid: uid, + path: root.appending(.temporary("\(tempFilePrefix).\(uid)")), + finalPath: root.appending(.message(uid, uidValidity)) + ) + } + + mutating func didDownload(uid: UID) { + downloadedUIDs.insert(uid) + } +} + +private struct InvalidFilePath: Swift.Error { + var path: String + init(path: FilePath) { + self.path = String(decoding: path) + } +} + +// MARK: - Enumerating (Existing) Files + +extension DownloadDirectory { + static func withFilenames( + in directory: FilePath, + closure: (Filename) -> Void + ) throws { + try scan(directory: directory) { entry in + guard let f = Filename(dirent: entry) else { return } + closure(f) + } + } +} + +extension FilePath.Component { + init(_ other: DownloadDirectory.Filename) { + switch other { + case .message(let uid, let validity): + // UIDVALIDITY is encoded as hex padded to an even number of digits. + // The parser (`scanUIDValidity`) consumes the hex two digits at a time, + // so writer and reader must agree on this padding. + let b = String(UInt32(validity), radix: 16) + self.init("\(UInt32(uid)).\(((b.count % 2) == 0) ? "" : "0")\(b).message")! + case .temporary(let id): + self.init(".\(id).message")! + } + } +} + +extension DownloadDirectory.Filename { + init?(dirent entry: UnsafePointer) { + guard + let parsed = withRegularFileName( + dirent: entry, + { buffer in + DownloadDirectory.Filename(regularFilename: buffer) + } + ) + else { return nil } + self = parsed + } + + init?( + regularFilename filename: Span + ) { + // Filenames are short, so copying out of the span costs nothing and lets + // the scanning below stay in ordinary, consuming `Collection` code — + // `Span` is non-escapable and so cannot have `mutating` methods. + var remainder = filename.withUnsafeBufferPointer { Array($0) }[...] + if remainder.popDot() { + guard + remainder.dropMessageSuffix(), + let s = String(validating: remainder, as: UTF8.self) + else { return nil } + self = .temporary(s) + } else { + guard + remainder.dropMessageSuffix(), + let uid = remainder.scanUID(), + remainder.popDot(), + let validity = remainder.scanUIDValidity(), + remainder.isEmpty + else { return nil } + self = .message(uid, validity) + } + } +} + +// MARK: - File Names + +extension DownloadDirectory { + enum Filename: Hashable, Sendable { + case message(UID, UIDValidity) + case temporary(String) + } +} + +private let fileExtension: StaticString = ".message" + +extension ArraySlice { + /// If the buffer has a ".message" suffix remove it and return `true`, + /// return `false` otherwise. + fileprivate mutating func dropMessageSuffix() -> Bool { + guard + fileExtension.utf8CodeUnitCount < self.count + else { return false } + // Check for ".message" file extension + let start = self.index(self.endIndex, offsetBy: -fileExtension.utf8CodeUnitCount) + guard + fileExtension.withUTF8Buffer({ self[start...].elementsEqual($0) }) + else { return false } + + self = self[.. UID? { + guard + var result = popNumber().map({ UInt32($0) }) + else { return nil } + while true { + guard + let next = popNumber() + else { return UID(exactly: result) } + // Widen to `UInt64` _before_ multiplying so an overflowing filename + // (e.g. `9999999999.0001.message`) makes the guard below skip the + // file rather than trapping on `UInt32` overflow. + let a = UInt64(result) * 10 + UInt64(next) + guard + let b = UInt32(exactly: a) + else { return nil } + result = b + } + } + + fileprivate mutating func scanUIDValidity() -> UIDValidity? { + guard + var result = popDoubleHex().map({ UInt32($0) }) + else { return nil } + while true { + guard + let next = popDoubleHex() + else { return UIDValidity(exactly: result) } + // Widen to `UInt64` _before_ multiplying so an overflowing validity + // segment makes the guard below skip the file rather than trapping. + let a = UInt64(result) * 256 + UInt64(next) + guard + let b = UInt32(exactly: a) + else { return nil } + result = b + } + } + + fileprivate mutating func popDot() -> Bool { + guard first == UTF8.CodeUnit(ascii: ".") else { return false } + self = dropFirst() + return true + } + + fileprivate mutating func popNumber() -> UInt8? { + guard + let f = first, + UTF8.CodeUnit(ascii: "0") <= f, + f <= UTF8.CodeUnit(ascii: "9") + else { return nil } + self = dropFirst() + return f - UTF8.CodeUnit(ascii: "0") + } + + fileprivate mutating func popDoubleHex() -> UInt8? { + guard + 2 <= count + else { return nil } + guard + let a = self[self.startIndex].hexValue, + let b = self[self.index(after: self.startIndex)].hexValue + else { return nil } + self = dropFirst(2) + return a << 4 + b + } +} + +extension UTF8.CodeUnit { + fileprivate var hexValue: UInt8? { + switch self { + case UTF8.CodeUnit(ascii: "0")...UTF8.CodeUnit(ascii: "9"): + self - UTF8.CodeUnit(ascii: "0") + case UTF8.CodeUnit(ascii: "a")...UTF8.CodeUnit(ascii: "f"): + self - UTF8.CodeUnit(ascii: "a") + 10 + case UTF8.CodeUnit(ascii: "A")...UTF8.CodeUnit(ascii: "F"): + self - UTF8.CodeUnit(ascii: "A") + 10 + default: + nil + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ExistingMailboxHierarchy.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ExistingMailboxHierarchy.swift new file mode 100644 index 00000000..07300a5c --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ExistingMailboxHierarchy.swift @@ -0,0 +1,199 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +/// Represents the existing mailbox hierarchy on the server. +struct ExistingMailboxHierarchy: Sendable { + var paths: [Path] + + struct Path: Sendable { + var mailboxPath: MailboxPath + var displayStringComponents: [String] + } +} + +/// A mailbox display name with its associated special-use parameters. +struct MailboxDisplayNameWithSpecialUse: Hashable, Sendable { + /// The path components of the mailbox display name. + var namePath: [String] + /// The `CREATE` parameters including special-use attributes. + var parameters: [CreateParameter] + + /// Creates a display name with the given path and parameters. + init( + namePath: [String], + parameters: [CreateParameter] + ) { + self.namePath = namePath + self.parameters = parameters + } +} + +/// Describes whether a mailbox already exists or needs creation. +enum NewMailboxAction: Hashable, Sendable { + /// The mailbox already exists with the given name. + case alreadyExists(MailboxName) + /// The mailbox needs creation with the given name and parameters. + case create(MailboxName, [CreateParameter]) +} + +extension ExistingMailboxHierarchy { + /// Returns the mailbox actions needed to create the given display paths. + /// + /// The returned array orders parent mailboxes before their nested children. + func makeMailboxNamesForCreation( + _ displayNames: [MailboxDisplayNameWithSpecialUse] + ) throws -> [NewMailboxAction] { + var existing = self + let sortedNames = + displayNames + .sorted(by: { + // We sort primarily so that shorter paths come before longer ones; this + // guarantees parents are created before their children. For two paths of + // equal length we still need a deterministic tiebreaker (so tests are + // stable), but we can't sort by lexicographic `String` order — IMAP + // mailbox names are byte sequences (RFC 3501 §5.1) and a Unicode-aware + // compare can re-order names that differ only in normalization. XOR of + // `hashValue`s gives a tiebreaker that doesn't pretend names are strings. + let lhs = $0.namePath.count + let rhs = $1.namePath.count + if lhs < rhs { + return true + } else if rhs < lhs { + return false + } + return $0.namePath.reduce(into: 0, { $0 = $0 ^ $1.hashValue }) + < $1.namePath.reduce(into: 0, { $0 = $0 ^ $1.hashValue }) + }) + return try sortedNames.map { name in + let path = try existing.makeMailboxPath(displayStrings: name.namePath) + guard + !existing.paths.contains(where: { $0.mailboxPath.name == path.name }) + else { return .alreadyExists(path.name) } + existing.insert(mailboxPath: path) + return .create(path.name, name.parameters) + } + } +} + +// MARK: - + +extension ExistingMailboxHierarchy { + /// Creates a new hierarchy from the given mailbox paths. + init( + mailboxPaths: some Sequence + ) { + self.paths = [] + for p in mailboxPaths { + insert(mailboxPath: p) + } + } + + mutating func insert( + mailboxPath new: MailboxPath + ) { + guard + !paths.contains(where: { $0.mailboxPath.name == new.name }) + else { return } + paths.append( + Path( + mailboxPath: new, + displayStringComponents: new.displayStringComponents(omittingEmptySubsequences: false) + ) + ) + } + + var inbox: Path? { + paths.first(where: { $0.mailboxPath.name.isInbox }) + } + + func bestParent( + displayStrings _displayStrings: [String] + ) -> Path? { + let displayStrings = + _displayStrings + .map { $0.precomposedStringWithCanonicalMapping } + guard + !displayStrings.isEmpty + else { return nil } + guard + 2 <= displayStrings.count + else { + return nil + } + return + paths + .filter { path in + guard + path.displayStringComponents.count < displayStrings.count + else { return false } + return Array(displayStrings.prefix(path.displayStringComponents.count)) == path.displayStringComponents + } + .sorted(by: { $0.displayStringComponents.count > $1.displayStringComponents.count }) + .first + } + + /// Constructs a `MailboxPath` from the given display-name path components. + func makeMailboxPath( + displayStrings _displayStrings: [String] + ) throws -> MailboxPath { + let displayStrings = + _displayStrings + .map { $0.precomposedStringWithCanonicalMapping } + guard + let firstName = displayStrings.first + else { throw Error.emptyMailboxPath } + guard + 1 < displayStrings.count + else { + return try MailboxPath.makeRootMailbox( + displayName: firstName, + pathSeparator: self.inbox?.mailboxPath.pathSeparator + ) + } + + guard + let parent = bestParent( + displayStrings: displayStrings + ) + else { + guard + let pathSeparator = self.inbox?.mailboxPath.pathSeparator + else { throw Error.noExistingInbox } + + var result = try MailboxPath.makeRootMailbox( + displayName: firstName, + pathSeparator: pathSeparator + ) + for name in displayStrings.suffix(from: 1) { + result = try result.makeSubMailbox(displayName: name) + } + return result + } + + var result = parent.mailboxPath + for name in displayStrings.suffix(from: parent.displayStringComponents.count) { + result = try result.makeSubMailbox(displayName: name) + } + return result + } +} + +extension ExistingMailboxHierarchy { + enum Error: Swift.Error { + case emptyMailboxPath + case noExistingInbox + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Fetch.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Fetch.swift new file mode 100644 index 00000000..53b8a543 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Fetch.swift @@ -0,0 +1,251 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +// MARK: - Message Info + +extension ConnectionProtocol { + /// Get ``MessageInfo`` for all messages specified by `query`. + func fetchMessageInfo( + mailboxMessageCount: Int, + capabilities: [Capability], + query: FetchQuery + ) async throws -> [MessageInfo] { + // Store into a dictionary to make sure the values + // are unique per UID -- in case the server returns multiple + // replies (commands running in parallel). + let all: [UID: MessageInfo] + all = try await batchedFetchSimpleAttributes( + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities, + query: query, + attributes: [.uid, .flags, .envelope], + into: [:], + update: { result, batchResult in + for (uid, attr) in batchResult { + guard + let info = MessageInfo( + uid: uid, + attributes: attr + ) + else { continue } + result[info.uid] = info + } + } + ) + return all + .values + .sorted(by: { $0.uid < $1.uid }) + } + + /// Fetches the given `attributes` for messages specified by `query`, in batches. + /// + /// The `update` closure merges one batch's results into `result`. + /// + /// - Parameters: + /// - mailboxMessageCount: The number of messages in the mailbox. + /// - capabilities: The server capabilities. + func batchedFetchSimpleAttributes( + mailboxMessageCount: Int, + capabilities: [Capability], + query: FetchQuery, + attributes: [FetchAttribute], + into result: Result, + update: @Sendable (inout Result, [UID: [MessageAttribute]]) throws -> Void + ) async throws -> Result { + return try await batched( + query: query, + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities, + fetch: { batch in + let r: [UID: [MessageAttribute]] = try await self.fetchSimpleAttributes( + capabilities: capabilities, + uids: batch.makeUIDs(query), + attributes: attributes, + modifiers: batch.fetchModifiers, + into: [:] + ) { all, uid, _, attributes in + all[uid] = attributes + } + return r + }, + into: result, + update: update + ) + } +} + +// MARK: - Simple Attributes + +extension ConnectionProtocol { + /// Sends a `UID FETCH` command for non-streaming message attributes. + /// + /// The `update` closure runs for each `* FETCH` response received. + /// Due to command pipelining, responses for other commands may also arrive. + func fetchSimpleAttributes( + capabilities: [Capability], + uids: UIDSet, + attributes _attributes: [FetchAttribute], + modifiers: [FetchModifier], + into result: Result, + update: @Sendable (inout Result, UID, SequenceNumber?, [MessageAttribute]) throws -> Void + ) async throws -> Result { + guard + _attributes.allSatisfy({ $0.isSimpleAttribute }) + else { + throw FetchAttributeIsNotSimpleAttribute( + attributes: _attributes.filter { !$0.isSimpleAttribute } + ) + } + + // Make sure we’re requesting the UID: + let attributes: [FetchAttribute] = (_attributes.contains(.uid) ? _attributes : [.uid] + _attributes) + + return try await fetch( + capabilities: capabilities, + uids: uids, + attributes: attributes, + modifiers: modifiers, + into: ResultWithState( + state: .noMessage, + result: result + ) + ) { result, response in + switch (result.state, response) { + case (.noMessage, .start(let seq)): + result.state = .message(seq, []) + case (.noMessage, .startUID(let uid)): + result.state = .message(nil, [.uid(uid)]) + case (_, .start), (_, .startUID): + break + case (.message(let seq, var attributes), .simpleAttribute(let new)): + attributes.append(new) + result.state = .message(seq, attributes) + case (.noMessage, .simpleAttribute): + break + case (_, .streamingBegin), (_, .streamingBytes), (_, .streamingEnd): + break + case (.noMessage, .finish): + break + case (.message(let seq, let attributes), .finish): + defer { + result.state = .noMessage + } + let uid: UID? = attributes + .lazy + .compactMap { + guard case .uid(let uid) = $0 else { return nil } + return uid + } + .first + guard + let uid, + uids.contains(uid) + else { break } + try update(&result.result, uid, seq, attributes) + } + }.result + } +} + +private struct ResultWithState: Sendable { + var state: State + var result: Result + + enum State: Sendable { + case noMessage + case message(SequenceNumber?, [MessageAttribute]) + } +} + +// MARK: Returns Data + +struct FetchAttributeIsNotSimpleAttribute: Swift.Error { + var attributes: [FetchAttribute] +} + +extension FetchAttribute { + var isSimpleAttribute: Bool { + switch self { + case .binarySize, + .bodyStructure, + .emailID, + .envelope, + .flags, + .gmailLabels, + .gmailMessageID, + .gmailThreadID, + .internalDate, + .modificationSequence, + .modificationSequenceValue, + .preview, + .rfc822Size, + .threadID, + .uid: + true + case .binary, + .bodySection, + .rfc822, + .rfc822Header, + .rfc822Text: + false + } + } +} + +// MARK: - Generic + +extension ConnectionProtocol { + /// Sends a `UID FETCH` command. + /// + /// The `update` closure runs for each ``FetchResponse`` received. + /// Due to command pipelining, responses for other commands may also arrive. + func fetch( + capabilities: [Capability], + uids _uids: UIDSet, + attributes: [FetchAttribute], + modifiers: [FetchModifier], + into _result: Result, + update: @Sendable (inout Result, FetchResponse) throws -> Void + ) async throws -> Result { + guard + let uids = UIDSetNonEmpty(set: _uids) + else { return _result } + + let command = Command.uidFetch( + .set(uids), + attributes, + modifiers + ) + return try await send(command) { tag, responses -> Result in + writeStatus("Did send \(tag) \(command)") + var result = _result + for try await response in responses { + guard + case .fetch(let fetch) = response + else { continue } + try update(&result, fetch) + } + return result + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Fixed.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Fixed.swift new file mode 100644 index 00000000..33ff16e8 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Fixed.swift @@ -0,0 +1,38 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +// MARK: - Fixed `[UIDRange]` strategy +// +// Used when the caller passes `FetchQuery.uids(_)` to `makeBatches(...)` on a server +// without RFC 9394 `PARTIAL` support. The requested UIDs are split into ranges of +// at most `batchSize` UIDs each, preserving the UID ordering. + +/// Splits the given UIDs into `UIDRange`s with at most `batchSize` UIDs each. +func splitUIDsIntoRanges( + uids: UIDSet, + batchSize: BatchSize +) -> [UIDRange] { + var ranges: [UIDRange] = [] + var remaining = uids + while !remaining.isEmpty { + guard + let next = UIDSetNonEmpty(set: remaining.suffix(batchSize.count)) + else { break } + ranges.append(next.min()...next.max()) + remaining.subtract(UIDSet(next.min()...UID.max)) + } + return ranges +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+FromBoundaries.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+FromBoundaries.swift new file mode 100644 index 00000000..8ca5a9c4 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+FromBoundaries.swift @@ -0,0 +1,190 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +// MARK: - `UIDBatchFromBoundaries` strategy +// +// Used on servers without RFC 9394 `PARTIAL` support for `.all` and `.last(n)` +// queries. Because UIDs are not contiguous, we first issue a `SEARCH` on sequence +// numbers at batch boundaries (e.g. every 1,000th message) to learn the actual +// boundary UIDs, then emit one `.uidRange(low...high)` batch per gap. +// +// Striding is anchored at the *max* sequence number so the newest batch is full — +// callers may use that property to restrict follow-up tasks to the latest batch. + +extension ConnectionProtocol { + /// Returns batches by first asking the server for boundary UIDs. + /// + /// Used for `.all` / `.last(n)` queries on servers without RFC 9394 `PARTIAL`. + func makeBoundaryFetchBatch( + query: FetchQuery, + mailboxMessageCount: Int, + batchSize: BatchSize, + capabilities: [Capability], + ) async throws -> FetchBatches { + func make(count: Int) async throws -> FetchBatches { + guard + batchSize.count / 2 < count + else { + writeStatus("Requesting list of latest \(count) UIDs from server") + // Run a search to get the UIDs: + let uids = try await search( + capabilities: capabilities, + key: .lastMessages( + count: count, + mailboxMessageCount: mailboxMessageCount + ) + ) + guard + let a = uids.min(), + let b = uids.max() + else { + writeStatus("No UIDs — mailbox is empty?") + return .empty + } + return .singleBatch(a...b) + } + // Split up into batches. + guard + let boundarySequenceNumbers = sequenceNumbersForMessageBatches( + mailboxMessageCount: mailboxMessageCount, + maximumCount: count, + batchSize: batchSize + ) + else { + writeStatus("No UIDs — mailbox is empty?") + return .empty + } + writeStatus("Searching for message batches UID boundaries") + let boundaryUIDs = try await search( + capabilities: capabilities, + key: .sequenceNumbers(.set(boundarySequenceNumbers)) + ) + writeStatus("Message batch UID boundaries (for \(count) messages): \(boundaryUIDs)") + return .fromBoundaries(UIDBatchFromBoundaries(boundaries: boundaryUIDs)) + } + + switch query { + case .last(count: let count): + // Honor `count` even on a small mailbox: fetching the whole mailbox to satisfy + // a `.last(n)` request would over-fetch. `make(count:)` issues a bounded SEARCH + // for (at most) the last `count` messages. + return try await make(count: min(count, mailboxMessageCount)) + case .all: + // The whole mailbox is wanted. If it is small enough, fetch it in a single batch + // without a boundary SEARCH. + guard + batchSize.count / 2 < mailboxMessageCount + else { + writeStatus("Mailbox has very few messages — using a single batch") + return .fixed([UID.min...UID.max]) + } + return try await make(count: mailboxMessageCount) + case .uids(let uids): + let ranges = splitUIDsIntoRanges( + uids: uids, + batchSize: batchSize + ) + writeStatus("Did split FETCH for \(uids.count) UIDs into \(ranges.count) batch(es) / range(s)") + return .fixed(ranges) + } + } +} + +/// Calculate the sequence numbers that should be queried for UIDs, based on the message count. +/// - Parameters: +/// - mailboxMessageCount: The total number of messages in the mailbox. +/// - maximumCount: The number of messages of interest, that is, the number of messages that +/// the returned UIDs should span. +/// - batchSize: The number of messages in each batch. +func sequenceNumbersForMessageBatches( + mailboxMessageCount: Int, + maximumCount: Int?, + batchSize: BatchSize +) -> MessageIdentifierSetNonEmpty? { + let min: SequenceNumber + if let maximumCount, let m = SequenceNumber(exactly: mailboxMessageCount - maximumCount + 1) { + min = m + } else { + min = SequenceNumber.min + } + guard + let max = SequenceNumber(exactly: mailboxMessageCount) + else { return nil } + + // We stride starting from max. That way the last (newest) batch + // will be (close to) the desired batch size, and we can then + // subsequently use that when we want to limit tasks to only operate + // on messages in that last batch. + var next: SequenceNumber? = max + let step = Int64(batchSize.count) + let boundaries = AnyIterator { + defer { + if let n = next, step <= min.distance(to: n) { + next = n.advanced(by: -step) + } else { + next = nil + } + } + return next + } + var result = SequenceSet(boundaries) + result.insert(min) + return MessageIdentifierSetNonEmpty(set: result) +} + +/// A sequence of `FetchBatch` based on boundary UIDs. +/// +/// The boundary UIDs should be the result of `sequenceNumbersForMessageBatches()`. +struct UIDBatchFromBoundaries: Hashable, Sendable { + let boundaries: UIDSet +} + +extension UIDBatchFromBoundaries: Sequence { + typealias Element = FetchBatch + + struct Iterator: IteratorProtocol { + let start: UID? + var boundaries: ReversedCollection.Iterator + var last: UID? + + mutating func next() -> FetchBatch? { + while true { + guard + let uid = boundaries.next() + else { return nil } + guard + let last + else { + last = uid + continue + } + self.last = uid + guard uid == start else { + return .uidRange(uid.advanced(by: 1)...last) + } + // The last range has to include the last UID + return .uidRange(uid...last) + } + } + } + + func makeIterator() -> Iterator { + Iterator( + start: boundaries.first, + boundaries: boundaries.reversed().makeIterator() + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Partial.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Partial.swift new file mode 100644 index 00000000..8f9eb793 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch+Partial.swift @@ -0,0 +1,109 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +// MARK: - `PartialFetchBatches` strategy (RFC 9394 “Partial”) +// +// Used when the server supports RFC 9394 `PARTIAL`. Each batch is a +// `.partialLast(start...end)` referring to a window counted from the *end* of the +// mailbox (so `1` is the newest message). This avoids any preliminary SEARCH — +// the server resolves the window itself. +// +// `PartialFetchBatches` is the `Sequence` that walks from the newest message +// back to `last`, emitting one `.partialLast` batch per step of `batchSize`. + +/// Returns batches based on RFC 9394 “Partial” ranges. +/// +/// No preliminary `SEARCH` is needed — each batch resolves on the server. +func makePartialFetchBatch( + query: FetchQuery, + mailboxMessageCount: Int, + batchSize: BatchSize +) -> FetchBatches { + guard + let batches = PartialFetchBatches( + query: query, + mailboxMessageCount: mailboxMessageCount, + batchSize: batchSize + ) + else { return .empty } + return .partial(batches) +} + +/// A sequence of `FetchBatch` for a server that supports RFC 9394 “Partial”. +struct PartialFetchBatches: Hashable, Sendable { + /// The last message to include in the sequence. + /// + /// Note that 1 (`.min`) refers to the last message in the mailbox, whereas e.g + /// 1,000 would refer to the 1,000th message _from the end_ of the mailbox. + let last: SequenceNumber + let batchSize: BatchSize +} + +extension PartialFetchBatches { + init?( + query: FetchQuery, + mailboxMessageCount: Int, + batchSize: BatchSize + ) { + guard + 0 < mailboxMessageCount + else { return nil } + switch query { + case .last(count: let c): + guard + let l = SequenceNumber(exactly: Swift.min(c, mailboxMessageCount)) + else { return nil } + self.last = l + case .uids(let uids): + guard + let l = SequenceNumber(exactly: Swift.min(uids.count, mailboxMessageCount)) + else { return nil } + self.last = l + case .all: + self.last = SequenceNumber.min.advanced(by: Int64(mailboxMessageCount - 1)) + } + self.batchSize = batchSize + } +} + +extension PartialFetchBatches: Sequence { + typealias Element = FetchBatch + + struct Iterator: IteratorProtocol { + let last: SequenceNumber + let batchSize: BatchSize + var index = 0 + + mutating func next() -> FetchBatch? { + let range = batchSize.partialRange(batch: index) + guard + range.lowerBound <= last + else { return nil } + let end = Swift.min(last, range.upperBound) + index += 1 + return .partialLast(NIOIMAP.PartialRange.last(range.lowerBound...end)) + } + + typealias Element = FetchBatch + } + + func makeIterator() -> Iterator { + Iterator( + last: last, + batchSize: batchSize + ) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch.swift new file mode 100644 index 00000000..b6d761a7 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchBatch.swift @@ -0,0 +1,147 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +// MARK: - How batching works +// +// IMAP `UID FETCH` and `UID SEARCH` operate on potentially huge mailboxes. To stay +// within server limits (`MESSAGELIMIT`, RFC 9738) and to keep memory bounded, we +// partition the messages of interest into a sequence of `FetchBatch` values and +// issue one server round-trip per batch. +// +// `makeBatches(...)` picks one of three strategies based on the server capabilities +// and the shape of the request: +// +// ┌──────────────────────────────────────────────────────────────────────┐ +// │ Server supports RFC 9394 `PARTIAL` ? │ +// │ │ +// │ yes ──► `PartialFetchBatches` ── see `FetchBatch+Partial.swift` │ +// │ (`.partialLast(range)`, no extra SEARCH needed) │ +// │ │ +// │ no ──► one of two `UID range` strategies: │ +// │ │ +// │ query = .uids(_) ──► fixed `[UIDRange]` from the requested UIDs │ +// │ ── see `FetchBatch+Fixed.swift` │ +// │ │ +// │ query = .all / .last(n) ──► `UIDBatchFromBoundaries` │ +// │ ── see `FetchBatch+FromBoundaries` │ +// │ (one SEARCH for boundary UIDs first) │ +// └──────────────────────────────────────────────────────────────────────┘ +// +// Each strategy is implemented as its own `Sequence` of `FetchBatch` in a sibling +// file. `FetchBatches` is the enum that unifies them so callers can iterate without +// caring which strategy was chosen. + +/// Describes a batch of messages to fetch or search with `UID FETCH` or `UID SEARCH`. +/// +/// Supports RFC 9394 partial ranges or regular UID ranges. +/// Create batches using the `makeBatches()` function, which selects the best strategy +/// based on server capabilities. +enum FetchBatch: Hashable, Sendable { + /// A range of UIDs. + case uidRange(UIDRange) + /// A range using RFC 9394 “Partial” + case partialLast(NIOIMAP.PartialRange) +} + +extension FetchBatch { + func makeUIDs(_ query: FetchQuery) -> UIDSet { + switch (self, query) { + case (.uidRange(let range), .last), + (.uidRange(let range), .all): + return UIDSet(range) + case (.uidRange(let range), .uids(let allUIDs)): + return allUIDs.intersection(UIDSet(range)) + case (.partialLast, .last), + (.partialLast, .all): + return .all + case (.partialLast, .uids(let allUIDs)): + return allUIDs + } + } + + var fetchModifiers: [FetchModifier] { + switch self { + case .uidRange: [] + case .partialLast(let range): [FetchModifier.partial(range)] + } + } +} + +// MARK: Make Sequence + +extension ConnectionProtocol { + /// Returns a `FetchBatches` (that is, a `Sequence` of `FetchBatch`) based on the server capabilities. + /// + /// This spans the messages based on `query` and `mailboxMessageCount`. + func makeBatches( + query: FetchQuery, + mailboxMessageCount: Int, + capabilities: [Capability] + ) async throws -> FetchBatches { + let batchSize = BatchSize(capabilities: capabilities) + guard capabilities.contains(.partial) else { + return try await makeBoundaryFetchBatch( + query: query, + mailboxMessageCount: mailboxMessageCount, + batchSize: batchSize, + capabilities: capabilities + ) + } + return makePartialFetchBatch( + query: query, + mailboxMessageCount: mailboxMessageCount, + batchSize: batchSize + ) + } +} + +// MARK: Sequence(s) + +/// Describes the batches that we split the `FETCH` into. +enum FetchBatches { + case fixed([UIDRange]) + case partial(PartialFetchBatches) + case fromBoundaries(UIDBatchFromBoundaries) + + static var empty: FetchBatches { + FetchBatches.fixed([]) + } + + static func singleBatch(_ r: UIDRange) -> FetchBatches { + FetchBatches.fixed([r]) + } +} + +extension FetchBatches: Sequence { + func makeIterator() -> Iterator { + switch self { + case .fixed(let u): + Iterator(underlying: u.map { FetchBatch.uidRange($0) }.makeIterator()) + case .partial(let u): + Iterator(underlying: u.makeIterator()) + case .fromBoundaries(let u): + Iterator(underlying: u.makeIterator()) + } + } + + struct Iterator: IteratorProtocol { + var underlying: any IteratorProtocol + typealias Element = FetchBatch + mutating func next() -> FetchBatch? { + underlying.next() + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchQuery.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchQuery.swift new file mode 100644 index 00000000..a42effbb --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/FetchQuery.swift @@ -0,0 +1,127 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP + +/// Which messages to operate on. +enum FetchQuery: Hashable, Sendable { + /// Fetches the specific UIDs. + case uids(UIDSet) + /// Fetches the last `count` messages in a mailbox. + case last(count: Int) + /// Fetches all messages. + case all +} + +extension ConnectionProtocol { + /// Determines the best combination of `UIDSet` and `[FetchModifier]` to operate on messages in the mailbox. + /// + /// Use this for `UID FETCH`, `UID SEARCH`, and similar commands. This helper checks which capabilities + /// the server supports, and picks the best approach to split the work into multiple ranges or multiple + /// `UID FETCH` commands. + /// + /// It does not perform the `UID FETCH` itself, but repeatedly calls the `fetch` closure to do any fetching, + /// and the `update` closure to collect results. + func batched( + query: FetchQuery, + mailboxMessageCount: Int, + capabilities: [Capability], + fetch: @Sendable @escaping (FetchBatch) async throws -> InnerResult, + into _result: Result, + update: @Sendable (inout Result, InnerResult) throws -> Void + ) async throws -> Result { + let batches = try await makeBatches( + query: query, + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities + ) + // Run multiple concurrently: + let maxConcurrentTasks = 11 + return try await withThrowingTaskGroup( + of: InnerResult.self, + returning: Result.self + ) { group in + var batchIterator = batches.makeIterator() + + // A helper that does the actual work: + func addTask() { + guard let batch = batchIterator.next() else { return } + group.addTask { + try await fetch(batch) + } + } + + // Start the first set of tasks: + for _ in 0.. FetchQuery { + switch (count, all) { + case (nil, false): + // Default to “last 20”: + return .last(count: 20) + case (let c?, false): + return .last(count: c) + case (nil, true): + return .all + case (.some, true): + throw ValidationError("Must not specify both --count and --all.") + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identify.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identify.swift new file mode 100644 index 00000000..aef98c44 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identify.swift @@ -0,0 +1,53 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import OrderedCollections + +extension ConnectionProtocol { + /// Sends an `ID` command and returns the server's identity information. + func identify( + capabilities: [Capability] + ) async throws -> Identity { + guard + capabilities.contains(.id) + else { return Identity(capabilities: capabilities) } + + return try await send(.id(clientID)) { _, responses -> Identity in + var result = Identity( + capabilities: capabilities + ) + _ = try await responses.forEach { response in + guard + case .untagged(.id(let id)) = response + else { return } + result.serverID = Dictionary(uniqueKeysWithValues: id.map { ($0.key, $0.value) }) + }.getOK() + return result + } + } +} + +private let clientID: OrderedDictionary = [ + "name": "imap-tool", + "os": Identity.operatingSystemName, + "os-version": Identity.operatingSystemVersion, +] diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identity.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identity.swift new file mode 100644 index 00000000..48863880 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Identity.swift @@ -0,0 +1,108 @@ +//===----------------------------------------------------------------------===// +// +// 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 +#if canImport(Darwin) +import Darwin +#else +import Glibc +import SystemPackage +#endif + +/// The identity of a server, including its `ID` response and capabilities. +struct Identity: Hashable, Sendable { + /// The key-value pairs from the server’s `ID` response. + var serverID: [String: String?] + /// The capabilities advertised by the server. + var capabilities: [Capability] + + /// Creates a new identity with the given server ID and capabilities. + init( + serverID: [String: String?] = [:], + capabilities: [Capability] + ) { + self.serverID = serverID + self.capabilities = capabilities + } +} + +#if canImport(Darwin) + +extension Identity { + static var operatingSystemName: String? { + systemInformation(name: "kern.ostype") + } + + static var operatingSystemVersion: String? { + systemInformation(name: "kern.osproductversion") + } +} + +/// Retrieves system information by name. Wraps `sysctlbyname(3)`. +private func systemInformation(name: String) -> String? { + name.withCString { _name -> String? in + withUnsafeTemporaryAllocation(of: UInt8.self, capacity: 200) { buffer -> String? in + var count = buffer.count + guard sysctlbyname(_name, buffer.baseAddress, &count, nil, 0) == 0 + else { return nil } + guard 0 < count else { return nil } + // sysctlbyname includes a trailing NUL in the byte count. + return String(decoding: buffer.prefix(count - 1), as: UTF8.self) + } + } +} + +#else + +extension Identity { + static var operatingSystemName: String? { + systemInformation(name: "ostype") + } + + static var operatingSystemVersion: String? { + systemInformation(name: "osrelease") + } +} + +/// Retrieves system information by name. Reads from `/proc/sys/kernel/`. +private func systemInformation(name: String) -> String? { + let url = URL(fileURLWithPath: "/proc/sys/kernel/\(name)") + guard + let data = try? Data(contentsOf: url), + let text = String(data: data, encoding: .utf8) + else { return nil } + return text.trimmingCharacters(in: .whitespacesAndNewlines) +} + +#endif + +extension Identity: Encodable { + func encode(to encoder: Encoder) throws { + var c = encoder.container(keyedBy: CodingKeys.self) + try c.encode(self.serverID, forKey: .id) + try c.encode(self.capabilities.map { String($0) }, forKey: .capabilities) + } + + enum CodingKeys: String, CodingKey { + case id + case capabilities + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/IdleEvents.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/IdleEvents.swift new file mode 100644 index 00000000..d7d576b1 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/IdleEvents.swift @@ -0,0 +1,232 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension IMAPConnection { + /// Runs an `IDLE` command and passes the event stream to the given closure. + func runIdle( + _ closure: (IMAPConnection.Tag, IdleEventStream) async throws -> Result + ) async throws -> Result { + try await sendIdle { tag, responses in + writeStatus("Running IDLE as \(tag)") + let r = try await closure(tag, IdleEventStream(underlying: responses)) + writeStatus("Did run IDLE") + return r + } + } +} + +// MARK: Event + +/// An event received during an `IDLE` session. +enum IdleEvent: Equatable, Sendable { + /// The mailbox now contains this many messages. + case exists(Int) + /// The message at this sequence number was expunged. + case expunge(SequenceNumber) + /// The given UIDs were removed (via `VANISHED`). + case vanished(UIDSet) + /// A `FETCH` response with the given attributes. + case fetch(SequenceNumber?, [MessageAttribute]) +} + +extension IdleEvent: Encodable { + /// Encodes the event into a format that is straightforward to read and parse. + func encode(to encoder: any Encoder) throws { + var container = encoder.container(keyedBy: CodingKeys.self) + try container.encode(kind, forKey: .kind) + switch self { + case .exists(let count): + try container.encode(count, forKey: .count) + case .expunge(let seq): + try container.encode(UInt32(seq), forKey: .sequenceNumber) + case .vanished(let uids): + // Two encodings: + // - `uids` — the canonical IMAP wire form (e.g. `"1:5,7,9:12"`), + // for clients that prefer the compact range syntax. + // - `uidsList` — a fully-expanded JSON array of UIDs, for clients + // that don't want to parse the IMAP grammar. + // + // `debugDescription` on `MessageIdentifierSet` produces the wire + // form by running its IMAP encoder, so this is stable across runs. + try container.encode(uids.debugDescription, forKey: .uids) + try container.encode(uids.map { UInt32($0) }, forKey: .uidsList) + case .fetch(let seq, let attributes): + try container.encodeIfPresent(seq.map { UInt32($0) }, forKey: .sequenceNumber) + // We need to keep track of what (which keys) we’ve already added. + // We might receive the same key multiple times, but we can only encode it once. + var allKeys = Set() + + func check(key: CodingKeys) -> Bool { + guard !allKeys.contains(key) else { return false } + allKeys.insert(key) + return true + } + + for attr in attributes { + switch attr { + case .flags(let flags): + guard check(key: .flags) else { continue } + try container.encode(flags.map { String($0) }, forKey: .flags) + case .uid(let uid): + guard check(key: .uid) else { continue } + try container.encode(UInt32(uid), forKey: .uid) + case .rfc822Size(let count): + guard check(key: .rfc822Size) else { continue } + try container.encode(count, forKey: .rfc822Size) + case .fetchModificationSequence(let modSeq): + guard check(key: .fetchModificationResponse) else { continue } + try container.encode(UInt64(modSeq), forKey: .fetchModificationResponse) + case .gmailMessageID(let id): + guard check(key: .gmailMessageID) else { continue } + try container.encode(id, forKey: .gmailMessageID) + case .gmailThreadID(let id): + guard check(key: .gmailThreadID) else { continue } + try container.encode(id, forKey: .gmailThreadID) + case .gmailLabels(let labels): + guard check(key: .gmailLabels) else { continue } + try container.encode(labels.map { $0.makeDisplayString() }, forKey: .gmailLabels) + case .preview(let preview): + guard check(key: .preview) else { continue } + try container.encode(preview.map { String($0) }, forKey: .preview) + case .emailID(let id): + guard check(key: .emailID) else { continue } + try container.encode(String(id), forKey: .emailID) + case .threadID(let id): + guard check(key: .threadID) else { continue } + try container.encode(id.map { String($0) }, forKey: .threadID) + default: + continue + } + } + } + } + + var kind: String { + switch self { + case .exists: "exists" + case .expunge: "expunge" + case .vanished: "vanished" + case .fetch: "fetch" + } + } + + enum CodingKeys: String, CodingKey { + case kind + case count + case sequenceNumber + case uids + case uidsList + + case flags + case uid + case rfc822Size + case fetchModificationResponse + case gmailMessageID + case gmailThreadID + case gmailLabels + case preview + case emailID + case threadID + + } +} + +// MARK: Event Decoder + +enum IdleEventDecoder: Sendable { + case normal + case fetch(SequenceNumber?, [MessageAttribute]) +} + +extension IdleEventDecoder { + mutating func update( + _ response: Response + ) -> IdleEvent? { + switch (self, response) { + case (.normal, .fetch(.start(let seq))): + self = .fetch(seq, []) + return nil + case (.normal, .fetch(.startUID(let uid))): + self = .fetch(nil, [.uid(uid)]) + return nil + case (.fetch(let seq, var attr), .fetch(.simpleAttribute(let new))): + attr.append(new) + self = .fetch(seq, attr) + return nil + case (.fetch(let seq, let attr), .fetch(.finish)): + self = .normal + return .fetch(seq, attr) + case (.fetch, .fetch(.streamingBegin)), + (.fetch, .fetch(.streamingBytes)), + (.fetch, .fetch(.streamingEnd)): + // Ignore bytes being streamed + return nil + case (.fetch, _): + // We received something that’s not part of FETCH. Should not happen, but ignore. + return nil + case (.normal, .fetch): + // Should not happen, but ignore. + return nil + case (.normal, .untagged(.mailboxData(.exists(let count)))): + return .exists(count) + case (.normal, .untagged(.messageData(.expunge(let seq)))): + return .expunge(seq) + case (.normal, .untagged(.messageData(.vanished(let uids)))): + return .vanished(uids) + case (.normal, _): + return nil + } + } +} + +// MARK: Idle Stream + +/// An async sequence that transforms raw IMAP responses into `IdleEvent` values. +struct IdleEventStream: AsyncSequence, Sendable { + /// The iterator that decodes responses into idle events. + struct AsyncIterator: AsyncIteratorProtocol { + typealias Element = IdleEvent + + var underlying: IMAPConnection.ResponseStream.AsyncIterator + var decoder = IdleEventDecoder.normal + + mutating func next() async throws -> IdleEvent? { + while let response = try await underlying.next() { + guard + let event = decoder.update(response) + else { continue } + writeStatus("Did receive '\(event.kind)' during IDLE") + return event + } + return nil + } + } + + typealias Element = IdleEvent + + let underlying: IMAPConnection.ResponseStream + + func makeAsyncIterator() -> AsyncIterator { + AsyncIterator(underlying: underlying.makeAsyncIterator()) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ListStatus.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ListStatus.swift new file mode 100644 index 00000000..85ddc431 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/ListStatus.swift @@ -0,0 +1,390 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import AsyncAlgorithms +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP + +extension ConnectionProtocol { + /// Runs `LIST` and `STATUS` on all mailboxes for the account. + /// + /// Uses `LIST-STATUS` (RFC 5819) if available, or falls back to separate `LIST` and `STATUS` commands + /// based on the capabilities of the server. + func listMailboxes( + capabilities: [Capability] + ) async throws -> [MailboxInfoAndStatus] { + try await list( + capabilities: capabilities, + target: .allMailboxes + ) + } + + func listMailbox( + capabilities: [Capability], + mailbox: MailboxName + ) async throws -> MailboxInfoAndStatus? { + let allInfo = try await list( + capabilities: capabilities, + target: .specific(mailbox) + ) + return allInfo.first(where: { $0.path.name == mailbox }) + } +} + +enum ListTarget: Hashable, Sendable { + case allMailboxes + case specific(MailboxName) +} + +extension ConnectionProtocol { + func list( + capabilities: [Capability], + target: ListTarget + ) async throws -> [MailboxInfoAndStatus] { + let strategy = ListStatusStrategy( + capabilities: capabilities + ) + + switch strategy.kind { + case .listThenStatus: + let listInfo = try await list( + target: target, + listReturnOptions: strategy.listReturnOptions + ) + let statusInfo = try await status( + mailboxes: listInfo.keys.lazy.map { $0.name }, + statusAttributes: strategy.statusAttributes + ) + return combineListAndStatus( + listInfo: listInfo, + statusInfo: statusInfo + ) + case .listStatus: + return try await listStatus( + target: target, + listReturnOptions: strategy.listReturnOptions, + statusAttributes: strategy.statusAttributes + ) + } + } +} + +// MARK: Strategy + +struct ListStatusStrategy: Hashable, Sendable { + var listReturnOptions: [ReturnOption] + var statusAttributes: [MailboxAttribute] + var kind: Kind + + enum Kind: Hashable, Sendable { + /// Run LIST followed by STATUS for each mailbox + case listThenStatus + /// Run LIST-STATUS + case listStatus + } +} + +extension ListStatusStrategy { + init( + capabilities: [Capability] + ) { + self.init( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + ], + kind: .listThenStatus + ) + + // RFC 5162 + if capabilities.contains(.condStore) { + statusAttributes.append(.highestModificationSequence) + } + // RFC 6154 + if capabilities.contains(.specialUse) { + listReturnOptions.append(.specialUse) + } + // RFC 7889 + // Disabled for now. Many servers fail on this. + if false && capabilities.contains(where: { $0.name == "APPENDLIMIT" }) { + statusAttributes.append(.appendLimit) + } + // RFC 8438 "STATUS=SIZE" + if capabilities.contains(Capability("STATUS=SIZE")) { + statusAttributes.append(.size) + } + // RFC 5819 “LIST-STATUS” + kind = capabilities.contains(.listStatus) ? .listStatus : .listThenStatus + } +} + +// MARK: - List then Status + +private func combineListAndStatus( + listInfo: [MailboxPath: [MailboxInfo.Attribute]], + statusInfo: [MailboxName: MailboxStatus] +) -> [MailboxInfoAndStatus] { + return + listInfo + .reduce(into: []) { all, list in + all.append( + MailboxInfoAndStatus( + path: list.key, + attributes: Set(list.value), + status: statusInfo[list.key.name] + ) + ) + } + .sorted { + stableCompare($0.path.name, $1.path.name) + } +} + +// MARK: - + +/// The combined result of `LIST` and `STATUS` for a single mailbox. +struct MailboxInfoAndStatus: Hashable, Sendable { + /// The mailbox path including its separator. + var path: MailboxPath + /// The mailbox attributes from `LIST`. + var attributes: Set + /// The mailbox status from `STATUS`, if available. + var status: MailboxStatus? +} + +extension MailboxInfoAndStatus { + /// An encodable representation of mailbox information and status. + struct EncodableInfo: Encodable, Sendable { + /// The raw mailbox name as a string. + var name: String? + /// The path separator character. + var pathSeparator: String? + /// The display name split into path components. + var displayName: [String] + /// The mailbox attributes as strings. + var attributes: [String] + + /// The total number of messages in the mailbox. + var messageCount: Int? + /// The predicted next UID value. + var nextUID: UInt32? + /// The UID validity value for the mailbox. + var uidValidity: UInt32? + /// The number of unseen messages. + var unseenCount: Int? + /// The highest modification sequence value. + var highestModificationSequence: UInt64? + /// The per-message append size limit, if the server reports one. + var appendLimit: Int? + } +} + +extension MailboxInfoAndStatus.EncodableInfo { + /// Creates an encodable representation from a `MailboxInfoAndStatus`. + init(_ other: MailboxInfoAndStatus) { + self.init( + name: String(validating: other.path.name.bytes, as: UTF8.self), + pathSeparator: other.path.pathSeparator.map { String($0) }, + displayName: other.path.displayStringComponents(omittingEmptySubsequences: false), + attributes: other.attributes.map { String($0) }.sorted(), + messageCount: other.status?.messageCount, + nextUID: (other.status?.nextUID).map { UInt32($0) }, + uidValidity: (other.status?.uidValidity).map { UInt32($0) }, + unseenCount: other.status?.unseenCount, + highestModificationSequence: (other.status?.highestModificationSequence).map { UInt64($0) }, + appendLimit: other.status?.appendLimit + ) + } +} + +// MARK: - + +extension Command { + fileprivate static func list( + target: ListTarget, + returnOptions: [ReturnOption] + ) -> Command { + switch target { + case .allMailboxes: .listAllMailboxes(returnOptions: returnOptions) + case .specific(let name): .listMailbox(mailbox: name, returnOptions: returnOptions) + } + } + + fileprivate static func listAllMailboxes( + returnOptions: [ReturnOption] + ) -> Command { + Command.listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(string: "*")), + returnOptions + ) + } + + fileprivate static func listMailbox( + mailbox: MailboxName, + returnOptions: [ReturnOption] + ) -> Command { + Command.listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(bytes: mailbox.bytes)), + returnOptions + ) + } +} + +extension ConnectionProtocol { + private func list( + target: ListTarget, + listReturnOptions: [ReturnOption] + ) async throws -> [MailboxPath: [MailboxInfo.Attribute]] { + let command = Command.list( + target: target, + returnOptions: listReturnOptions + ) + return try await send(command) { tag, responses in + var all: [MailboxPath: [MailboxInfo.Attribute]] = [:] + for try await response in responses { + switch response { + case .untagged(.mailboxData(.list(let info))): + all[info.path] = info.attributes + case .tagged(let r): + try r.checkOK() + default: + break + } + } + return all + } + } + + private func status( + mailboxes: some Sequence, + statusAttributes: [MailboxAttribute] + ) async throws -> [MailboxName: MailboxStatus] { + // Loop over all mailboxes + // Pipeline a few STATUS at the time: + let concurrencyLimit = 5 + + return try await withThrowingTaskGroup { group in + var remaining = mailboxes.makeIterator() + var submittedCount = 0 + + func popNextMailbox() -> MailboxName? { + guard + submittedCount < concurrencyLimit, + let result = remaining.next() + else { return nil } + submittedCount += 1 + return result + } + + while let mailbox = popNextMailbox() { + group.addTask { + let s = try await self.status( + mailbox: mailbox, + statusAttributes: statusAttributes + ) + return (mailbox, s) + } + } + + var all: [MailboxName: MailboxStatus] = [:] + for try await result in group { + if let s = result.1 { + all[result.0] = s + } + + submittedCount -= 1 + // Every time we get a result back, check if there's more work we should submit and do so + if let mailbox = popNextMailbox() { + group.addTask { + let s = try await self.status( + mailbox: mailbox, + statusAttributes: statusAttributes + ) + return (mailbox, s) + } + } + } + return all + } + } + + private func status( + mailbox: MailboxName, + statusAttributes: [MailboxAttribute] + ) async throws -> MailboxStatus? { + try await send(.status(mailbox, statusAttributes)) { tag, responses in + var result: MailboxStatus? + for try await response in responses { + switch response { + case .untagged(.mailboxData(.status(mailbox, let status))): + result = status + case .tagged(let r): + try r.checkOK() + default: + break + } + } + return result + } + } +} + +// MARK: - List-Status + +extension ConnectionProtocol { + /// Use RFC 5819 “LIST-STATUS” to get LIST and STATUS with a single command. + private func listStatus( + target: ListTarget, + listReturnOptions: [ReturnOption], + statusAttributes: [MailboxAttribute] + ) async throws -> [MailboxInfoAndStatus] { + let command = Command.list( + target: target, + returnOptions: listReturnOptions + [.statusOption(statusAttributes)] + ) + return try await send(command) { tag, responses in + var list: [MailboxPath: [MailboxInfo.Attribute]] = [:] + var status: [MailboxName: MailboxStatus] = [:] + for try await response in responses { + switch response { + case .untagged(.mailboxData(.list(let info))): + list[info.path] = info.attributes + case .untagged(.mailboxData(.status(let mailbox, let s))): + status[mailbox] = s + case .tagged(let r): + try r.checkOK() + default: + break + } + } + return combineListAndStatus( + listInfo: list, + statusInfo: status + ) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/MoveMessage.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/MoveMessage.swift new file mode 100644 index 00000000..009019ca --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/MoveMessage.swift @@ -0,0 +1,110 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Moves messages from the currently selected mailbox to another mailbox. + /// + /// The source mailbox must already be selected before calling this function. + /// Requiring a ``SelectInfo`` argument makes that prerequisite visible in the + /// type signature, even though the value itself is not read. + func moveMessages( + selectInfo _: SelectInfo, + capabilities: [Capability], + uids _uids: UIDSet, + to destinationMailbox: MailboxName + ) async throws { + guard + let uids = MessageIdentifierSetNonEmpty(set: _uids) + else { return } + + // Check if server supports MOVE command (RFC 6851) + if capabilities.contains(.move) { + try await moveMessagesUsingMoveCommand( + uids: uids, + to: destinationMailbox + ) + } else { + try await moveMessagesUsingCopyCommand( + uids: uids, + to: destinationMailbox + ) + } + } + + /// Moves messages using `UID MOVE`. + private func moveMessagesUsingMoveCommand( + uids: MessageIdentifierSetNonEmpty, + to destinationMailbox: MailboxName + ) async throws { + let text = try await send( + .uidMove(.set(uids), destinationMailbox) + ) { tag, responses in + writeStatus("Did send UID MOVE \(uids.set.count) message(s) to '\(destinationMailbox)' with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + + writeStatus("Did UID MOVE message(s): \(text)") + } + + /// Moves messages using `UID COPY` followed by `UID STORE` and `EXPUNGE`. + /// + /// Used when the server does not advertise the `MOVE` capability (RFC 6851). + /// + /// - Note: The final `EXPUNGE` is a plain, mailbox-wide expunge (RFC 3501): it + /// permanently removes *every* message flagged `\Deleted` in the selected + /// mailbox, not only the ones copied here. This is intentional. A mailbox is + /// commonly accessed from several devices at once, any of which may expunge at + /// any time, so relying on `\Deleted` messages lingering is unsafe — the modern + /// best practice is to expunge right after flagging. + private func moveMessagesUsingCopyCommand( + uids: MessageIdentifierSetNonEmpty, + to destinationMailbox: MailboxName + ) async throws { + // UID COPY + let copyText = try await send( + .uidCopy(.set(uids), destinationMailbox) + ) { tag, responses in + writeStatus("Did send UID COPY \(uids.set.count) message(s) to '\(destinationMailbox)' with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did UID COPY message(s): \(copyText)") + + // UID STORE + let storeText = try await send( + .uidStore(.set(uids), [], .flags(.add(silent: true, list: [.deleted]))) + ) { tag, responses in + writeStatus("Did send UID STORE \\Deleted with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did mark message(s) as deleted: \(storeText)") + + // EXPUNGE + let expungeText = try await send(.expunge) { tag, responses in + writeStatus("Did send EXPUNGE with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did EXPUNGE: \(expungeText)") + + writeStatus("Did move \(uids.set.count) message(s) using UID COPY") + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/RenameMailbox.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/RenameMailbox.swift new file mode 100644 index 00000000..f46c9121 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/RenameMailbox.swift @@ -0,0 +1,39 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Renames a mailbox on the server. + func renameMailbox( + capabilities: [Capability], + old oldName: MailboxName, + new newName: MailboxName + ) async throws { + let text = try await send( + .rename(from: oldName, to: newName, parameters: [:]) + ) { tag, responses in + writeStatus("Did send RENAME mailbox '\(oldName)' to '\(newName)' with tag \(tag)") + return try await responses.waitForCompletion() + }.getOK() + writeStatus("Did RENAME mailbox '\(oldName)' to '\(newName)': \(text)") + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search.swift new file mode 100644 index 00000000..abc1ce43 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search.swift @@ -0,0 +1,270 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension ConnectionProtocol { + /// Returns all UIDs matching the given fetch query. + func allUIDs( + query: FetchQuery, + mailboxMessageCount: Int, + capabilities: [Capability] + ) async throws -> UIDSet { + try await batchedSearch( + key: .all, + query: query, + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities + ) + } +} + +extension SearchKey { + static func messageID(_ id: MessageID) -> SearchKey { + .header("message-id", ByteBuffer(string: String(id))) + } + + static func messageID(_ ids: some Sequence) -> SearchKey? { + ids.reduce( + into: SearchKey?.none, + { all, id in + let new = SearchKey.messageID(id) + if let a = all { + all = SearchKey.or(a, new) + } else { + all = new + } + } + ) + } + + /// Will match the last `count` messages in a mailbox with `mailboxMessageCount` messages. + static func lastMessages( + count: Int, + mailboxMessageCount: Int + ) -> SearchKey { + guard + count < mailboxMessageCount + else { return .all } + let end = SequenceNumber + .min + .advanced(by: Int64(mailboxMessageCount)) + .advanced(by: -Int64(count)) + let range = MessageIdentifierSetNonEmpty(range: end...SequenceNumber.max) + return .sequenceNumbers(.set(range)) + } +} + +// MARK: - + +extension ConnectionProtocol { + /// Performs a search for the given `SearchKey`, but splits the messages into batches + /// and runs multiple searches, one on each batch. + func batchedSearch( + key searchKey: SearchKey, + query: FetchQuery, + mailboxMessageCount: Int, + capabilities: [Capability] + ) async throws -> UIDSet { + try await batched( + query: query, + mailboxMessageCount: mailboxMessageCount, + capabilities: capabilities, + fetch: { batch in + try await self.searchBatch( + capabilities: capabilities, + key: searchKey, + query: query, + batch: batch + ) ?? UIDSet() + }, + into: UIDSet(), + update: { + $0.formUnion($1) + } + ) + } +} + +extension SearchKey { + /// Combine the given `SearchKey` with a predicate that limits the UIDs to the ones in the given `FetchBatch`. + static func combine( + key searchKey: SearchKey, + query: FetchQuery, + batch: FetchBatch + ) -> Self { + let uids = batch.makeUIDs(query) + guard uids != .all else { return searchKey } + guard let set = UIDSetNonEmpty(set: uids) else { return .not(.all) } + let uidKey = SearchKey.uid(.set(set)) + guard searchKey != .all else { return uidKey } + return SearchKey.and([uidKey, searchKey]) + } +} + +extension ConnectionProtocol { + /// Sends a `UID SEARCH` command. + /// + /// Depending on the server capabilities, a normal (RFC 3501), an extended, or a partial + /// search command may be used. + func searchBatch( + capabilities: [Capability], + key searchKey: SearchKey, + query: FetchQuery, + batch: FetchBatch + ) async throws -> UIDSet? { + let combined = SearchKey.combine( + key: searchKey, + query: query, + batch: batch + ) + + switch batch { + case .uidRange: + return try await search( + capabilities: capabilities, + kind: .nonPartial(combined) + ) + case .partialLast(let partialRange): + return try await search( + capabilities: capabilities, + kind: .partial(partialRange, combined) + ) + } + } +} + +// MARK: - + +extension ConnectionProtocol { + /// Sends a `UID SEARCH` command. + /// + /// Depending on the server capabilities, a normal (RFC 3501), an extended, or a partial + /// search command may be used. + func search( + capabilities: [Capability], + key searchKey: SearchKey + ) async throws -> UIDSet { + guard capabilities.contains(.partial) else { + return try await search( + capabilities: capabilities, + kind: .nonPartial(searchKey) + ) ?? UIDSet() + } + let batchSize = BatchSize(capabilities: capabilities) + + var uids = UIDSet() + for batch in 0... { + let range = NIOIMAP.PartialRange.last(SequenceRange(batchSize.partialRange(batch: batch))) + writeStatus("[PARTIAL SEARCH] searching range \(range)") + let newUIDs = try await search( + capabilities: capabilities, + kind: .partial(range, searchKey) + ) + guard let newUIDs, !newUIDs.isEmpty else { break } + writeStatus("[PARTIAL SEARCH] Batch \(batch + 1) returned \(newUIDs.count) UIDs") + uids.formUnion(newUIDs) + } + writeStatus("Did find \(uids.count) UIDs using PARTIAL SEARCH") + return uids + } +} + +struct NoUntaggedSearchResponse: Swift.Error {} + +// MARK: - + +enum SearchKind: Hashable, Sendable { + case nonPartial(SearchKey) + case partial(NIOIMAP.PartialRange, SearchKey) +} + +extension ConnectionProtocol { + func search( + capabilities: [Capability], + kind: SearchKind, + ) async throws -> UIDSet? { + let searchKey: SearchKey + let returnOptions: [SearchReturnOption] + switch kind { + case .partial(let range, let key): + searchKey = key + returnOptions = [.partial(range)] + case .nonPartial(let key): + searchKey = key + returnOptions = capabilities.contains(.extendedSearch) ? [.all] : [] + } + + guard returnOptions.isEmpty else { + let uids = try await sendUIDSearch( + key: searchKey, + returnOptions: returnOptions + ) { tag, response in + guard + case .untagged(.mailboxData(.extendedSearch(let result))) = response, + let c = result.correlator, + c.tag == "\(tag)" + else { return nil } + return result.matchedUIDs ?? UIDSet() + } + writeStatus("Did find \(uids?.count ?? 0) UIDs using extended UID SEARCH") + return uids + } + let uids = try await sendUIDSearch( + key: searchKey, + returnOptions: [] + ) { _, response in + guard + case .untagged(.mailboxData(.search(let ids, _))) = response + else { return nil } + return UIDSet(MessageIdentifierSet(ids)) + } + writeStatus("Did find \(uids?.count ?? 0) UIDs using UID SEARCH") + return uids + } + + /// Sends a `UID SEARCH` command and extracts matching UIDs from untagged responses + /// using `extract`. Throws `NoUntaggedSearchResponse` if no matching untagged response + /// arrived before the tagged completion. + private func sendUIDSearch( + key searchKey: SearchKey, + returnOptions: [SearchReturnOption], + extract: @Sendable @escaping (IMAPConnection.Tag, Response) -> UIDSet? + ) async throws -> UIDSet? { + try await send( + .uidSearch( + key: searchKey, + charset: nil, + returnOptions: returnOptions + ) + ) { tag, responses in + var didFind = false + var uids: UIDSet? + try await responses.forEach { response in + guard let extracted = extract(tag, response) else { return } + didFind = true + uids = extracted + }.checkOK() + guard didFind else { throw NoUntaggedSearchResponse() } + return uids + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search_Predicate.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search_Predicate.swift new file mode 100644 index 00000000..0903e15d --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/Search_Predicate.swift @@ -0,0 +1,281 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import IMAPCommands +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIO +import NIOIMAP + +extension SearchKey { + /// A combination of search criteria for filtering messages. + struct Predicate: Hashable, Sendable { + var olderThanDays: Int? + var newerThanDays: Int? + var subject: String? + var from: String? + var to: String? + var cc: String? + var text: String? + var messageSizeSmallerThan: Int? + var messageSizeLargerThan: Int? + var messageID: MessageID? + var emailID: EmailID? + var threadID: ThreadID? + var flagsSet: Set + var flagsNotSet: Set + + init( + olderThanDays: Int? = nil, + newerThanDays: Int? = nil, + subject: String? = nil, + from: String? = nil, + to: String? = nil, + cc: String? = nil, + text: String? = nil, + messageSizeSmallerThan: Int? = nil, + messageSizeLargerThan: Int? = nil, + messageID: MessageID? = nil, + emailID: EmailID? = nil, + threadID: ThreadID? = nil, + flagsSet: Set = [], + flagsNotSet: Set = [] + ) { + self.olderThanDays = olderThanDays + self.newerThanDays = newerThanDays + self.subject = subject + self.from = from + self.to = to + self.cc = cc + self.text = text + self.messageSizeSmallerThan = messageSizeSmallerThan + self.messageSizeLargerThan = messageSizeLargerThan + self.messageID = messageID + self.emailID = emailID + self.threadID = threadID + self.flagsSet = flagsSet + self.flagsNotSet = flagsNotSet + } + } +} + +extension SearchKey.Predicate: CustomStringConvertible { + var description: String { + var components: [String] = [] + if let olderThanDays { + components.append("olderThanDays: \(olderThanDays)") + } + if let newerThanDays { + components.append("newerThanDays: \(newerThanDays)") + } + if let subject { + components.append("subject: \"\(subject)\"") + } + if let from { + components.append("from: \"\(from)\"") + } + if let to { + components.append("to: \"\(to)\"") + } + if let cc { + components.append("cc: \"\(cc)\"") + } + if let text { + components.append("text: \"\(text)\"") + } + if let messageSizeSmallerThan { + components.append("messageSizeSmallerThan: \(messageSizeSmallerThan)") + } + if let messageSizeLargerThan { + components.append("messageSizeLargerThan: \(messageSizeLargerThan)") + } + if let messageID { + components.append("messageID: \(messageID)") + } + if let emailID { + components.append("emailID: \(emailID)") + } + if let threadID { + components.append("threadID: \(threadID)") + } + if !flagsSet.isEmpty { + components.append("flagsSet: [\(flagsSet.map { String($0) }.joined(separator: ", "))]") + } + if !flagsNotSet.isEmpty { + components.append("flagsNotSet: [\(flagsNotSet.map { String($0) }.joined(separator: ", "))]") + } + return components.joined(separator: ", ") + } +} + +extension IMAPCalendarDay { + init( + days: Int, + since now: Date, + timeZone: TimeZone + ) throws { + var calendar = Calendar(identifier: .gregorian) + calendar.timeZone = timeZone + + guard + let date = calendar.date( + byAdding: .day, + value: -days, + to: now + ) + else { throw ValidationError("Can not construct date with \(days) day(s) before now.") } + let components = calendar.dateComponents([.year, .month, .day], from: date) + guard + let result = IMAPCalendarDay( + year: components.year!, + month: components.month!, + day: components.day! + ) + else { throw ValidationError("Can not construct date with \(days) day(s) since now.") } + self = result + } +} + +extension SearchKey { + /// Builds search criteria from common parameters. + init( + _ predicate: Predicate, + now: Date = Date(), + timeZone: TimeZone = TimeZone.current + ) throws { + var keys: [SearchKey] = [] + + // Date based searches: + if let days = predicate.olderThanDays { + try keys.append( + .sentBefore( + IMAPCalendarDay( + days: days, + since: now, + timeZone: timeZone + ) + ) + ) + } + if let days = predicate.newerThanDays { + try keys.append( + .sentSince( + IMAPCalendarDay( + days: days, + since: now, + timeZone: timeZone + ) + ) + ) + } + + // Text-based searches + if let subject = predicate.subject { + keys.append(.subject(ByteBuffer(string: subject))) + } + if let from = predicate.from { + keys.append(.from(ByteBuffer(string: from))) + } + if let to = predicate.to { + keys.append(.to(ByteBuffer(string: to))) + } + if let cc = predicate.cc { + keys.append(.cc(ByteBuffer(string: cc))) + } + if let text = predicate.text { + keys.append(.text(ByteBuffer(string: text))) + } + + // Size-based searches + if let size = predicate.messageSizeSmallerThan { + keys.append(.messageSizeSmaller(size)) + } + if let size = predicate.messageSizeLargerThan { + keys.append(.messageSizeLarger(size)) + } + + // ID-based searches + if let messageID = predicate.messageID { + keys.append(.messageID(messageID)) + } + if let emailID = predicate.emailID { + keys.append(.emailID(emailID)) + } + if let threadID = predicate.threadID { + keys.append(.threadID(threadID)) + } + + // Flag-based searches + for flag in predicate.flagsSet.sorted(by: { String($0) < String($1) }) { + try keys.append(.init(flag: flag)) + } + + for flag in predicate.flagsNotSet.sorted(by: { String($0) < String($1) }) { + try keys.append(.init(notFlag: flag)) + } + + // Combine all keys + if keys.isEmpty { + self = .all + } else if keys.count == 1 { + self = keys[0] + } else { + self = .and(keys) + } + } + + init( + flag: NIOIMAP.Flag + ) throws { + if flag == .answered { + self = .answered + } else if flag == .flagged { + self = .flagged + } else if flag == .deleted { + self = .deleted + } else if flag == .seen { + self = .seen + } else if flag == .draft { + self = .draft + } else if let keyword = NIOIMAP.Flag.Keyword(String(flag)) { + self = .keyword(keyword) + } else { + throw ValidationError("Invalid flag: \(String(flag))") + } + } + + init( + notFlag flag: NIOIMAP.Flag + ) throws { + if flag == .answered { + self = .unanswered + } else if flag == .flagged { + self = .unflagged + } else if flag == .deleted { + self = .undeleted + } else if flag == .seen { + self = .unseen + } else if flag == .draft { + self = .undraft + } else if let keyword = NIOIMAP.Flag.Keyword(String(flag)) { + self = .not(.keyword(keyword)) + } else { + throw ValidationError("Invalid flag: \(String(flag))") + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/SelectMailbox.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/SelectMailbox.swift new file mode 100644 index 00000000..4dffb1bb --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/SelectMailbox.swift @@ -0,0 +1,249 @@ +//===----------------------------------------------------------------------===// +// +// 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 ` 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 + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Operations/UpdateFlags.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/UpdateFlags.swift new file mode 100644 index 00000000..78be2f1d --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Operations/UpdateFlags.swift @@ -0,0 +1,81 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP + +/// Describes flags to add and remove from messages. +struct FlagChanges: Hashable, Sendable { + /// The flags to add to the messages. + var set: [NIOIMAP.Flag] + /// The flags to remove from the messages. + var unset: [NIOIMAP.Flag] + + /// Creates a new flag change set with the given flags to add and remove. + init( + set: [NIOIMAP.Flag], + unset: [NIOIMAP.Flag] + ) { + self.set = set + self.unset = unset + } + + var isEmpty: Bool { + self.set.isEmpty && self.unset.isEmpty + } +} + +extension ConnectionProtocol { + /// Updates flags on the messages specified by UIDs. + func updateFlags( + uids: UIDSet, + changes: FlagChanges + ) async throws { + try await sendStore( + uids: uids, + flags: changes.set, + operatorLabel: "+FLAGS", + makeStoreFlags: { StoreFlags.add(silent: false, list: $0) } + ) + try await sendStore( + uids: uids, + flags: changes.unset, + operatorLabel: "-FLAGS", + makeStoreFlags: { StoreFlags.remove(silent: false, list: $0) } + ) + } + + private func sendStore( + uids: UIDSet, + flags: [NIOIMAP.Flag], + operatorLabel: String, + makeStoreFlags: ([NIOIMAP.Flag]) -> StoreFlags + ) async throws { + guard + !flags.isEmpty, + let command = Command.uidStore( + messages: uids, + modifiers: [], + data: StoreData.flags(makeStoreFlags(flags)) + ) + else { return } + try await send(command) { tag, responses in + writeStatus( + "Did send UID STORE \(operatorLabel) \(flags.map { String($0) }.joined(separator: ", ")) with tag \(tag)" + ) + return try await responses.waitForCompletion() + }.checkOK() + writeStatus("Did UID STORE \(operatorLabel) on \(uids.count) UID(s)") + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bar.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bar.swift new file mode 100644 index 00000000..5910e69d --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bar.swift @@ -0,0 +1,78 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +// `NumberFormatter` is not part of `FoundationEssentials`. +import Foundation + +extension String { + /// Creates a Unicode bar that’s `width` wide, and `fraction` of it filled in. + static func barWithLabel(fraction: Double, width: Int) -> String { + let basic = self.bar(fraction: fraction, width: width) + let label = formatFraction(fraction) + // We need room for the label plus at least one bar character. If the + // bar is too narrow (or empty), fall back to the plain bar. + guard 11 <= width, label.count + 1 <= basic.count else { return basic } + guard fraction < 0.5 else { + return String(basic.prefix(1)) + label + + String(basic.suffix(from: basic.index(basic.startIndex, offsetBy: 1 + label.count))) + } + return basic.prefix(basic.count - label.count) + label + } + + /// Creates a Unicode bar that’s `width` wide, and `fraction` of it filled in. + static func bar(fraction: Double, width: Int) -> String { + // Clamp so a non-positive width (e.g. from a very long label) yields an + // empty bar rather than trapping on an invalid `Range`. + let width = Swift.max(0, width) + let chars = (0.. Character in + let lower = Double(index) / Double(width) + let blockWidth = 1.0 / Double(width) + let fill = (fraction - lower) / blockWidth + let index = Swift.max(0, Swift.min(8, Int(round(fill * 8)))) + return blocks[index] + } + return String(chars) + } +} + +private let blocks: [Character] = [ + " ", + "▏", + "▎", + "▍", + "▌", + "▋", + "▊", + "▉", + "█", +] + +// MARK: - + +extension Locale { + static let posix = Locale(identifier: "en_US_POSIX") +} + +private func formatFraction(_ fraction: Double) -> String { + formatter.string(for: fraction)! +} + +private let formatter: NumberFormatter = { + var f = NumberFormatter() + f.numberStyle = .percent + f.minimumSignificantDigits = 1 + f.maximumSignificantDigits = 3 + f.locale = .posix + return f +}() diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bin.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bin.swift new file mode 100644 index 00000000..79c184c3 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Bin.swift @@ -0,0 +1,95 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +// `round`/`floor`/`log10`/`pow` are not part of `FoundationEssentials`. +import Foundation + +struct Histogram: Equatable, Encodable { + var bins: [Bin] + var totalCount: Int + + struct Bin: Equatable, Encodable { + var range: Range + var count: Int + } +} + +extension Histogram { + init?(data: [Double]) { + guard let h = Histogram.withEmptyBins(data: data) else { return nil } + self = h + data.forEach { value in + guard let index = bins.firstIndex(where: { $0.range.contains(value) }) else { return } + bins[index].count += 1 + } + } + + static func withEmptyBins(data: [Double]) -> Histogram? { + guard let ranges = binRanges(data: data) else { return nil } + return Histogram( + bins: ranges.map { + Histogram.Bin(range: $0, count: 0) + }, + totalCount: data.count + ) + } +} + +// MARK: - + +func binRanges(data: [Double]) -> [Range]? { + guard + let mean = data.mean(), + let standardDeviation = data.standardDeviation() + else { return nil } + // We want to span approx. ±2σ + // -- but less if the data doesn’t span that interval: + let lower = max( + data.reduce(into: Double.infinity) { + $0 = min($0, $1) + }, + mean - 2 * standardDeviation + ) + let upper = min( + data.reduce(into: -Double.infinity) { + $0 = max($0, $1) + }, + mean + 2 * standardDeviation + ) + guard lower < upper else { return nil } + // Calculate the bins with “rounded” sizes: + let bins = -3..<3 + let binSpan = roundedBinSpan((upper - lower) / Double(bins.count)) + let middle = roundedBinSpan(lower + 0.5 * (upper - lower)) + return bins.map { + let lower = middle + Double($0) * binSpan + let upper = lower + binSpan + return lower.. Double { + // `log10`/`pow` are only meaningful for a positive magnitude. Guard against zero + // and non-finite input (which would otherwise yield NaN), and round the magnitude + // for negative input so the result keeps `input`’s sign. + guard input.isFinite, input != 0 else { return 0 } + let magnitude = abs(input) + let scale = pow(10, floor(log10(magnitude))) + let a = magnitude / scale + let x: Double = 5 + let b = round(a * x) / x + let rounded = b * scale + return input < 0 ? -rounded : rounded +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Histogram.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Histogram.swift new file mode 100644 index 00000000..cc959e8c --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Histogram.swift @@ -0,0 +1,89 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +// `NumberFormatter` is not part of `FoundationEssentials`. +import Foundation + +/// A text-based histogram suitable for terminal output. +struct TextHistogram: Equatable, Encodable, TextOutputEncodable { + let underlying: Histogram + let lines: [String] + + /// Encodes the underlying histogram data. + func encode(to encoder: Encoder) throws { + try self.underlying.encode(to: encoder) + } + + /// The single-line text representation. + var textOutput: String { "" } + /// The multi-line text representation. + var textOutputLines: [String] { self.lines } +} + +extension TextHistogram { + /// Creates a histogram from duration values, or returns `nil` if the data is insufficient. + init?(durations: [TimeInterval], width: Int = 78) { + guard let histogram = Histogram(data: durations) else { return nil } + let lines = histogram.makeDurationLines(width: width) + self.init(underlying: histogram, lines: lines) + } +} + +// MARK: - + +extension Histogram { + func makeDurationLines(width: Int) -> [String] { + let binsAndLabels: [(Histogram.Bin, String)] = bins.map { bin -> (Histogram.Bin, String) in + let label = formatDuration(bin.range.lowerBound) + "-" + formatDuration(bin.range.upperBound) + return (bin, label) + } + let maxLabelWidth = binsAndLabels.reduce(into: 0) { $0 = max($0, $1.1.count) } + + let lines: [String] = binsAndLabels.map { bin, label -> String in + let fraction = Double(bin.count) / Double(totalCount) + // Guard against very long labels driving the bar width non-positive. + let barWidth = max(1, width - maxLabelWidth - 2) + let bar = String.barWithLabel(fraction: fraction, width: barWidth) + return label + String(repeating: " ", count: maxLabelWidth - label.count) + ": " + bar + } + return lines + } +} + +// MARK: - + +func formatDuration(_ value: TimeInterval) -> String { + guard value >= 10 else { + return numberFormatter.string(for: value * 1000)! + "ms" + } + return numberFormatter.string(for: value)! + "s" +} + +private let numberFormatter: NumberFormatter = { + var f = NumberFormatter() + f.numberStyle = .decimal + f.minimumSignificantDigits = 1 + f.maximumSignificantDigits = 3 + f.usesGroupingSeparator = true + f.groupingSeparator = "," + f.groupingSize = 3 + f.locale = .posix + return f +}() + +private let calendar: Calendar = { + var c = Calendar(identifier: .gregorian) + c.locale = .posix + return c +}() diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Output.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Output.swift new file mode 100644 index 00000000..e812b595 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Output.swift @@ -0,0 +1,202 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +// `NumberFormatter` is not part of `FoundationEssentials`. +import Foundation +import NIOIMAP +import IMAPCommands +import SystemPackage + +/// A formatted output value that supports custom string interpolations. +public struct Output: Equatable { + var text: String +} + +/// Using `Output`, the tool can use different string interpolations than the default +/// `String` interpolations. +extension Output: ExpressibleByStringLiteral { + public init(stringLiteral value: String) { + self.init(text: value) + } +} + +extension Output: ExpressibleByStringInterpolation { + public init(stringInterpolation: StringInterpolation) { + self.text = stringInterpolation.text + } + + public struct StringInterpolation: StringInterpolationProtocol { + var text: String + + public init(literalCapacity: Int, interpolationCount: Int) { + self.text = "" + self.text.reserveCapacity(literalCapacity + interpolationCount * 10) + } + } +} + +extension Output.StringInterpolation { + public mutating func appendLiteral(_ literal: String) { + self.text.append(literal) + } + + public mutating func appendInterpolation(_ value: String) { + self.text.append(value) + } + + public mutating func appendInterpolation(_ value: Command) { + self.text.append(String(reflecting: value)) + } + + public mutating func appendInterpolation(_ duration: TimeInterval) { + let ms = duration * 1000 + self.text.append(integerFormatter.string(for: ms)! + " ms") + } + + public mutating func appendInterpolation(_ duration: Duration) { + self.appendInterpolation(TimeInterval(duration)) + } + + public mutating func appendInterpolation(_ path: MailboxPath) { + let text = + path + .displayStringComponents(omittingEmptySubsequences: false) + .joined(separator: path.pathSeparator.map { String($0) } ?? "/") + self.text.append(text) + } + + public mutating func appendInterpolation(_ name: MailboxName) { + guard let path = try? MailboxPath(name: name, pathSeparator: nil) else { return } + self.appendInterpolation(path) + } + + public mutating func appendInterpolation(_ value: UID) { + self.text.append("\(UInt32(value))") + } + + public mutating func appendInterpolation(_ value: SearchKey) { + self.text.append("\(String(reflecting: value))") + } + + public mutating func appendInterpolation(_ value: MessageID) { + self.text.append("\(String(value))") + } + + public mutating func appendInterpolation(_ value: UIDSet) { + self.text.append(String(reflecting: value)) + } + + public mutating func appendInterpolation(_ value: UIDValidity) { + self.text.append("\(UInt32(value))") + } + + public mutating func appendInterpolation(_ value: UIDSetNonEmpty) { + self.text.append("\(String(reflecting: value.set))") + } + + public mutating func appendInterpolation(_ value: IMAPConnection.Tag) { + self.text.append(String(value)) + } + + public mutating func appendInterpolation(_ value: ResponseText) { + if let code = value.code { + self.appendInterpolation(code) + self.appendLiteral(" ") + } + self.text.append(value.text) + } + + public mutating func appendInterpolation(_ range: NIOIMAP.PartialRange) { + switch range { + case .first(let r): + self.appendLiteral("first-") + self.appendInterpolation(r) + case .last(let r): + self.appendLiteral("last-") + self.appendInterpolation(r) + } + } + + public mutating func appendInterpolation(_ range: MessageIdentifierRange) { + self.text.append(String(reflecting: range)) + } + + public mutating func appendInterpolation(_ code: ResponseTextCode) { + self.text.append(String(reflecting: code)) + } + + public mutating func appendInterpolation(_ state: TaggedResponse.State) { + self.text.append(String(reflecting: state)) + } + + public mutating func appendInterpolation(_ status: UntaggedStatus) { + self.text.append(String(reflecting: Response.untagged(.conditionalState(status)))) + } + + public mutating func appendInterpolation(_ status: Bool) { + self.text.append(status ? "true" : "false") + } + + public mutating func appendInterpolation(_ value: Int) { + self.text.append(integerFormatter.string(for: value)!) + } + + public mutating func appendInterpolation(_ value: CInt) { + self.text.append(integerFormatter.string(for: value)!) + } + + public mutating func appendInterpolation(_ value: FilePath) { + self.text.append(String(decoding: value)) + } + + public mutating func appendInterpolation(_ value: FilePath.Component) { + self.text.append(String(decoding: value)) + } + + public mutating func appendInterpolation(_ error: some Swift.Error) { + switch error { + case let e as LocalizedError: + self.text.append(e.errorDescription ?? "\(e)") + default: + self.text.append("\(error)") + } + } +} + +extension TimeInterval { + /// The duration expressed as a number of seconds. + fileprivate init(_ duration: Duration) { + let components = duration.components + self = Double(components.seconds) + Double(components.attoseconds) * 1e-18 + } +} + +private let integerFormatter: NumberFormatter = { + var f = NumberFormatter() + f.locale = Locale(identifier: "en_US_POSIX") + f.numberStyle = .decimal + f.groupingSeparator = "," + f.usesGroupingSeparator = true + f.groupingSize = 3 + f.maximumFractionDigits = 0 + f.roundingMode = .halfUp + return f +}() + +extension IMAPConnection.Tag: TextOutputEncodable { + /// The text representation of the tag. + public var textOutput: String { String(self) } + /// Additional output lines (always empty for tags). + public var textOutputLines: [String] { [] } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Print.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Print.swift new file mode 100644 index 00000000..3970e711 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Print.swift @@ -0,0 +1,56 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +// `FileHandle` is not part of `FoundationEssentials`. +import Foundation + +#if canImport(Glibc) +import Glibc +nonisolated(unsafe) let _exit: (Int32) -> Never = Glibc.exit +#elseif canImport(Darwin) +import Darwin +nonisolated(unsafe) let _exit: (Int32) -> Never = Darwin.exit +#elseif canImport(MSVCRT) +import MSVCRT +nonisolated(unsafe) let _exit: (Int32) -> Never = ucrt._exit +#endif + +/// Writes to standard error (`stderr`). +/// +/// This is for informational messages. It does not interfere with command output (such as JSON). +public func writeStatus(_ output: Output, terminator: String = "\n") { + let text = output.text + terminator + FileHandle.standardError.write(text.data(using: .utf8)!) +} + +/// Writes to standard output (`stdout`). +/// +/// Used for "clean" terminations such as `--help` and `--version`, whose text +/// belongs on standard output rather than standard error. +func writeStandardOutput(_ text: String) { + FileHandle.standardOutput.write(Data(text.utf8)) + _ = fsync(FileHandle.standardOutput.fileDescriptor) +} + +func flushStatus() { + // We use fsync(2) and intentionally ignore the result. This can fail depending on what kind of output (terminal vs. pipe vs. file) standard output is going to. + _ = fsync(FileHandle.standardError.fileDescriptor) +} + +/// Writes the output message to standard error and terminates the process. +public func exitWithErrorMessage(_ output: Output, code: Int32 = -1) -> Never { + writeStatus(output) + flushStatus() + _exit(code) +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/ResultFormat.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/ResultFormat.swift new file mode 100644 index 00000000..549738bb --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/ResultFormat.swift @@ -0,0 +1,89 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +// `FileHandle` is not part of `FoundationEssentials`. +import Foundation +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif + +/// The output format for command results. +public enum ResultFormat: String, Sendable { + /// Plain text output. + case text + /// JSON output. + case json +} + +extension ResultFormat: ExpressibleByArgument { + public init?(argument: String) { + self.init(rawValue: argument) + } +} + +// MARK: - + +/// Write the execution result to standard output. +/// +/// This uses the given `format` and writes either plain text or JSON. +/// Note that all other output should use `writeStatus()` and go to standard error to allow +/// piping the result to another tool. +public func writeResult( + result: R, + format: ResultFormat, + terminator: Data? = nil +) where R: Encodable { + let data: Data + do { + data = try makeResultData( + result: result, + format: format + ) + } catch { + exitWithErrorMessage("Failed to encode result '\(String(describing: result))'.") + } + + // Flush the status -- if we’re running in the terminal, both will + // go to the tty. + flushStatus() + // Write to stdout: + FileHandle.standardOutput.write(data) + if let terminator { + FileHandle.standardOutput.write(terminator) + } + // We use fsync(2) and intentionally ignore the result. This can fail depending on what kind of output (terminal vs. pipe vs. file) standard output is going to. + _ = fsync(FileHandle.standardOutput.fileDescriptor) +} + +private func makeResultData( + result: R, + format: ResultFormat +) throws -> Data where R: Encodable { + try makeResultData(result, format: format) +} + +func makeResultData(_ result: R, format: ResultFormat) throws -> Data where R: Encodable { + switch format { + case .text: + let encoder = TextEncoder() + return try encoder.encode(result).data(using: .utf8)! + case .json: + let encoder = JSONEncoder() + encoder.outputFormatting = [.sortedKeys, .prettyPrinted] + return try encoder.encode(result) + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/Statistics.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Statistics.swift new file mode 100644 index 00000000..28d3e79a --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/Statistics.swift @@ -0,0 +1,30 @@ +//===----------------------------------------------------------------------===// +// +// 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 Array where Element: FloatingPoint { + func mean() -> Element? { + guard !isEmpty else { return nil } + return self.sum() / Element(count) + } + + func sum() -> Element { + reduce(0, +) + } + + func standardDeviation() -> Element? { + guard let meanValue = mean() else { return nil } + let variance = (reduce(into: 0 as Element) { $0 += (meanValue - $1) * (meanValue - $1) }) / Element(count) + return variance.squareRoot() + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/TTY.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/TTY.swift new file mode 100644 index 00000000..de535eeb --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/TTY.swift @@ -0,0 +1,26 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif +// `FileHandle` is not part of `FoundationEssentials`. +import Foundation + +/// Returns `true` if standard input connects to an interactive terminal session. +var standardInputIsTTY: Bool { + isatty(FileHandle.standardInput.fileDescriptor) == 1 +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/TextEncoder.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/TextEncoder.swift new file mode 100644 index 00000000..95dea3ac --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/TextEncoder.swift @@ -0,0 +1,494 @@ +//===----------------------------------------------------------------------===// +// +// 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 Synchronization + +final class TextEncoder: Encoder { + init() { + self.values = Values() + } + + fileprivate init(values: Values) { + self.values = values + } + + func encode(_ value: T) throws -> String where T: Encodable { + let e = self.copy() + try value.encode(to: e) + return e.output + } + + fileprivate func copy() -> TextEncoder { + TextEncoder(values: Values(values: self.values.values)) + } + + var codingPath: [CodingKey] = [] + + var userInfo: [CodingUserInfoKey: Any] = [:] + + fileprivate let values: Values + + func container(keyedBy _: Key.Type) -> KeyedEncodingContainer where Key: CodingKey { + let c = TextKeyedEncodingContainer(codingPath: codingPath, values: values) + return KeyedEncodingContainer(c) + } + + func unkeyedContainer() -> UnkeyedEncodingContainer { + TextUnkeyedEncodingContainer(codingPath: self.codingPath, values: self.values) + } + + func singleValueContainer() -> SingleValueEncodingContainer { + TextSingleValueEncodingContainer(codingPath: self.codingPath, values: self.values) + } +} + +// MARK: Stored Values + +private struct KeyedValue { + var keyName: String + var value: Value +} + +private indirect enum Value { + case text(String) + case sub(Values) + case keyed(String, Value) +} + +private final class Values { + var values: [Value] + init(values: [Value] = []) { + self.values = values + } +} + +extension Values { + func addNestedValues() -> Values { + let nestedValues = Values() + self.values.append(.sub(nestedValues)) + return nestedValues + } + + func addNestedValues(for key: Key) -> Values { + let nestedValues = Values() + self.values.append(.keyed(key.textOutputKey, .sub(nestedValues))) + return nestedValues + } + + func add(text: String) { + self.values.append(.text(text)) + } + + func add(text: String, for key: Key) { + self.values.append(.keyed(key.textOutputKey, .text(text))) + } +} + +extension CodingKey { + fileprivate var textOutputKey: String { + // Split words by "_". Uppercase the 1st word. + stringValue + .camelCaseComponents + .filter { !$0.isEmpty } + .enumerated() + .map { ($0.0 == 0) ? $0.1.titlecased() : $0.1.lowercased() } + .joined(separator: " ") + } +} + +extension String { + fileprivate var camelCaseComponents: [Substring] { + var result: [Substring] = [] + var idx = startIndex + var lastStart: Index? + while idx < endIndex { + if self[idx].isLetter, self[idx].isUppercase { + if let s = lastStart { + result.append(self[s.. String { + let idx = index(after: startIndex) + guard idx <= endIndex else { return String(self) } + return String(self[startIndex.. 1) } + if needsSeparation { + self.appendSeparatedOutput(to: &result, indent: indent) + } else { + self.values.forEach { + $0.appendOutput(to: &result, indent: indent) + } + } + } + + private func appendSeparatedOutput(to result: inout String, indent: Int) { + var isFirst = true + self.values.forEach { + if isFirst { + isFirst = false + } else { + result.append(String.indentation(indent) + .newline) + } + $0.appendOutput(to: &result, indent: indent) + } + } +} + +extension Value { + var count: Int { + switch self { + case .text: + return 1 + case .sub(let sub): + return sub.values.count + case .keyed: return 1 + } + } + + func appendOutput(to result: inout String, indent: Int) { + switch self { + case .text(let text): + result.append(String.indentation(indent) + text + .newline) + case .sub(let sub): + sub.appendOutput(to: &result, indent: indent) // Don't indent here. + case .keyed(let key, .text(let text)): + result.append(String.indentation(indent) + key + ": " + text + .newline) + case .keyed(let key, .sub(let sub)): + if sub.values.isEmpty { + result.append(String.indentation(indent) + key + ":" + .newline) + } else if sub.values.count == 1, case .some(.text(let text)) = sub.values.first { + result.append(String.indentation(indent) + key + ": " + text + .newline) + } else if sub.values.count == 1, case .some(.sub(let subsub)) = sub.values.first { + result.append(String.indentation(indent) + key + ":" + .newline) + subsub.appendOutput(to: &result, indent: indent + 1) + } else { + result.append(String.indentation(indent) + key + ":" + .newline) + sub.appendOutput(to: &result, indent: indent + 1) + } + case .keyed(_, .keyed): + fatalError("Value.keyed must not contain sub-key.") + } + } +} + +private let indentationMemo = Mutex<[String]>([]) + +extension String { + fileprivate static func indentation(_ indent: Int) -> String { + indentationMemo.withLock { memo in + while memo.count <= indent { + memo.append(String(repeating: " ", count: memo.count * 4)) + } + return memo[indent] + } + } + + fileprivate static let newline: String = "\n" +} + +// MARK: Encoding Containers + +private struct TextKeyedEncodingContainer: KeyedEncodingContainerProtocol { + init(codingPath: [CodingKey], values: Values) { + self.codingPath = codingPath + self.values = values + } + + var codingPath: [CodingKey] + fileprivate var values: Values + + mutating func encodeNil(forKey key: Key) throws { + self.values.add(text: "", for: key) + } + + mutating func encode(_ value: T, forKey key: Key) throws where T: Encodable { + switch value { + case let v as TextOutputEncodable: + self.values.add(text: v.textOutput, for: key) + v.textOutputLines.forEach { + self.values.add(text: $0) + } + case let text as String: + self.values.add(text: text, for: key) + case let b as Bool: + self.values.add(text: b ? "true" : "false", for: key) + case let i as Double: + self.values.add(text: i.description, for: key) + case let i as Float: + self.values.add(text: i.description, for: key) + + case let i as UInt: + self.values.add(text: i.description, for: key) + case let i as Int: + self.values.add(text: i.description, for: key) + case let i as UInt8: + self.values.add(text: i.description, for: key) + case let i as Int8: + self.values.add(text: i.description, for: key) + case let i as UInt16: + self.values.add(text: i.description, for: key) + case let i as Int16: + self.values.add(text: i.description, for: key) + case let i as UInt32: + self.values.add(text: i.description, for: key) + case let i as Int32: + self.values.add(text: i.description, for: key) + case let i as UInt64: + self.values.add(text: i.description, for: key) + case let i as Int64: + self.values.add(text: i.description, for: key) + + case let i as [Double]: + self.values.add(text: i.description, for: key) + case let i as [Float]: + self.values.add(text: i.description, for: key) + + case let i as [UInt]: + self.values.add(text: i.description, for: key) + case let i as [Int]: + self.values.add(text: i.description, for: key) + case let i as [UInt8]: + self.values.add(text: i.description, for: key) + case let i as [Int8]: + self.values.add(text: i.description, for: key) + case let i as [UInt16]: + self.values.add(text: i.description, for: key) + case let i as [Int16]: + self.values.add(text: i.description, for: key) + case let i as [UInt32]: + self.values.add(text: i.description, for: key) + case let i as [Int32]: + self.values.add(text: i.description, for: key) + case let i as [UInt64]: + self.values.add(text: i.description, for: key) + case let i as [Int64]: + self.values.add(text: i.description, for: key) + + default: + let nested = self.values.addNestedValues(for: key) + let e = TextEncoder(values: nested) + e.codingPath = self.codingPath + [key] + try value.encode(to: e) + } + } + + mutating func nestedContainer( + keyedBy _: NestedKey.Type, + forKey key: Key + ) -> KeyedEncodingContainer where NestedKey: CodingKey { + let nestedPath = self.codingPath + [key] + let nestedValues = self.values.addNestedValues(for: key) + let c = TextKeyedEncodingContainer(codingPath: nestedPath, values: nestedValues) + return KeyedEncodingContainer(c) + } + + mutating func nestedUnkeyedContainer(forKey key: Key) -> UnkeyedEncodingContainer { + let nestedPath = self.codingPath + [key] + let nestedValues = self.values.addNestedValues(for: key) + return TextUnkeyedEncodingContainer(codingPath: nestedPath, values: nestedValues) + } + + mutating func superEncoder() -> Encoder { + fatalError() + } + + mutating func superEncoder(forKey _: Key) -> Encoder { + fatalError() + } +} + +/// A type that provides custom text encoding for the ``TextEncoder``. +protocol TextOutputEncodable { + /// The single-line text representation. + var textOutput: String { get } + /// Additional output lines beyond the primary text representation. + var textOutputLines: [String] { get } +} + +private struct TextUnkeyedEncodingContainer: UnkeyedEncodingContainer { + init(codingPath: [CodingKey], values: Values) { + self.codingPath = codingPath + self.values = values + } + + var codingPath: [CodingKey] + fileprivate var values: Values + + var count: Int { + values.values.count + } + + mutating func encodeNil() throws { + self.values.add(text: "") + } + + mutating func encode(_ value: T) throws where T: Encodable { + switch value { + case let v as TextOutputEncodable: + if !v.textOutput.isEmpty { + self.values.add(text: v.textOutput) + } + v.textOutputLines.forEach { + self.values.add(text: $0) + } + case let text as String: + self.values.add(text: text) + case let b as Bool: + self.values.add(text: b ? "true" : "false") + case let i as Double: + self.values.add(text: i.description) + case let i as Float: + self.values.add(text: i.description) + case let i as UInt: + self.values.add(text: i.description) + case let i as Int: + self.values.add(text: i.description) + case let i as UInt8: + self.values.add(text: i.description) + case let i as Int8: + self.values.add(text: i.description) + case let i as UInt16: + self.values.add(text: i.description) + case let i as Int16: + self.values.add(text: i.description) + case let i as UInt32: + self.values.add(text: i.description) + case let i as Int32: + self.values.add(text: i.description) + case let i as UInt64: + self.values.add(text: i.description) + case let i as Int64: + self.values.add(text: i.description) + default: + let e = TextEncoder(values: values.addNestedValues()) + e.codingPath = self.codingPath + try value.encode(to: e) + } + } + + mutating func encodeConditional(_ object: T) throws where T: AnyObject, T: Encodable { + try self.encode(object) + } + + mutating func encode(contentsOf sequence: T) throws where T: Sequence, T.Element: Encodable { + let e = TextEncoder(values: values) + e.codingPath = self.codingPath + for value in sequence { + try value.encode(to: e) + } + } + + mutating func nestedContainer(keyedBy _: NestedKey.Type) -> KeyedEncodingContainer + where NestedKey: CodingKey { + let nestedValues = self.values.addNestedValues() + let c = TextKeyedEncodingContainer(codingPath: codingPath, values: nestedValues) + return KeyedEncodingContainer(c) + } + + mutating func nestedUnkeyedContainer() -> UnkeyedEncodingContainer { + let nestedValues = self.values.addNestedValues() + return TextUnkeyedEncodingContainer(codingPath: self.codingPath, values: nestedValues) + } + + mutating func superEncoder() -> Encoder { + fatalError() + } +} + +private struct TextSingleValueEncodingContainer: SingleValueEncodingContainer { + init(codingPath: [CodingKey], values: Values) { + self.codingPath = codingPath + self.values = values + } + + var codingPath: [CodingKey] + fileprivate var values: Values + + mutating func encodeNil() throws { + self.values.add(text: "") + } + + mutating func encode(_ value: T) throws where T: Encodable { + switch value { + case let v as TextOutputEncodable: + if !v.textOutput.isEmpty { + self.values.add(text: v.textOutput) + } + v.textOutputLines.forEach { + self.values.add(text: $0) + } + case let text as String: + self.values.add(text: text) + case let b as Bool: + self.values.add(text: b ? "true" : "false") + case let i as Double: + self.values.add(text: i.description) + case let i as Float: + self.values.add(text: i.description) + case let i as UInt: + self.values.add(text: i.description) + case let i as Int: + self.values.add(text: i.description) + case let i as UInt8: + self.values.add(text: i.description) + case let i as Int8: + self.values.add(text: i.description) + case let i as UInt16: + self.values.add(text: i.description) + case let i as Int16: + self.values.add(text: i.description) + case let i as UInt32: + self.values.add(text: i.description) + case let i as Int32: + self.values.add(text: i.description) + case let i as UInt64: + self.values.add(text: i.description) + case let i as Int64: + self.values.add(text: i.description) + default: + let e = TextEncoder(values: values) + e.codingPath = self.codingPath + try value.encode(to: e) + } + } +} diff --git a/Examples/IMAPTool/Sources/IMAPToolLib/Output/ThroughputEstimator.swift b/Examples/IMAPTool/Sources/IMAPToolLib/Output/ThroughputEstimator.swift new file mode 100644 index 00000000..16250ff9 --- /dev/null +++ b/Examples/IMAPTool/Sources/IMAPToolLib/Output/ThroughputEstimator.swift @@ -0,0 +1,101 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif + +struct ThroughputEstimator { + var start: Date + var count = 0 + + init( + now: Date = Date() + ) { + self.start = now + } + + mutating func didComplete( + now: Date = Date() + ) -> Throughput? { + count += 1 + let duration = now.timeIntervalSince(start) + guard + 2 <= count, + 0 < duration, + (30 < duration) || (60 < count) + else { return nil } + let throughput = Double(count) / Double(duration) + count = 0 + start = now + return Throughput(tasksPerSecond: throughput) + } +} + +extension ThroughputEstimator { + struct Throughput { + var tasksPerSecond: Double + } +} + +extension ThroughputEstimator.Throughput { + func formattedTasksPerSecond( + fractionLength: Int = 1 + ) -> String { + tasksPerSecond.formatted( + .number.precision(.fractionLength(fractionLength)) + .locale(Locale(identifier: "en_US.posix")) + ) + } + + func formattedTimeRemaining( + remainingCount: Int, + remainingCountCutOff: Int = 0 + ) -> String? { + // Don’t create this when things are super slow. + guard + remainingCountCutOff < remainingCount, + 0.001 < tasksPerSecond + else { return nil } + + let secondsRemaining = Double(remainingCount) / tasksPerSecond + return formatCondensedDuration(seconds: secondsRemaining) + } +} + +/// Formats a duration as `1hr 2min 3s`, omitting zero components. +/// +/// `Date`’s `.components(style:fields:)` format style is Darwin-only, and this is +/// user-visible output, so it is spelled out by hand. +func formatCondensedDuration(seconds: Double) -> String { + // Anything non-finite (or negative) has no sensible representation. + guard seconds.isFinite, 0 < seconds else { return "0sec" } + // Clamp rather than trap when converting to an integer. + guard seconds < Double(Int.max) else { return "0sec" } + // Truncate towards zero, matching the format style this replaces. + let total = Int(seconds) + let components = [ + (total / 3600, "hr"), + ((total % 3600) / 60, "min"), + (total % 60, "sec"), + ] + let parts = + components + .filter { value, _ in value != 0 } + .map { value, unit in "\(value)\(unit)" } + guard !parts.isEmpty else { return "0sec" } + return parts.joined(separator: " ") +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ArgumentParsingTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ArgumentParsingTests.swift new file mode 100644 index 00000000..e0fd290a --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ArgumentParsingTests.swift @@ -0,0 +1,396 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +@testable import IMAPCommands +import Foundation +import NIO +import NIOIMAP +import Testing + +@Suite("Argument Parsing") +enum ArgumentParsingTests { + static func parse( + _: A.Type, + _ arguments: [String], + sourceLocation: SourceLocation = #_sourceLocation + ) throws -> A where A: ParsableCommand { + let root = try RootCommand.parseAsRoot(arguments) + return try #require(root as? A, sourceLocation: sourceLocation) + } + + @Test + static func parseIdentifyCommand() throws { + let id = try parse( + IdentifyCommand.self, + [ + "id", + "--sasl", "plain:foo bar", + "--server", "bar.example.com", + ] + ) + #expect(id.connectionInfo.username == nil) + #expect(id.connectionInfo.sasl == "plain:foo bar") + #expect(id.connectionInfo.disableSASLIR == false) + #expect(id.connectionInfo.server == "bar.example.com") + #expect(id.outputFormat == .text) + } + + @Test + static func parseAppendCommand() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "foo.eml", + "baz/bar.eml", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.sasl == nil) + #expect(sut.connectionInfo.disableSASLIR == false) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.input == ["foo.eml", "baz/bar.eml"]) + #expect(sut.outputFormat == .text) + } + + @Test + static func parseDeleteMessagesCommand() throws { + let sut = try parse( + DeleteMessagesCommand.self, + [ + "delete-messages", + "--username", "foo:bar", + "--server", "bar.example.com", + "--messages", "foo.json", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.sasl == nil) + #expect(sut.connectionInfo.disableSASLIR == false) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.action == .deleteSpecific(filePath: "foo.json")) + #expect(sut.mailboxName == .inbox) + #expect(sut.outputFormat == .text) + } + + @Test + static func parseDeleteMessagesCommand_2() throws { + let sut = try parse( + DeleteMessagesCommand.self, + [ + "delete-messages", + "--username", "foo:bar", + "--server", "bar.example.com", + "--messages", "foo.json", + "--mailbox", "work", + "--output-format", "json", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.sasl == nil) + #expect(sut.connectionInfo.disableSASLIR == false) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.action == .deleteSpecific(filePath: "foo.json")) + #expect(sut.mailboxName.debugDescription == "work") + #expect(sut.outputFormat == .json) + } + + @Test + static func parseDeleteMessagesCommand_3() throws { + let sut = try parse( + DeleteMessagesCommand.self, + [ + "delete-messages", + "--username", "foo:bar", + "--server", "bar.example.com", + "--all", + "--mailbox", "work", + "--output-format", "json", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.sasl == nil) + #expect(sut.connectionInfo.disableSASLIR == false) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.action == .deleteAll) + #expect(sut.mailboxName.debugDescription == "work") + #expect(sut.outputFormat == .json) + } + + @Test + static func parseDeleteMessagesCommand_4() throws { + let sut = try parse( + DeleteMessagesCommand.self, + [ + "delete-messages", + "--username", "foo:bar", + "--server", "bar.example.com", + "--all", + "--messages", "foo.json", + "--mailbox", "work", + "--output-format", "json", + ] + ) + #expect(sut.action == .fail("Can not specify both --all and a file to read message info from.")) + } + + @Test + static func parseDeleteMessagesCommand_5() throws { + let sut = try parse( + DeleteMessagesCommand.self, + [ + "delete-messages", + "--username", "foo:bar", + "--server", "bar.example.com", + "--mailbox", "work", + "--output-format", "json", + ] + ) + #expect(sut.action == .fail("Need to specify a file to read message info from.")) + } + + @Test + static func parseAppendCommand_1() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "a", + "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.appendOptions == [.skipErrors, .sort]) + #expect(sut.input == ["a", "b"]) + } + + @Test + static func parseAppendCommand_2() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "--sort-by-date", + "--skip-unreadable", + "a", + "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.appendOptions == [.skipErrors, .sort]) + #expect(sut.input == ["a", "b"]) + } + + @Test + static func parseAppendCommand_3() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "--no-sort-by-date", + "--create-mailbox", + "a", + "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.appendOptions == [.skipErrors, .createMailbox([])]) + #expect(sut.input == ["a", "b"]) + } + + @Test + static func parseAppendCommand_4() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "--no-skip-unreadable", + "a", + "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.appendOptions == [.sort]) + #expect(sut.input == ["a", "b"]) + } + + @Test + static func parseAppendCommand_5() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "foo:bar", + "--server", "bar.example.com", + "--mailbox", "A", + "a", + "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == MailboxName(ByteBuffer(string: "A"))) + #expect(sut.appendOptions == [.skipErrors, .sort]) + #expect(sut.input == ["a", "b"]) + } + + @Test + static func parseListMailboxes_1() throws { + let sut = try parse( + MailboxCommand.List.self, + [ + "mailboxes", + "list", + "--username", "foo:bar", + "--server", "bar.example.com", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + } + + @Test + static func parseListMailboxes_2() throws { + let sut = try parse( + MailboxCommand.List.self, + [ + "mailbox", + "list", + "--username", "foo:bar", + "--server", "bar.example.com", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + } + + @Test + static func parseCreateMailboxes_1() throws { + let sut = try parse( + MailboxCommand.Create.self, + [ + "mailbox", + "create", + "--username", "foo:bar", + "--server", "bar.example.com", + "--name", "foo", + "--name", "bar", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.names == ["foo", "bar"]) + #expect(sut.paths == []) + } + + @Test + static func parseCreateMailboxes_2() throws { + let sut = try parse( + MailboxCommand.Create.self, + [ + "mailbox", + "create", + "--username", "foo:bar", + "--server", "bar.example.com", + "--name", "a", + "--name-json", #"path: ["foo"]"#, + "--name-json", #"{path: ["bar"]}"#, + "--name-json", #"{path: ["foo", "baz"], specialUse: "trash"}"#, + "--name-json", #"name: "qux""#, + "--name", "b", + ] + ) + #expect(sut.connectionInfo.username == "foo:bar") + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.names == ["a", "b"]) + #expect( + sut.paths == [ + .init(namePath: ["foo"]), + .init(namePath: ["bar"]), + .init(namePath: ["foo", "baz"], specialUse: .trash), + .init(namePath: ["qux"]), + ] + ) + #expect( + sut.mailboxDisplayNamesWithSpecialUse == [ + .init(namePath: ["a"], parameters: []), + .init(namePath: ["b"], parameters: []), + .init(namePath: ["foo"], parameters: []), + .init(namePath: ["bar"], parameters: []), + .init(namePath: ["foo", "baz"], parameters: [.attributes([.trash])]), + .init(namePath: ["qux"], parameters: []), + ] + ) + } + + @Test + static func seedParsing() { + #expect( + SeededRandomNumberGenerator.Seed(argument: "hex:3501_404A_0218_5150_F23C_78DA_2C09_7E04") + == SeededRandomNumberGenerator.Seed(a: 0x3501_404A_0218_5150, b: 0xF23C_78DA_2C09_7E04) + ) + } + + @Test + static func parseAppendCommand_withFlags() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "test:pass", + "--server", "imap.example.com", + "--flag", "seen", + "--flag", "flagged", + "message.eml", + ] + ) + #expect(sut.flags == [.seen, .flagged]) + #expect(sut.input == ["message.eml"]) + } + + @Test + static func parseAppendCommand_withFlags_2() throws { + let sut = try parse( + AppendCommand.self, + [ + "append", + "--username", "test:pass", + "--server", "imap.example.com", + "--flag", "answered", + "message.eml", + ] + ) + #expect(sut.flags == [.answered]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ExpressibleByArgumentTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ExpressibleByArgumentTests.swift new file mode 100644 index 00000000..3734c656 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/ExpressibleByArgumentTests.swift @@ -0,0 +1,181 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +import Foundation +import NIO +import NIOIMAP +import SystemPackage +import Testing + +private struct ArgumentFixture: Sendable { + var input: String + var expected: A? +} + +@Suite +private enum ExpressibleByArgumentTests { + @Test(arguments: [ + ArgumentFixture( + input: "", + expected: MessageID("") + ), + ArgumentFixture( + input: "foo@apple.com", + expected: MessageID("") + ), + ArgumentFixture( + input: "( + input: "foo@apple.com>", + expected: nil + ), + ArgumentFixture( + input: "", + expected: nil + ), + ArgumentFixture( + input: " ", + expected: nil + ), + ArgumentFixture( + input: "<>", + expected: nil + ), + ]) + static func messageID( + fixture: ArgumentFixture + ) { + if let expected = fixture.expected { + #expect(MessageID(argument: fixture.input) == expected) + } else { + #expect(MessageID(argument: fixture.input) == nil) + } + } + + @Test(arguments: [ + ArgumentFixture( + input: "INBOX", + expected: try? MailboxPath.makeRootMailbox(displayName: "INBOX").name + ), + ArgumentFixture( + input: "Sent", + expected: try? MailboxPath.makeRootMailbox(displayName: "Sent").name + ), + ArgumentFixture( + input: "Archive/2024", + expected: try? MailboxPath.makeRootMailbox(displayName: "Archive/2024").name + ), + ]) + static func mailboxName( + fixture: ArgumentFixture + ) { + if let expected = fixture.expected { + #expect(MailboxName(argument: fixture.input) == expected) + } else { + #expect(MailboxName(argument: fixture.input) == nil) + } + } + + @Test(arguments: [ + ArgumentFixture( + input: "/path/to/file", + expected: FilePath("/path/to/file") + ), + ArgumentFixture( + input: "relative/path", + expected: FilePath("relative/path") + ), + ArgumentFixture( + input: "", + expected: FilePath("") + ), + ]) + static func filePath( + fixture: ArgumentFixture + ) { + if let expected = fixture.expected { + #expect(FilePath(argument: fixture.input) == expected) + } else { + #expect(FilePath(argument: fixture.input) == nil) + } + } + + @Test(arguments: [ + ArgumentFixture( + input: "1", + expected: UID(exactly: 1) + ), + ArgumentFixture( + input: "42", + expected: UID(exactly: 42) + ), + ArgumentFixture( + input: "4294967295", + expected: UID(exactly: 4_294_967_295) + ), + ArgumentFixture( + input: "0", + expected: nil + ), + ArgumentFixture( + input: "-1", + expected: nil + ), + ArgumentFixture( + input: "abc", + expected: nil + ), + ArgumentFixture( + input: "4294967296", + expected: nil + ), + ]) + static func uid( + fixture: ArgumentFixture + ) { + if let expected = fixture.expected { + #expect(UID(argument: fixture.input) == expected) + } else { + #expect(UID(argument: fixture.input) == nil) + } + } + + @Test(arguments: [ + ArgumentFixture(input: "1e", expected: .recordSeparator), + ArgumentFixture(input: "rs", expected: .recordSeparator), + ArgumentFixture(input: "recordSeparator", expected: .recordSeparator), + ArgumentFixture(input: "json-seq", expected: .recordSeparator), + ArgumentFixture(input: "0a", expected: .lineFeed), + ArgumentFixture(input: "lf", expected: .lineFeed), + ArgumentFixture(input: "linefeed", expected: .lineFeed), + // Case-insensitive: these used to fail because the labels were mixed-case. + ArgumentFixture(input: "lineFeed", expected: .lineFeed), + ArgumentFixture(input: "LINEFEED", expected: .lineFeed), + ArgumentFixture(input: "0d", expected: .carriageReturn), + ArgumentFixture(input: "cr", expected: .carriageReturn), + ArgumentFixture(input: "carriageReturn", expected: .carriageReturn), + ArgumentFixture(input: "carriagereturn", expected: .carriageReturn), + ArgumentFixture(input: "", expected: nil), + ArgumentFixture(input: "nope", expected: nil), + ]) + static func recordSeparator( + fixture: ArgumentFixture + ) { + #expect(RecordSeparator(argument: fixture.input) == fixture.expected) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MailboxCommandTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MailboxCommandTests.swift new file mode 100644 index 00000000..2d11f153 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MailboxCommandTests.swift @@ -0,0 +1,288 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +@testable import IMAPCommands +import Foundation +import NIO +import NIOIMAP +import Testing + +private enum MailboxCommandTests { + static func parseDelete( + _ arguments: [String], + sourceLocation: SourceLocation = #_sourceLocation + ) throws -> MailboxCommand.Delete { + try ArgumentParsingTests.parse( + MailboxCommand.Delete.self, + arguments, + sourceLocation: sourceLocation + ) + } + + static func parseRename( + _ arguments: [String], + sourceLocation: SourceLocation = #_sourceLocation + ) throws -> MailboxCommand.Rename { + try ArgumentParsingTests.parse( + MailboxCommand.Rename.self, + arguments, + sourceLocation: sourceLocation + ) + } + + // MARK: - Delete Command Argument Parsing Tests + + @Test + static func parseDeleteCommand_singleMailbox() throws { + let sut = try parseDelete([ + "mailbox", + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "TestFolder", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.connectionInfo.sasl == "plain:foo bar") + #expect(sut.names == ["TestFolder"]) + #expect(sut.outputFormat == .text) + } + + @Test + static func parseDeleteCommand_multipleMailboxes() throws { + let sut = try parseDelete([ + "mailbox", + "delete", + "--username", "user:pass", + "--server", "mail.example.com", + "OldFolder1", + "OldFolder2", + "TempFolder", + ]) + + #expect(sut.connectionInfo.server == "mail.example.com") + #expect(sut.connectionInfo.username == "user:pass") + #expect( + sut.names == [ + "OldFolder1", + "OldFolder2", + "TempFolder", + ] + ) + #expect(sut.outputFormat == .text) + } + + @Test + static func parseDeleteCommand_withOutputFormat() throws { + let sut = try parseDelete([ + "mailbox", + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "TestFolder", + "--output-format", "json", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.names == ["TestFolder"]) + #expect(sut.outputFormat == .json) + } + + @Test + static func parseDeleteCommand_nestedMailboxNames() throws { + let sut = try parseDelete([ + "mailbox", + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "INBOX.Work.OldProject", + "INBOX.Archives.2023", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect( + sut.names == [ + "INBOX.Work.OldProject", + "INBOX.Archives.2023", + ] + ) + } + + @Test + static func parseDeleteCommand_validation_noNames() throws { + #expect( + performing: { + _ = try parseDelete([ + "mailbox", + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + ]) + }, + throws: { + #expect( + RootCommand.fullMessage(for: $0).prefix(while: { !$0.isNewline }) + == "Error: Must specify at least one mailbox" + ) + return true + } + ) + } + + // MARK: - Rename Command Argument Parsing Tests + + @Test + static func parseRenameCommand_basic() throws { + let sut = try parseRename([ + "mailbox", + "rename", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "--old-name", "OldFolder", + "--new-name", "NewFolder", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.connectionInfo.sasl == "plain:foo bar") + #expect(sut.oldName == "OldFolder") + #expect(sut.newName == "NewFolder") + #expect(sut.outputFormat == .text) + } + + @Test + static func parseRenameCommand_withOutputFormat() throws { + let sut = try parseRename([ + "mailbox", + "rename", + "--username", "user:pass", + "--server", "mail.example.com", + "--old-name", "OldName", + "--new-name", "NewName", + "--output-format", "json", + ]) + + #expect(sut.connectionInfo.server == "mail.example.com") + #expect(sut.connectionInfo.username == "user:pass") + #expect(sut.oldName == "OldName") + #expect(sut.newName == "NewName") + #expect(sut.outputFormat == .json) + } + + @Test + static func parseRenameCommand_nestedMailboxNames() throws { + let sut = try parseRename([ + "mailbox", + "rename", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "--old-name", "INBOX.Work.Project1", + "--new-name", "INBOX.Archives.CompletedProject1", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.oldName == "INBOX.Work.Project1") + #expect(sut.newName == "INBOX.Archives.CompletedProject1") + } + + @Test + static func parseRenameCommand_allConnectionOptions() throws { + let sut = try parseRename([ + "mailbox", + "rename", + "--username", "testuser:testpass", + "--server", "imap.example.com:143", + "--old-name", "OldFolder", + "--new-name", "NewFolder", + ]) + + #expect(sut.connectionInfo.username == "testuser:testpass") + #expect(sut.connectionInfo.server == "imap.example.com:143") + #expect(sut.oldName == "OldFolder") + #expect(sut.newName == "NewFolder") + } + + // MARK: - Command Alias Tests + + @Test + static func parseDeleteCommand_usingMailboxAlias() throws { + let sut = try parseDelete([ + "mailboxes", // Using alias instead of "mailbox" + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "TestFolder", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.names == ["TestFolder"]) + } + + @Test + static func parseRenameCommand_usingMaildirAlias() throws { + let sut = try parseRename([ + "maildir", // Using alias instead of "mailbox" + "rename", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "--old-name", "OldFolder", + "--new-name", "NewFolder", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.oldName == "OldFolder") + #expect(sut.newName == "NewFolder") + } + + // MARK: - Validation Tests + + @Test + static func parseDeleteCommand_duplicateNames() throws { + #expect( + performing: { + _ = try parseDelete([ + "mailbox", + "delete", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "TestFolder", + "TestFolder", + "OtherFolder", + ]) + }, + throws: { + #expect( + RootCommand.fullMessage(for: $0).prefix(while: { !$0.isNewline }) + == "Error: Duplicate mailbox name 'TestFolder'" + ) + return true + } + ) + } + + @Test + static func parseRenameCommand_sameSourceAndTarget() throws { + // This shouldn’t throw. Server might return an error + // at run-time, though. + _ = try parseRename([ + "mailbox", + "rename", + "--sasl", "plain:foo bar", + "--server", "imap.example.com", + "--old-name", "SameFolder", + "--new-name", "SameFolder", + ]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagCommandTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagCommandTests.swift new file mode 100644 index 00000000..3d3fd514 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagCommandTests.swift @@ -0,0 +1,306 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +@testable import IMAPCommands +import Foundation +import NIO +import NIOIMAP +import Testing + +private enum MessageFlagCommandTests { + static func parse( + _ arguments: [String], + sourceLocation: SourceLocation = #_sourceLocation + ) throws -> MessageFlagCommand { + try ArgumentParsingTests.parse( + MessageFlagCommand.self, + arguments, + sourceLocation: sourceLocation + ) + } + + @Test + static func parseFlagsCommand_withUID() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "bar.example.com", + "--mailbox", "INBOX", + "--uid", "123", + "--flag", "seen", + "--flag", "flagged", + ]) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.uids == [123]) + #expect(sut.messages == nil) + #expect(sut.setFlags == [.seen, .flagged]) + } + + @Test + static func parseFlagsCommand_withMessages() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "bar.example.com", + "--mailbox", "INBOX", + "--flag", "seen", + "--flag", "flagged", + "--messages", "messages.json", + ]) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.mailbox == .inbox) + #expect(sut.uids == []) + #expect(sut.messages == "messages.json") + #expect(sut.setFlags == [.seen, .flagged]) + } + + @Test + static func parseFlagsCommand_validation_noFlags() throws { + // This should actually be valid - you can specify UIDs without flags + // if you want to just select the messages (though not very useful) + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "bar.example.com", + "--uid", "123", + // No flags specified - this is technically valid + ]) + #expect(sut.setFlags == []) + #expect(sut.unsetFlags == []) + #expect(sut.uids == [123]) + #expect(sut.messageIDs == []) + } + + @Test + static func parseFlagsCommand_multipleUIDs() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--uid", "456", + "--uid", "789", + "--flag", "seen", + ]) + #expect(sut.uids == [123, 456, 789]) + #expect(sut.messageIDs == []) + #expect(sut.setFlags == [.seen]) + #expect(sut.unsetFlags == []) + } + + @Test + static func parseFlagsCommand_singleMessageID() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--message-id", "foo@mail.example.com", + "--flag", "seen", + ]) + #expect(sut.uids == []) + #expect(sut.messageIDs == [""]) + #expect(sut.setFlags == [.seen]) + #expect(sut.unsetFlags == []) + } + + @Test + static func parseFlagsCommand_messageIDsAndUID() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--message-id", "foo@mail.example.com", + "--uid", "123", + "--flag", "seen", + ]) + #expect(sut.uids == [123]) + #expect(sut.messageIDs == [""]) + #expect(sut.setFlags == [.seen]) + #expect(sut.unsetFlags == []) + } + + @Test + static func parseFlagsCommand_multipleMessageIDs() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--message-id", "foo@mail.example.com", + "--message-id", "", + "--flag", "seen", + ]) + #expect(sut.uids == []) + #expect(sut.messageIDs == ["", ""]) + #expect(sut.setFlags == [.seen]) + #expect(sut.unsetFlags == []) + } + + @Test + static func parseFlagsCommand_unsetFlags() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--unset", "seen", + "--unset", "flagged", + ]) + #expect(sut.setFlags == []) + #expect(sut.unsetFlags == [.seen, .flagged]) + } + + @Test + static func parseFlagsCommand_setBothSetAndUnset() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--set", "seen", + "--set", "draft", + "--remove", "flagged", + "--remove", "deleted", + ]) + #expect(sut.setFlags == [.seen, .draft]) + #expect(sut.unsetFlags == [.flagged, .deleted]) + } + + @Test + static func parseFlagsCommand_allStandardFlags() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--flag", "answered", + "--flag", "flagged", + "--flag", "deleted", + "--flag", "seen", + "--flag", "draft", + ]) + #expect(sut.setFlags == [.answered, .flagged, .deleted, .seen, .draft]) + } + + @Test + static func parseFlagsCommand_colorFlags() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--flag", "red", + "--flag", "orange", + "--flag", "yellow", + "--flag", "green", + "--flag", "blue", + "--flag", "purple", + "--flag", "gray", + ]) + #expect(sut.setFlags == [.red, .orange, .yellow, .green, .blue, .purple, .gray]) + } + + @Test + static func parseFlagsCommand_customMailbox() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--mailbox", "Sent", + "--uid", "123", + "--flag", "seen", + ]) + #expect(sut.mailbox == "Sent") + #expect(sut.uids == [123]) + #expect(sut.setFlags == [.seen]) + } + + @Test + static func parseFlagsCommand_outputFormat() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--flag", "seen", + "--output-format", "json", + ]) + #expect(sut.outputFormat == .json) + } + + @Test + static func parseFlagsCommand_aliasCommand() throws { + let sut = try parse([ + "flag", // Using the alias instead of "flags" + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--flag", "seen", + ]) + #expect(sut.uids == [123]) + #expect(sut.setFlags == [.seen]) + } + + @Test + static func parseFlagsCommand_longFormOptions() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--set", "seen", // Using --set instead of --flag + "--remove", "flagged", // Using --remove instead of --unset + ]) + #expect(sut.setFlags == [.seen]) + #expect(sut.unsetFlags == [.flagged]) + } + + @Test + static func parseFlagsCommand_validation_bothUIDsAndMessages() throws { + // This should be valid - having both UIDs and messages file is allowed + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--messages", "messages.json", + "--flag", "seen", + ]) + #expect(sut.uids == [123]) + #expect(sut.messages == "messages.json") + #expect(sut.setFlags == [.seen]) + } + + @Test + static func parseFlagsCommand_flagChangesConversion() throws { + let sut = try parse([ + "flags", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--uid", "123", + "--set", "seen", + "--set", "flagged", + "--unset", "deleted", + "--unset", "draft", + ]) + + let flagChanges = sut.imapFlags + + // Test that the conversion works correctly + #expect(flagChanges.set == [.flagged, .seen]) + #expect(flagChanges.unset == [.deleted, .draft]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagTests.swift new file mode 100644 index 00000000..e17eb9ed --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MessageFlagTests.swift @@ -0,0 +1,290 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Foundation +import NIOIMAP +import Testing +import ArgumentParser + +extension NIOIMAP.Flag { + static var mailFlagBit0: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit0") } + static var mailFlagBit1: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit1") } + static var mailFlagBit2: NIOIMAP.Flag { NIOIMAP.Flag("$MailFlagBit2") } +} + +@Suite +private enum MessageFlagTests { + struct FlagsToSetFixture: Hashable, CustomTestStringConvertible { + var input: String + var expected: Set? + + var testDescription: String { input } + } + + @Test(arguments: [ + // Standard IMAP flags + FlagsToSetFixture( + input: "answered", + expected: [.answered] + ), + FlagsToSetFixture( + input: "flagged", + expected: [.flagged] + ), + FlagsToSetFixture( + input: "deleted", + expected: [.deleted] + ), + FlagsToSetFixture( + input: "seen", + expected: [.seen] + ), + FlagsToSetFixture( + input: "draft", + expected: [.draft] + ), + + // Color flags (use mail flag bits) + FlagsToSetFixture( + input: "red", + expected: [.flagged] + ), + FlagsToSetFixture( + input: "orange", + expected: [.flagged, .mailFlagBit0] + ), + FlagsToSetFixture( + input: "yellow", + expected: [.flagged, .mailFlagBit1] + ), + FlagsToSetFixture( + input: "green", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "blue", + expected: [.flagged, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "purple", + expected: [.flagged, .mailFlagBit0, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "gray", + expected: [.flagged, .mailFlagBit1, .mailFlagBit2] + ), + + // Invalid inputs (should return nil) + FlagsToSetFixture( + input: "invalid", + expected: nil + ), + FlagsToSetFixture( + input: "ANSWERED", // case sensitive + expected: nil + ), + FlagsToSetFixture( + input: "", + expected: nil + ), + FlagsToSetFixture( + input: "unseen", // not a valid flag + expected: nil + ), + FlagsToSetFixture( + input: "flag", // partial match + expected: nil + ), + ]) + static func flagsToSet( + fixture: FlagsToSetFixture + ) throws { + let parsed = MessageFlag(argument: fixture.input) + if let expected = fixture.expected { + let p = try #require(parsed) + #expect(p.flagsToSet == expected) + } else { + #expect(parsed == nil) + } + } + + @Test(arguments: [ + // Standard IMAP flags (unset themselves) + FlagsToSetFixture( + input: "answered", + expected: [.answered] + ), + FlagsToSetFixture( + input: "flagged", + expected: [.flagged] + ), + FlagsToSetFixture( + input: "deleted", + expected: [.deleted] + ), + FlagsToSetFixture( + input: "seen", + expected: [.seen] + ), + FlagsToSetFixture( + input: "draft", + expected: [.draft] + ), + + // Color flags (unset all color flags) + FlagsToSetFixture( + input: "red", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "orange", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "yellow", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "green", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "blue", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "purple", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSetFixture( + input: "gray", + expected: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + + // Invalid inputs (should return nil) + FlagsToSetFixture( + input: "invalid", + expected: nil + ), + FlagsToSetFixture( + input: "ANSWERED", // case sensitive + expected: nil + ), + FlagsToSetFixture( + input: "", + expected: nil + ), + FlagsToSetFixture( + input: "unseen", // not a valid flag + expected: nil + ), + FlagsToSetFixture( + input: "flag", // partial match + expected: nil + ), + ]) + static func flagsToUnset( + fixture: FlagsToSetFixture + ) throws { + let parsed = MessageFlag(argument: fixture.input) + if let expected = fixture.expected { + let p = try #require(parsed) + #expect(p.flagsToUnset == expected) + } else { + #expect(parsed == nil) + } + } + + struct FlagsToSearchFixture: Hashable, CustomTestStringConvertible { + var flag: MessageFlag + var expectedSet: Set + var expectedNotSet: Set + + var testDescription: String { flag.rawValue } + } + + @Test(arguments: [ + // Standard IMAP flags (set the flag, notSet is empty) + FlagsToSearchFixture( + flag: .answered, + expectedSet: [.answered], + expectedNotSet: [] + ), + FlagsToSearchFixture( + flag: .flagged, + expectedSet: [.flagged], + expectedNotSet: [] + ), + FlagsToSearchFixture( + flag: .deleted, + expectedSet: [.deleted], + expectedNotSet: [] + ), + FlagsToSearchFixture( + flag: .seen, + expectedSet: [.seen], + expectedNotSet: [] + ), + FlagsToSearchFixture( + flag: .draft, + expectedSet: [.draft], + expectedNotSet: [] + ), + + // Color flags (set flagged + specific bits, notSet contains other bits) + FlagsToSearchFixture( + flag: .red, + expectedSet: [.flagged], + expectedNotSet: [.mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ), + FlagsToSearchFixture( + flag: .orange, + expectedSet: [.flagged, .mailFlagBit0], + expectedNotSet: [.mailFlagBit1, .mailFlagBit2] + ), + FlagsToSearchFixture( + flag: .yellow, + expectedSet: [.flagged, .mailFlagBit1], + expectedNotSet: [.mailFlagBit0, .mailFlagBit2] + ), + FlagsToSearchFixture( + flag: .green, + expectedSet: [.flagged, .mailFlagBit0, .mailFlagBit1, .mailFlagBit2], + expectedNotSet: [] + ), + FlagsToSearchFixture( + flag: .blue, + expectedSet: [.flagged, .mailFlagBit2], + expectedNotSet: [.mailFlagBit0, .mailFlagBit1] + ), + FlagsToSearchFixture( + flag: .purple, + expectedSet: [.flagged, .mailFlagBit0, .mailFlagBit2], + expectedNotSet: [.mailFlagBit1] + ), + FlagsToSearchFixture( + flag: .gray, + expectedSet: [.flagged, .mailFlagBit1, .mailFlagBit2], + expectedNotSet: [.mailFlagBit0] + ), + ]) + static func flagsToSearch( + fixture: FlagsToSearchFixture + ) throws { + let result = fixture.flag.flagsToSearch + #expect(result.set == fixture.expectedSet) + #expect(result.notSet == fixture.expectedNotSet) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MoveMessageCommandTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MoveMessageCommandTests.swift new file mode 100644 index 00000000..78dfcc66 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/MoveMessageCommandTests.swift @@ -0,0 +1,201 @@ +//===----------------------------------------------------------------------===// +// +// 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 Testing +import ArgumentParser +@testable import IMAPToolLib +import NIOIMAP + +@Suite +enum MoveMessageCommandTests { + static func parse(_ arguments: [String]) throws -> MoveMessageCommand { + try ArgumentParsingTests.parse(MoveMessageCommand.self, arguments) + } + + @Test + static func parseBasicMoveCommand_withUID() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "testuser:testpass", + "--source", "INBOX", + "--destination", "Sent", + "--uid", "123", + ]) + + #expect(sut.connectionInfo.server == "imap.example.com") + #expect(sut.connectionInfo.username == "testuser:testpass") + #expect(sut.sourceMailbox == "INBOX") + #expect(sut.destinationMailbox == "Sent") + #expect(sut.uids == [123]) + #expect(sut.messageIDs == []) + #expect(sut.outputFormat == .text) + } + + @Test + static func parseMultipleUIDs() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + "--uid", "1", + "--uid", "2", + "--uid", "100", + ]) + + #expect(sut.uids == [1, 2, 100]) + #expect(sut.messageIDs == []) + } + + @Test + static func parseWithMessageID() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Trash", + "--message-id", "", + ]) + + #expect(sut.uids == []) + #expect(sut.messageIDs == [MessageID("")]) + } + + @Test + static func parseMultipleMessageIDs() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + "--message-id", "", + "--message-id", "", + "--message-id", "", + ]) + + #expect(sut.uids == []) + #expect( + sut.messageIDs == [ + MessageID(""), + MessageID(""), + MessageID(""), + ] + ) + } + + @Test + static func parseMixedUIDsAndMessageIDs() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Spam", + "--uid", "42", + "--message-id", "", + "--uid", "99", + ]) + + #expect(sut.uids == [42, 99]) + #expect(sut.messageIDs == [MessageID("")]) + } + + @Test + static func parseAlternativeMailboxNames() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--from", "INBOX", + "--to", "Sent", + "--uid", "1", + ]) + + #expect(sut.sourceMailbox == "INBOX") + #expect(sut.destinationMailbox == "Sent") + } + + @Test + static func parseWithJSONOutputFormat() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + "--uid", "1", + "--output-format", "json", + ]) + + #expect(sut.outputFormat == .json) + } + + @Test + static func parseWithMessagesFile() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + "--messages", "/path/to/messages.json", + ]) + + #expect(sut.messages == "/path/to/messages.json") + #expect(sut.uids == []) + #expect(sut.messageIDs == []) + } + + @Test + static func parseWithMessagesFileAndUIDs() throws { + let sut = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + "--messages", "/path/to/messages.json", + "--uid", "123", + ]) + + #expect(sut.messages == "/path/to/messages.json") + #expect(sut.uids == [123]) + } + + @Test + static func validationFailsWithNoMessageIdentifiers() throws { + #expect( + performing: { + _ = try parse([ + "move-message", + "--server", "imap.example.com", + "--username", "user:pass", + "--source", "INBOX", + "--destination", "Archive", + ]) + }, + throws: { + #expect( + firstLineOfErrorMessage(for: $0) + == "Error: Must specify at least one UID (--uid), Message-ID (--message-id), or a file to read from (--messages)." + ) + return true + } + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommandTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommandTests.swift new file mode 100644 index 00000000..9c658e65 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommandTests.swift @@ -0,0 +1,739 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +@testable import IMAPCommands +import Foundation +import NIO +@testable import NIOIMAPCore +import Testing + +@Suite("SearchMessagesCommand Tests") +private enum SearchMessagesCommandTests { + static func parse( + _ arguments: [String], + sourceLocation: SourceLocation = #_sourceLocation + ) throws -> SearchMessagesCommand { + try ArgumentParsingTests.parse( + SearchMessagesCommand.self, + arguments, + sourceLocation: sourceLocation + ) + } + + // MARK: - Command Argument Parsing Tests + + @Test + static func parseSearchCommand_basic() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "bar.example.com", + ]) + #expect(sut.connectionInfo.server == "bar.example.com") + #expect(sut.connectionInfo.sasl == "plain:foo bar") + #expect(sut.mailbox == .inbox) + #expect(sut.outputFormat == .text) + #expect(sut.predicate.olderThanDays == nil) + #expect(sut.predicate.newerThanDays == nil) + #expect(sut.predicate.subject == nil) + #expect(sut.predicate.fromAddress == nil) + #expect(sut.predicate.flags == []) + #expect(sut.shouldFetchMessageInfo == false) + } + + @Test + static func parseSearchCommand_customMailbox() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--mailbox", "Sent", + ]) + #expect(sut.mailbox == "Sent") + } + + @Test + static func parseSearchCommand_outputFormat() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--output-format", "json", + ]) + #expect(sut.outputFormat == .json) + } + + // MARK: - Date-based Search Parsing Tests + + @Test + static func parseSearchCommand_olderThanDays() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "30", + ]) + #expect(sut.predicate.olderThanDays == 30) + #expect(sut.predicate.newerThanDays == nil) + } + + @Test + static func parseSearchCommand_newerThanDays() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--newer-than-days", "7", + ]) + #expect(sut.predicate.newerThanDays == 7) + #expect(sut.predicate.olderThanDays == nil) + } + + @Test + static func parseSearchCommand_bothDateRanges() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "90", + "--newer-than-days", "30", + ]) + #expect(sut.predicate.olderThanDays == 90) + #expect(sut.predicate.newerThanDays == 30) + } + + @Test + static func parseSearchCommand_zeroDays() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "0", + "--newer-than-days", "0", + ]) + #expect(sut.predicate.olderThanDays == 0) + #expect(sut.predicate.newerThanDays == 0) + } + + // MARK: - Flag-based Search Parsing Tests + + @Test + static func parseSearchCommand_singleFlag() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + ]) + #expect(sut.predicate.flags == [.seen]) + } + + @Test + static func parseSearchCommand_multipleFlags() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + "--flag", "flagged", + "--flag", "answered", + ]) + #expect(sut.predicate.flags == [.seen, .flagged, .answered]) + } + + @Test + static func parseSearchCommand_allStandardFlags() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + "--flag", "flagged", + "--flag", "answered", + "--flag", "deleted", + "--flag", "draft", + ]) + #expect(sut.predicate.flags == [.seen, .flagged, .answered, .deleted, .draft]) + } + + @Test + static func parseSearchCommand_mixedCaseFlags() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + "--flag", "flagged", + "--flag", "answered", + ]) + #expect(sut.predicate.flags == [.seen, .flagged, .answered]) + } + + @Test + static func parseSearchCommand_unknownFlags() throws { + // Unknown flags should fail to parse + #expect( + performing: { + _ = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + "--flag", "nonexistent", + "--flag", "custom", + ]) + }, + throws: { _ in true } + ) + } + + // MARK: - Subject and From Search Parsing Tests + + @Test + static func parseSearchCommand_subject() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--subject", "Meeting Tomorrow", + ]) + #expect(sut.predicate.subject == "Meeting Tomorrow") + } + + @Test + static func parseSearchCommand_from() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--from", "john@example.com", + ]) + #expect(sut.predicate.fromAddress == "john@example.com") + } + + @Test + static func parseSearchCommand_subjectAndFrom() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--subject", "Important", + "--from", "boss@company.com", + ]) + #expect(sut.predicate.subject == "Important") + #expect(sut.predicate.fromAddress == "boss@company.com") + } + + @Test + static func parseSearchCommand_emptySubjectAndFrom() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--subject", "", + "--from", "", + ]) + #expect(sut.predicate.subject == "") + #expect(sut.predicate.fromAddress == "") + } + + @Test + static func parseSearchCommand_subjectWithSpaces() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--subject", "Meeting scheduled for next week", + ]) + #expect(sut.predicate.subject == "Meeting scheduled for next week") + } + + @Test + static func parseSearchCommand_fromWithDisplayName() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--from", "John Doe ", + ]) + #expect(sut.predicate.fromAddress == "John Doe ") + } + + // MARK: - Message Info Return Flag Tests + + @Test + static func parseSearchCommand_returnMessageInfo() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--fetch-message-info", + ]) + #expect(sut.shouldFetchMessageInfo == true) + } + + @Test + static func parseSearchCommand_noReturnMessageInfo() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + ]) + #expect(sut.shouldFetchMessageInfo == false) + } + + // MARK: - Combined Search Criteria Tests + + @Test + static func parseSearchCommand_allCriteria() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--mailbox", "Work", + "--older-than-days", "30", + "--newer-than-days", "7", + "--subject", "Project Update", + "--from", "manager@company.com", + "--flag", "seen", + "--flag", "flagged", + "--fetch-message-info", + "--output-format", "json", + ]) + #expect(sut.connectionInfo.server == "example.com") + #expect(sut.mailbox == "Work") + #expect(sut.predicate.olderThanDays == 30) + #expect(sut.predicate.newerThanDays == 7) + #expect(sut.predicate.subject == "Project Update") + #expect(sut.predicate.fromAddress == "manager@company.com") + #expect(sut.predicate.flags == [.seen, .flagged]) + #expect(sut.shouldFetchMessageInfo == true) + #expect(sut.outputFormat == .json) + } + + @Test + static func parseSearchCommand_multipleFlagsAndDates() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "90", + "--newer-than-days", "30", + "--flag", "seen", + "--flag", "answered", + "--flag", "flagged", + ]) + #expect(sut.predicate.olderThanDays == 90) + #expect(sut.predicate.newerThanDays == 30) + #expect(sut.predicate.flags == [.seen, .answered, .flagged]) + } + + // MARK: - Edge Cases and Validation Tests + + @Test + static func parseSearchCommand_largeDayValues() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "365", + "--newer-than-days", "1000", + ]) + #expect(sut.predicate.olderThanDays == 365) + #expect(sut.predicate.newerThanDays == 1000) + } + + @Test + static func parseSearchCommand_unicodeSubject() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--subject", "测试邮件 🎉", + ]) + #expect(sut.predicate.subject == "测试邮件 🎉") + } + + @Test + static func parseSearchCommand_specialCharactersInFrom() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--from", "user+tag@example.com", + ]) + #expect(sut.predicate.fromAddress == "user+tag@example.com") + } + + @Test + static func parseSearchCommand_duplicateFlags() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--flag", "seen", + "--flag", "seen", + "--flag", "flagged", + "--flag", "seen", + ]) + #expect(sut.predicate.flags == [.seen, .seen, .flagged, .seen]) + } + + @Test + static func parseSearchCommand_noSearchCriteria() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + ]) + // Should be valid - will use SearchKey.all + #expect(sut.predicate.olderThanDays == nil) + #expect(sut.predicate.newerThanDays == nil) + #expect(sut.predicate.subject == nil) + #expect(sut.predicate.fromAddress == nil) + #expect(sut.predicate.flags == []) + } + + // MARK: - Search Logic Integration Tests + + @Test + static func searchLogic_dateCalculation() throws { + // Test that date calculations work correctly + let calendar = Calendar.current + let today = Date() + + // Test older than 30 days + let olderDate = calendar.date(byAdding: .day, value: -30, to: today)! + let olderComponents = calendar.dateComponents([.year, .month, .day], from: olderDate) + let olderIMAPDate = IMAPCalendarDay( + year: olderComponents.year!, + month: olderComponents.month!, + day: olderComponents.day! + ) + #expect(olderIMAPDate != nil) + + // Test newer than 7 days + let newerDate = calendar.date(byAdding: .day, value: -7, to: today)! + let newerComponents = calendar.dateComponents([.year, .month, .day], from: newerDate) + let newerIMAPDate = IMAPCalendarDay( + year: newerComponents.year!, + month: newerComponents.month!, + day: newerComponents.day! + ) + #expect(newerIMAPDate != nil) + + // Newer date should be more recent than older date + if let older = olderIMAPDate, let newer = newerIMAPDate { + #expect(newer.year >= older.year) + if newer.year == older.year { + #expect(newer.month >= older.month) + if newer.month == older.month { + #expect(newer.day >= older.day) + } + } + } + } + + @Test + static func searchLogic_flagMapping() throws { + // Test that flag strings map correctly to lowercase + let flagMappings: [String: String] = [ + "seen": "seen", + "flagged": "flagged", + "answered": "answered", + "deleted": "deleted", + "draft": "draft", + ] + + for (input, expected) in flagMappings { + // Test lowercase + #expect(input.lowercased() == expected) + + // Test that uppercase works too + #expect(input.uppercased().lowercased() == expected) + } + } + + @Test + static func searchLogic_byteBufferCreation() throws { + // Test ByteBuffer creation for subject and from strings + let testStrings = [ + "Simple subject", + "Subject with unicode 🎉", + "Empty string: ", + "Subject with\nnewlines\nand\ttabs", + "user@example.com", + "User Name ", + "用户@example.com", // Unicode email + ] + + for testString in testStrings { + let buffer = ByteBuffer(string: testString) + #expect(buffer.readableBytes > 0 || testString.isEmpty) + + // Verify we can read the string back + let reconstructed = buffer.getString(at: 0, length: buffer.readableBytes) + #expect(reconstructed == testString) + } + } + + @Test + static func searchLogic_combinedSearchKeys() throws { + // Test the logic for combining multiple search criteria + var searchKeys: [SearchKey] = [] + + // Add various criteria + searchKeys.append(.seen) + searchKeys.append(.flagged) + let subjectBuffer = ByteBuffer(string: "test") + searchKeys.append(.subject(subjectBuffer)) + + // Test single key + let singleKey = searchKeys.first! + let singleKeyDesc = String(describing: singleKey).uppercased() + #expect(singleKeyDesc.contains("SEEN")) + + // Test combined key + if searchKeys.count > 1 { + let combinedKey = SearchKey.and(searchKeys) + // The combined key should contain multiple search terms + let combinedKeyDesc = String(describing: combinedKey).uppercased() + #expect(combinedKeyDesc.contains("SEEN")) + #expect(combinedKeyDesc.contains("FLAGGED")) + #expect(combinedKeyDesc.contains("SUBJECT")) + } + + // Test empty case (should use .all) + let emptyKeys: [SearchKey] = [] + if emptyKeys.isEmpty { + let allKey = SearchKey.all + let allKeyDesc = String(describing: allKey).uppercased() + #expect(allKeyDesc.contains("ALL")) + } + } + + // MARK: - Invalid Input Tests + + @Test + static func parseSearchCommand_negativeOlderThanDays() throws { + // Negative day values should be treated as invalid by ArgumentParser + #expect( + performing: { + _ = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--older-than-days", "-5", + ]) + }, + throws: { _ in true } + ) + } + + @Test + static func parseSearchCommand_negativeNewerThanDays() throws { + // Negative day values should be treated as invalid by ArgumentParser + #expect( + performing: { + _ = try parse([ + "search-messages", + "--sasl", "plain:foo bar", + "--server", "example.com", + "--newer-than-days", "-10", + ]) + }, + throws: { _ in true } + ) + } + + // MARK: - IMAPConnection Info Tests + + @Test + static func parseSearchCommand_usernameAuth() throws { + let sut = try parse([ + "search-messages", + "--username", "user:password", + "--server", "example.com", + ]) + #expect(sut.connectionInfo.username == "user:password") + #expect(sut.connectionInfo.sasl == nil) + } + + @Test + static func parseSearchCommand_saslAuth() throws { + let sut = try parse([ + "search-messages", + "--sasl", "oauth:token123", + "--server", "example.com", + ]) + #expect(sut.connectionInfo.sasl == "oauth:token123") + #expect(sut.connectionInfo.username == nil) + } + + @Test + static func parseSearchCommand_customPort() throws { + let sut = try parse([ + "search-messages", + "--username", "user:pass", + "--server", "example.com:143", + ]) + #expect(sut.connectionInfo.server == "example.com:143") + } + + @Test + static func parseSearchCommand_forceLogin() throws { + let sut = try parse([ + "search-messages", + "--username", "user:pass", + "--server", "example.com", + "--force-login", + ]) + #expect(sut.connectionInfo.forceLogin == true) + #expect(sut.connectionInfo.authenticationMethod == .login) + } + + @Test + static func parseSearchCommand_withoutForceLogin() throws { + let sut = try parse([ + "search-messages", + "--username", "user:pass", + "--server", "example.com", + ]) + #expect(sut.connectionInfo.authenticationMethod == .automatic) + } + + @Test + static func parseSearchCommand_forceLoginConflictsWithSASL() throws { + let saslArguments = [ + "search-messages", + "--sasl", "plain:dG9rZW4=", + "--server", "example.com", + ] + // The same arguments parse without the flag, so the flag is what’s rejected. + _ = try parse(saslArguments) + #expect(throws: (any Error).self) { + try parse(saslArguments + ["--force-login"]) + } + } + + // MARK: - Real-world Usage Pattern Tests + + @Test + static func parseSearchCommand_findUnreadMessagesFromLastWeek() throws { + let sut = try parse([ + "search-messages", + "--sasl", "oauth:token123", + "--server", "imap.gmail.com", + "--newer-than-days", "7", + "--flag", "seen", + "--fetch-message-info", + ]) + #expect(sut.predicate.newerThanDays == 7) + #expect(sut.predicate.flags == [.seen]) + #expect(sut.shouldFetchMessageInfo == true) + } + + @Test + static func searchLogic_sequenceNumberToMessageInfoMapping() throws { + // Test that we understand the difference between sequence numbers and UIDs + // This test documents the fix for the sequence number vs UID confusion + + // Simulate search results (sequence numbers) + let searchResults: [SequenceNumber] = [SequenceNumber(1), SequenceNumber(3), SequenceNumber(5)] + + // Simulate message infos (with UIDs that are different from sequence numbers) + struct MockMessageInfo { + let uid: UInt32 + let sequenceNumber: Int + } + + let allMessageInfos = [ + MockMessageInfo(uid: 1001, sequenceNumber: 1), // seq 1, uid 1001 + MockMessageInfo(uid: 1005, sequenceNumber: 2), // seq 2, uid 1005 + MockMessageInfo(uid: 1007, sequenceNumber: 3), // seq 3, uid 1007 + MockMessageInfo(uid: 1012, sequenceNumber: 4), // seq 4, uid 1012 + MockMessageInfo(uid: 1015, sequenceNumber: 5), // seq 5, uid 1015 + ] + + // Test the WRONG approach (matching sequence numbers against UIDs) + let searchUIDs = Set(searchResults.map { UInt32($0) }) // [1, 3, 5] + let wrongFiltered = allMessageInfos.filter { searchUIDs.contains($0.uid) } + #expect(wrongFiltered.isEmpty) // This fails because UIDs don't match sequence numbers + + // Test the CORRECT approach (matching by sequence number position) + let searchSequenceNumbers = Set(searchResults.map { Int($0) }) // [1, 3, 5] + let correctFiltered = allMessageInfos.enumerated().compactMap { (index, messageInfo) in + let sequenceNumber = index + 1 // Convert 0-based index to 1-based sequence + return searchSequenceNumbers.contains(sequenceNumber) ? messageInfo : nil + } + #expect(correctFiltered.count == 3) // Should find 3 messages + #expect(correctFiltered[0].uid == 1001) // seq 1 -> uid 1001 + #expect(correctFiltered[1].uid == 1007) // seq 3 -> uid 1007 + #expect(correctFiltered[2].uid == 1015) // seq 5 -> uid 1015 + } + + @Test + static func parseSearchCommand_findImportantEmailsFromBoss() throws { + let sut = try parse([ + "search-messages", + "--username", "employee:password", + "--server", "company.com", + "--from", "boss@company.com", + "--flag", "flagged", + "--subject", "urgent", + "--mailbox", "INBOX", + ]) + #expect(sut.predicate.fromAddress == "boss@company.com") + #expect(sut.predicate.flags == [.flagged]) + #expect(sut.predicate.subject == "urgent") + #expect(sut.mailbox == .inbox) + } + + @Test + static func parseSearchCommand_cleanupOldDrafts() throws { + let sut = try parse([ + "search-messages", + "--username", "user:pass", + "--server", "example.com", + "--mailbox", "Drafts", + "--older-than-days", "90", + "--flag", "draft", + "--output-format", "json", + ]) + #expect(sut.mailbox == "Drafts") + #expect(sut.predicate.olderThanDays == 90) + #expect(sut.predicate.flags == [.draft]) + #expect(sut.outputFormat == .json) + } + + @Test + static func parseSearchCommand_findAnsweredEmailsInDateRange() throws { + let sut = try parse([ + "search-messages", + "--sasl", "plain:token123", + "--server", "imap.example.com", + "--older-than-days", "30", + "--newer-than-days", "7", + "--flag", "answered", + "--flag", "seen", + "--fetch-message-info", + ]) + #expect(sut.predicate.olderThanDays == 30) + #expect(sut.predicate.newerThanDays == 7) + #expect(sut.predicate.flags == [.answered, .seen]) + #expect(sut.shouldFetchMessageInfo == true) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommand_PredicateTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommand_PredicateTests.swift new file mode 100644 index 00000000..90de85e1 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/SearchMessagesCommand_PredicateTests.swift @@ -0,0 +1,310 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +import Foundation +import NIO +import NIOIMAP +import Testing + +@Suite("SearchMessagesCommand Tests") +private enum SearchMessagesCommandPredicateTests { + struct ParseFixture: Sendable, CustomTestStringConvertible { + var arguments: [String] + var expected: Expected + + enum Expected: Sendable { + case parse(SearchKey.Predicate) + case fail(String) + } + + var testDescription: String { arguments.joined(separator: " ") } + } + + @Test(arguments: [ + ParseFixture( + arguments: ["--from", "foo"], + expected: .parse( + SearchKey.Predicate( + from: "foo" + ) + ) + ), + ParseFixture( + arguments: ["--to", "bar"], + expected: .parse( + SearchKey.Predicate( + to: "bar" + ) + ) + ), + ParseFixture( + arguments: ["--cc", "baz"], + expected: .parse( + SearchKey.Predicate( + cc: "baz" + ) + ) + ), + ParseFixture( + arguments: ["--subject", "test subject"], + expected: .parse( + SearchKey.Predicate( + subject: "test subject" + ) + ) + ), + ParseFixture( + arguments: ["--text", "search text"], + expected: .parse( + SearchKey.Predicate( + text: "search text" + ) + ) + ), + ParseFixture( + arguments: ["--older-than-days", "10"], + expected: .parse( + SearchKey.Predicate( + olderThanDays: 10 + ) + ) + ), + ParseFixture( + arguments: ["--newer-than-days", "5"], + expected: .parse( + SearchKey.Predicate( + newerThanDays: 5 + ) + ) + ), + ParseFixture( + arguments: ["--message-size-smaller-than", "1000"], + expected: .parse( + SearchKey.Predicate( + messageSizeSmallerThan: 1000 + ) + ) + ), + ParseFixture( + arguments: ["--message-size-larger-than", "500"], + expected: .parse( + SearchKey.Predicate( + messageSizeLargerThan: 500 + ) + ) + ), + ParseFixture( + arguments: ["--message-id", ""], + expected: .parse( + SearchKey.Predicate( + messageID: MessageID("") + ) + ) + ), + ParseFixture( + arguments: ["--email-id", "test123"], + expected: .parse( + SearchKey.Predicate( + emailID: EmailID("test123") + ) + ) + ), + ParseFixture( + arguments: ["--thread-id", "thread456"], + expected: .parse( + SearchKey.Predicate( + threadID: ThreadID("thread456") + ) + ) + ), + ParseFixture( + arguments: ["--flag", "seen"], + expected: .parse( + SearchKey.Predicate( + flagsSet: [.seen] + ) + ) + ), + ParseFixture( + arguments: ["--flag", "red"], + expected: .parse( + SearchKey.Predicate( + flagsSet: [.flagged], + flagsNotSet: [.mailFlagBit0, .mailFlagBit1, .mailFlagBit2] + ) + ) + ), + ParseFixture( + arguments: ["--flag", "orange"], + expected: .parse( + SearchKey.Predicate( + flagsSet: [.flagged, .mailFlagBit0], + flagsNotSet: [.mailFlagBit1, .mailFlagBit2] + ) + ) + ), + ParseFixture( + arguments: ["--flag", "seen", "--flag", "deleted"], + expected: .parse( + SearchKey.Predicate( + flagsSet: [.seen, .deleted] + ) + ) + ), + ParseFixture( + arguments: ["--flag", "red", "--flag", "orange"], + expected: .fail("Error: Invalid combination of flags {red, orange}") + ), + ParseFixture( + arguments: ["--flag", "red", "--flag", "orange", "--flag", "answered"], + expected: .fail("Error: Invalid combination of flags {red, orange}") + ), + ParseFixture( + arguments: ["--from", "sender@example.com", "--to", "recipient@example.com", "--flag", "seen"], + expected: .parse( + SearchKey.Predicate( + from: "sender@example.com", + to: "recipient@example.com", + flagsSet: [.seen] + ) + ) + ), + ParseFixture( + arguments: ["--from", "boss@example.com", "--subject", "urgent", "--older-than-days", "7"], + expected: .parse( + SearchKey.Predicate( + olderThanDays: 7, + subject: "urgent", + from: "boss@example.com" + ) + ) + ), + ParseFixture( + arguments: ["--from", "newsletter@example.com", "--message-size-larger-than", "1000000"], + expected: .parse( + SearchKey.Predicate( + from: "newsletter@example.com", + messageSizeLargerThan: 1_000_000 + ) + ) + ), + ParseFixture( + arguments: [ + "--text", "verification code", "--newer-than-days", "1", "--message-size-smaller-than", "5000", + ], + expected: .parse( + SearchKey.Predicate( + newerThanDays: 1, + text: "verification code", + messageSizeSmallerThan: 5000 + ) + ) + ), + ParseFixture( + arguments: [ + "--from", "team@example.com", "--to", "me@example.com", "--cc", "manager@example.com", "--subject", + "project update", + ], + expected: .parse( + SearchKey.Predicate( + subject: "project update", + from: "team@example.com", + to: "me@example.com", + cc: "manager@example.com" + ) + ) + ), + ParseFixture( + arguments: ["--subject", "invoice", "--text", "payment due", "--newer-than-days", "30"], + expected: .parse( + SearchKey.Predicate( + newerThanDays: 30, + subject: "invoice", + text: "payment due" + ) + ) + ), + ParseFixture( + arguments: ["--thread-id", "thread789", "--flag", "seen", "--flag", "answered"], + expected: .parse( + SearchKey.Predicate( + threadID: ThreadID("thread789"), + flagsSet: [.seen, .answered] + ) + ) + ), + ParseFixture( + arguments: ["--older-than-days", "365", "--message-size-larger-than", "10000000", "--flag", "seen"], + expected: .parse( + SearchKey.Predicate( + olderThanDays: 365, + messageSizeLargerThan: 10_000_000, + flagsSet: [.seen] + ) + ) + ), + ParseFixture( + arguments: ["--older-than-days", "10", "--newer-than-days", "20"], + expected: .parse( + SearchKey.Predicate( + olderThanDays: 10, + newerThanDays: 20, + ) + ) + ), + ParseFixture( + arguments: ["--older-than-days", "20", "--newer-than-days", "10"], + expected: .fail("Error: Messages can not be older than 20 and newer than 10 at the same time.") + ), + ]) + static func parse( + fixture: ParseFixture + ) throws { + switch fixture.expected { + case .parse(let expected): + let commandPredicate = try SearchMessagesCommand.Predicate.parse(fixture.arguments) + let p = try SearchKey.Predicate(commandPredicate) + #expect(p.olderThanDays == expected.olderThanDays) + #expect(p.newerThanDays == expected.newerThanDays) + #expect(p.subject == expected.subject) + #expect(p.from == expected.from) + #expect(p.to == expected.to) + #expect(p.cc == expected.cc) + #expect(p.text == expected.text) + #expect(p.messageSizeSmallerThan == expected.messageSizeSmallerThan) + #expect(p.messageSizeLargerThan == expected.messageSizeLargerThan) + #expect(p.messageID == expected.messageID) + #expect(p.emailID == expected.emailID) + #expect(p.threadID == expected.threadID) + #expect(p.flagsSet == expected.flagsSet) + #expect(p.flagsNotSet == expected.flagsNotSet) + case .fail(let expected): + #expect( + performing: { + let commandPredicate = try SearchMessagesCommand.Predicate.parse(fixture.arguments) + _ = try SearchKey.Predicate(commandPredicate) + }, + throws: { + #expect( + firstLineOfErrorMessage(for: $0) + == expected + ) + return true + } + ) + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/TerminationInfoTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/TerminationInfoTests.swift new file mode 100644 index 00000000..49472c5d --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/TerminationInfoTests.swift @@ -0,0 +1,77 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPToolLib +import Testing + +/// Verifies how ``main()`` decides to terminate: `--help`/`--version` must be +/// treated as "clean" exits (standard output, exit code `0`), while genuine +/// parsing errors must be non-clean (standard error, non-zero exit code). +@Suite("Termination Info") +enum TerminationInfoTests { + /// Mirrors ``main()``: parse, then run, returning whichever step throws. + /// + /// This matters because ArgumentParser signals `--help`/`--version` by + /// having `run()` throw a clean-exit error — `parseAsRoot` itself does not + /// throw for those. None of the arguments used below parse to a runnable + /// subcommand that performs I/O. + private static func terminationError(for arguments: [String]) async -> (any Error)? { + do { + var command = try RootCommand.parseAsRoot(arguments) + if var asyncCommand = command as? AsyncParsableCommand { + try await asyncCommand.run() + } else { + try command.run() + } + return nil + } catch { + return error + } + } + + @Test + static func helpRequestIsACleanExit() async throws { + let info = terminationInfo(for: try #require(await terminationError(for: ["--help"]))) + #expect(info.isCleanExit) + #expect(info.code == 0) + #expect(!info.message.isEmpty) + } + + @Test + static func subcommandHelpRequestIsACleanExit() async throws { + let info = terminationInfo(for: try #require(await terminationError(for: ["idle", "--help"]))) + #expect(info.isCleanExit) + #expect(info.code == 0) + } + + @Test + static func parsingErrorIsNotACleanExit() async throws { + // An unknown flag on a known subcommand is a usage error, not a clean exit. + let info = terminationInfo( + for: try #require(await terminationError(for: ["idle", "--this-flag-does-not-exist"])) + ) + #expect(!info.isCleanExit) + #expect(info.code != 0) + } + + @Test + static func unknownSubcommandIsNotACleanExit() async throws { + let info = terminationInfo( + for: try #require(await terminationError(for: ["definitely-not-a-subcommand"])) + ) + #expect(!info.isCleanExit) + #expect(info.code != 0) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/UIDsAndMessageIDsTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/UIDsAndMessageIDsTests.swift new file mode 100644 index 00000000..7988c78b --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Commands/UIDsAndMessageIDsTests.swift @@ -0,0 +1,79 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Foundation +import NIO +import NIOIMAP +import Testing + +@Suite +enum UIDsAndMessageIDsTests { + @Test + static func parsingJSON_1() throws { + let ids = try UIDsAndMessageIDs.parse( + input: Data( + #""" + {"messages" : [{"filename" : "Available now_ Bayonetta 3.eml","id" : "<61bed42d-59c4-4734-b501-c903d3ba8952@atl1s07mta2958.xt.local>","uid" : 34},{"filename" : "New sign-in to your account 5.eml","id" : "<010001762fc8b627-39331a9f-265d-4135-8367-8fdaf93a44ed-000000@email.amazonses.com>","uid" : 5678}]} + """#.utf8 + ) + ) + #expect(ids.uids == [34, 5678]) + #expect(ids.messageIDs == []) + } + + @Test + static func parsingJSON_2() throws { + let ids = try UIDsAndMessageIDs.parse( + input: Data( + #""" + {"messages" : [{"uid" : 34},{"uid" : 5678}]} + """#.utf8 + ) + ) + #expect(ids.uids == [34, 5678]) + #expect(ids.messageIDs == []) + } + + @Test + static func parsingJSON_3() throws { + let ids = try UIDsAndMessageIDs.parse( + input: Data( + #""" + {"messages" : [{"uid" : 30}]} + """#.utf8 + ) + ) + #expect(ids.uids == [30]) + #expect(ids.messageIDs == []) + } + + @Test + static func parsingJSON_4() throws { + let ids = try UIDsAndMessageIDs.parse( + input: Data( + #""" + {"messages" : [{"id" : "<61bed42d-59c4-4734-b501-c903d3ba8952@atl1s07mta2958.xt.local>"},{"id" : "<010001762fc8b627-39331a9f-265d-4135-8367-8fdaf93a44ed-000000@email.amazonses.com>"}]} + """#.utf8 + ) + ) + #expect(ids.uids == []) + #expect( + ids.messageIDs == [ + "<61bed42d-59c4-4734-b501-c903d3ba8952@atl1s07mta2958.xt.local>", + "<010001762fc8b627-39331a9f-265d-4135-8367-8fdaf93a44ed-000000@email.amazonses.com>", + ] + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Helpers.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Helpers.swift new file mode 100644 index 00000000..237a0191 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Helpers.swift @@ -0,0 +1,123 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPCommands +import Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing +import SystemPackage +#if canImport(Glibc) +import Glibc +#elseif canImport(Darwin) +import Darwin +#endif + +/// `URL(filePath:)` is Darwin-only; on Linux the initializer takes a `String`. +extension URL { + init(_ filePath: FilePath) { + self.init(fileURLWithPath: filePath.string) + } +} + +func firstLineOfErrorMessage(for error: any Error) -> Substring { + RootCommand + .fullMessage(for: error) + .prefix(while: { !$0.isNewline }) +} + +struct ConnectionHelper { + var sent: [CommandStreamPart] = [] + mutating func send(_ c: CommandStreamPart) { + self.sent.append(c) + } +} + +extension IMAPCredential { + static var testUsername: IMAPCredential { + .username("foo", password: "bar") + } +} + +extension CommandStreamPart { + static func continuationResponse(_ data: Data) -> CommandStreamPart { + .continuationResponse(ByteBuffer(data)) + } +} + +extension NIOIMAP.MailboxName: @retroactive ExpressibleByStringLiteral { + public init(stringLiteral value: String) { + // Test code only: + self = try! MailboxPath.makeRootMailbox(displayName: value).name + } +} + +extension NIOIMAP.MailboxPath: @retroactive ExpressibleByStringLiteral { + public init(stringLiteral value: String) { + try! self.init(name: MailboxName(stringLiteral: value), pathSeparator: ".") + } +} + +extension IMAPConnection.Tag: @retroactive ExpressibleByStringLiteral { + public init(stringLiteral value: String) { + self = IMAPConnection.Tag(value)! + } +} + +extension CommandStreamPart { + func getCommand() throws -> TaggedCommand { + guard case .tagged(let tagged) = self else { + struct NotACommand: Swift.Error {} + throw NotACommand() + } + return tagged + } +} + +func withTemporaryDirectory( + closure: (FilePath) async throws -> R +) async throws -> R { + let a = FilePath(NSTemporaryDirectory()).appending("DownloadDirectoryTests-XXXXXXXXXXXXXXXX") + let p = a.withPlatformString { pointer -> FilePath? in + let count = strlen(pointer) + let immutable = UnsafeBufferPointer(start: pointer, count: count) + return withUnsafeTemporaryAllocation( + of: CInterop.PlatformChar.self, + capacity: count + 1 + ) { buffer -> FilePath? in + let (_, index) = buffer.initialize(from: immutable) + buffer[index] = 0 + // Glibc’s `mkdtemp` takes a non-optional pointer. + guard + let template = buffer.baseAddress, + mkdtemp(template) != nil + else { return nil } + return FilePath(platformString: template) + } + } + guard let p else { throw FailedToCreateTemporaryDirectory() } + let r = try await closure(p) + deleteDirectory(p) + return r +} + +private struct FailedToCreateTemporaryDirectory: Swift.Error {} + +private func deleteDirectory(_ root: FilePath) { + // `nftw` is not exposed by Swift’s Glibc overlay, so this walks the tree + // with `FileManager`, which is portable. Deletion is best effort. + try? FileManager.default.removeItem(at: URL(root)) +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/InternetMessageDateParsingTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/InternetMessageDateParsingTests.swift new file mode 100644 index 00000000..6db41867 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/InternetMessageDateParsingTests.swift @@ -0,0 +1,373 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIOIMAP +import Testing + +@Suite("InternetMessageDate parsing") +private enum InternetMessageDateParsingTests { + // MARK: - Fast path: parseWithoutFoundation + + struct FixedTZParseFixture: Sendable, CustomTestStringConvertible { + var input: String + var expected: TimeInterval + + var testDescription: String { input } + } + + /// Cases that the strptime-based path can parse — that is, dates with a + /// numeric `±HHMM` offset (or no offset) and no obs-zone abbreviation. + /// + /// The `parseWithoutFoundation` fast path is Darwin-only (glibc has no + /// `strptime_l`), so this test only runs there. The same inputs are covered + /// through `parse()` — which falls back to Foundation — on all platforms. + #if canImport(Darwin) + @Test(arguments: [ + // IMAP-style quoted dates + FixedTZParseFixture(input: #""29-Jul-2013 11:45:15 -0700""#, expected: 396_816_315), + FixedTZParseFixture(input: #"" 8-Nov-2004 08:00:00 -0700""#, expected: 121_618_800), + FixedTZParseFixture(input: #""08-May-1985 15:00:00 +0100""#, expected: -493_898_400), + FixedTZParseFixture(input: #""4-Nov-1980 14:49:00 -0500""#, expected: -636_091_860), + // RFC 2822 + FixedTZParseFixture(input: "Tue, 29 Oct 2012 10:00:00 -0800", expected: 373_226_400), + FixedTZParseFixture(input: "29 Oct 2012 10:00 -0800", expected: 373_226_400), + FixedTZParseFixture(input: " Tue, 29 Oct 2012 10:00:00 -0800 ", expected: 373_226_400), + FixedTZParseFixture(input: "Thu, 1 Apr 1976 17:00:00 -0800", expected: -781_052_400), + FixedTZParseFixture(input: "Mon, May 20 2002 10:18:51 -0700", expected: 43_607_931), + // Time zone offset followed by a parenthesised time-zone name (seen in the wild): + FixedTZParseFixture(input: "Sat, 5 Sep 2020 02:25:49 +0000 (GMT)", expected: 620_965_549), + FixedTZParseFixture(input: "Fri, 18 Oct 2019 14:03:42 -0700 (PDT)", expected: 593_125_422), + ]) + static func parsingWithoutFoundation(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parseWithoutFoundation() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + #endif + + // MARK: - Empty / unparseable + + @Test(arguments: ["", " \t\n"]) + static func emptyDates(input: String) { + #expect(InternetMessageDate(input).parse() == nil) + } + + // MARK: - IMAP calendar-day form + + @Test(arguments: [ + FixedTZParseFixture(input: #""29-Jul-2013 11:45:15 -0700""#, expected: 396_816_315), + FixedTZParseFixture(input: #"" 8-Nov-2004 08:00:00 -0700""#, expected: 121_618_800), + FixedTZParseFixture(input: #""08-May-1945 15:00:00 +0100""#, expected: -1_756_202_400), + ]) + static func imapCalendarDays(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parse() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + + // MARK: - RFC 2822 dates + + @Test(arguments: [ + FixedTZParseFixture(input: "Tue, 29 Oct 2012 10:00:00 -0800", expected: 373_226_400), + FixedTZParseFixture(input: "29 Oct 2012 10:00 -0800", expected: 373_226_400), + FixedTZParseFixture(input: " Tue, 29 Oct 2012 10:00:00 -0800 ", expected: 373_226_400), + FixedTZParseFixture(input: "Thu, 1 Apr 1976 17:00:00 -0800", expected: -781_052_400), + ]) + static func internetMessageDates(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parse() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + + // MARK: - Obsolete dates (RFC 2822 §4.3 obs-zone, 2-digit years) + + @Test(arguments: [ + // The military time zones from RFC 5322 §4.3 don't work with NSDateFormatter/ICU; + // they aren't covered here. + FixedTZParseFixture(input: "24 Mar 2001 12:00:00 UT", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 12:00:00 GMT", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 07:00:00 EST", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 08:00 EDT", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 06:00:00 CST", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 07:00 CDT", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 05:00:00 MST", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 06:00:00 MDT", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 04:00 PST", expected: 7_128_000), + FixedTZParseFixture(input: "24 Mar 2001 05:00:00 PDT", expected: 7_128_000), + // 2-digit years before 50 are 20xx; 50 and later are 19xx. + FixedTZParseFixture(input: "24 Jun 13 10:45 -0700", expected: 393_788_700), + FixedTZParseFixture(input: "3 Jun 77 01:25 -0500", expected: -744_140_100), + ]) + static func obsoleteInternetMessageDates(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parse() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + + // MARK: - Illegal-but-tolerated forms + + @Test + static func illegalDatesFromICloud() { + // iCloud's quirky form: + let date = InternetMessageDate("Sat, 5 Sep 2020 02:25:49 +0000 (GMT)").parse() + expectDate(date, equals: 620_965_549, input: "iCloud") + } + + @Test(arguments: [ + FixedTZParseFixture(input: "29-Jul-2013 11:45:15 -0700", expected: 396_816_315), + FixedTZParseFixture(input: "8-Nov-04 08:00 -0700", expected: 121_618_800), + FixedTZParseFixture(input: "8-Nov-04 08:00 PDT", expected: 121_618_800), + ]) + static func illegalIMAPLikeDates(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parse() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + + @Test(arguments: [ + FixedTZParseFixture(input: "Jun 5, 2011 7:59:47 AM US/Eastern", expected: 328_942_787), + FixedTZParseFixture(input: "Mon, May 20 2002 10:18:51 -0700", expected: 43_607_931), + FixedTZParseFixture(input: "January 08, 2004 12:01:13 EST", expected: 95_274_073), + FixedTZParseFixture(input: "January 27, 2004 11:42:03 EST", expected: 96_914_523), + FixedTZParseFixture(input: "Tue Oct 21, 2003 15:59:25 US/Eastern", expected: 88_459_165), + FixedTZParseFixture(input: "Sun, Mar 31, 1996 07:57 EDT", expected: -150_033_780), + FixedTZParseFixture(input: "December 30, 2003 12:30:43 EST", expected: 94_498_243), + FixedTZParseFixture(input: "Mon Sep 22, 2003 14:49:00 US/Eastern", expected: 85_949_340), + FixedTZParseFixture(input: "Fri May 23 12:00:00 EDT", expected: 359_438_400), + FixedTZParseFixture(input: #""4-Nov-1980 14:49:00 -0500""#, expected: -636_091_860), + FixedTZParseFixture(input: "1984-5-4 15:00:00 -0700", expected: -525_751_200), + FixedTZParseFixture(input: "2/9 3:42 AM", expected: -28_250_280), + FixedTZParseFixture(input: "02/09/87 3:42 am", expected: -438_477_480), + ]) + static func illegalDates(fixture: FixedTZParseFixture) { + let date = InternetMessageDate(fixture.input).parse() + expectDate(date, equals: fixture.expected, input: fixture.input) + } + + // MARK: - Local-timezone dates (no offset in the string) + // + // These dates omit the time-zone, so the parser interprets them in the + // local time zone. We compute the expected timestamp the same way, which + // means these tests are sensitive to the test machine's time zone — but + // also mirror the parser's behavior exactly. `Calendar.current` resolves + // the wall-clock components against the local zone including DST, so a + // summer date is read as e.g. CEST rather than CET. + + struct LocalTZParseFixture: Sendable, CustomTestStringConvertible { + var input: String + var year: Int + var month: Int + var day: Int + var hour: Int + var minute: Int + var second: Int = 0 + + var testDescription: String { input } + } + + @Test(arguments: [ + LocalTZParseFixture( + input: "Tue, Dec 30, 2008 at 3:22 PM", + year: 2008, + month: 12, + day: 30, + hour: 15, + minute: 22 + ), + LocalTZParseFixture( + input: "Mon Mar 30 11:45:00 2003", + year: 2003, + month: 3, + day: 30, + hour: 11, + minute: 45 + ), + LocalTZParseFixture( + input: "Tue, 19 Aug 2003 14:49:00", + year: 2003, + month: 8, + day: 19, + hour: 14, + minute: 49 + ), + LocalTZParseFixture( + input: "5 Nov 1982 14:49:00", + year: 1982, + month: 11, + day: 5, + hour: 14, + minute: 49 + ), + ]) + static func datesParsedInLocalTimeZone(fixture: LocalTZParseFixture) { + guard let actual = InternetMessageDate(fixture.input).parse() else { + Issue.record("Failed to parse '\(fixture.input)'") + return + } + let components = DateComponents( + year: fixture.year, + month: fixture.month, + day: fixture.day, + hour: fixture.hour, + minute: fixture.minute, + second: fixture.second + ) + let expectedDate = Calendar.current.date(from: components)! + let expected = expectedDate.timeIntervalSinceReferenceDate + let actualInterval = actual.timeIntervalSinceReferenceDate + #expect( + abs(actualInterval - expected) < 0.000_5, + "Parsed '\(fixture.input)' as \(actual); expected interval \(expected), got \(actualInterval)" + ) + } + + // MARK: - Formatting (Date → InternetMessageDate) + + struct FormatFixture: Sendable, CustomTestStringConvertible { + var date: Date + var calendar: Calendar + var calendarLabel: String + var expected: String + + var testDescription: String { "\(date) / \(calendarLabel)" } + } + + @Test(arguments: [ + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 590_000_000), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Thu, 12 Sep 2019 23:53:20 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 590_012_345), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Fri, 13 Sep 2019 03:19:05 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 590_018_888), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Fri, 13 Sep 2019 05:08:08 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 596_737_019), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Fri, 29 Nov 2019 23:16:59 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 596_737_019), + calendar: .testCalendarB, + calendarLabel: "Sao_Paulo", + expected: "Fri, 29 Nov 2019 13:16:59 -0300" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: -150_033_780), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Sun, 31 Mar 1996 18:57:00 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: -150_033_780), + calendar: .testCalendarB, + calendarLabel: "Sao_Paulo", + expected: "Sun, 31 Mar 1996 08:57:00 -0300" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 88_459_165), + calendar: .testCalendar, + calendarLabel: "+0700", + expected: "Wed, 22 Oct 2003 02:59:25 +0700" + ), + FormatFixture( + date: Date(timeIntervalSinceReferenceDate: 88_459_165), + calendar: .testCalendarB, + calendarLabel: "Sao_Paulo", + expected: "Tue, 21 Oct 2003 17:59:25 -0200" + ), + ]) + static func formatAsRFC822(fixture: FormatFixture) { + let formatted = String(InternetMessageDate(from: fixture.date, calendar: fixture.calendar)) + #expect(formatted == fixture.expected) + } + + // MARK: - Round trip (format → parse) + + @Test(arguments: [ + Date(timeIntervalSinceReferenceDate: 590_000_000), + Date(timeIntervalSinceReferenceDate: 596_737_019), + Date(timeIntervalSinceReferenceDate: -150_033_780), + Date(timeIntervalSinceReferenceDate: 88_459_165), + Date(timeIntervalSinceReferenceDate: 0), + Date(timeIntervalSinceReferenceDate: 1_000_000_000), + ]) + static func roundTrip(date: Date) { + for calendar in [Calendar.testCalendar, .testCalendarB, .testCalendarUTC] { + let formatted = InternetMessageDate(from: date, calendar: calendar) + guard let parsed = formatted.parse() else { + Issue.record("Failed to parse '\(String(formatted))'") + continue + } + // The wire format has second precision, so allow up to ~1 second of drift. + let drift = abs(parsed.timeIntervalSinceReferenceDate - date.timeIntervalSinceReferenceDate) + #expect( + drift < 1.1, + "'\(String(formatted))' round-tripped with \(drift)s drift" + ) + } + } +} + +// MARK: - Helpers + +private func expectDate( + _ date: Date?, + equals expectedInterval: TimeInterval, + input: String, + sourceLocation: SourceLocation = #_sourceLocation +) { + guard let date else { + Issue.record("Failed to parse '\(input)'", sourceLocation: sourceLocation) + return + } + let actual = date.timeIntervalSinceReferenceDate + #expect( + abs(actual - expectedInterval) < 0.000_5, + "Parsed '\(input)' as \(date); expected interval \(expectedInterval), got \(actual)", + sourceLocation: sourceLocation + ) +} + +extension Calendar { + /// Gregorian calendar fixed at UTC+07:00 (no DST). + fileprivate static var testCalendar: Calendar { + var c = Calendar(identifier: .gregorian) + c.timeZone = TimeZone(secondsFromGMT: 7 * 3600)! + return c + } + + /// Gregorian calendar in `America/Sao_Paulo` — historically observes DST, + /// which is what we want to exercise the formatter's offset handling. + fileprivate static var testCalendarB: Calendar { + var c = Calendar(identifier: .gregorian) + c.timeZone = TimeZone(identifier: "America/Sao_Paulo")! + return c + } + + /// Gregorian calendar fixed at UTC. + fileprivate static var testCalendarUTC: Calendar { + var c = Calendar(identifier: .gregorian) + c.timeZone = TimeZone(secondsFromGMT: 0)! + return c + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Message/MiniMIMETests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Message/MiniMIMETests.swift new file mode 100644 index 00000000..32c06c99 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Message/MiniMIMETests.swift @@ -0,0 +1,224 @@ +//===----------------------------------------------------------------------===// +// +// 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 Testing +import NIOCore +import Foundation +import NIOIMAPCore +@testable import IMAPToolLib + +@Suite("MIMEMessage line scanning") +struct MIMEMessageLineScanningTests { + + @Test("Finds Date header with CRLF line endings") + func dateHeaderCRLF() { + let input = + "From: sender@example.com\r\nDate: Fri, 15 Mar 2024 10:30:45 +0100\r\nSubject: Hello\r\n\r\nBody here" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Finds Date header with LF line endings") + func dateHeaderLF() { + let input = "From: sender@example.com\nDate: Fri, 15 Mar 2024 10:30:45 +0100\nSubject: Hello\n\nBody here" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Case-insensitive header name matching") + func caseInsensitive() { + let input = "DATE: Mon, 01 Jan 2024 00:00:00 +0000\r\n\r\n" + #expect(dateFrom(input) == "Mon, 01 Jan 2024 00:00:00 +0000") + } + + @Test("Mixed case header name") + func mixedCase() { + let input = "dAtE: Tue, 02 Jan 2024 12:00:00 -0500\r\n\r\n" + #expect(dateFrom(input) == "Tue, 02 Jan 2024 12:00:00 -0500") + } + + @Test("Stops at empty line — Date in body is not found") + func stopsAtEmptyLine() { + let input = "From: sender@example.com\r\n\r\nDate: Fri, 15 Mar 2024 10:30:45 +0100\r\n" + #expect(dateFrom(input) == nil) + } + + @Test("Returns nil when no Date header present") + func noDateHeader() { + let input = "From: sender@example.com\r\nSubject: Hello\r\n\r\nBody" + #expect(dateFrom(input) == nil) + } + + @Test("Trims leading whitespace from value") + func trimsLeadingWhitespace() { + let input = "Date: Fri, 15 Mar 2024 10:30:45 +0100\r\n\r\n" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Trims trailing whitespace from value") + func trimsTrailingWhitespace() { + let input = "Date: Fri, 15 Mar 2024 10:30:45 +0100 \r\n\r\n" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Handles tab after colon") + func tabAfterColon() { + let input = "Date:\tFri, 15 Mar 2024 10:30:45 +0100\r\n\r\n" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Returns nil for empty buffer") + func emptyBuffer() { + #expect(dateFrom("") == nil) + } + + @Test("Headers without terminating empty line still finds Date") + func noTerminatingEmptyLine() { + let input = "Date: Fri, 15 Mar 2024 10:30:45 +0100\r\nSubject: Hello" + #expect(dateFrom(input) == "Fri, 15 Mar 2024 10:30:45 +0100") + } + + @Test("Does not match partial header name like X-Date") + func doesNotMatchPartialName() { + let input = "X-Date: not this one\r\nDate: the real one\r\n\r\n" + #expect(dateFrom(input) == "the real one") + } + + @Test("Enumerates multiple headers in order") + func enumeratesMultipleHeaders() { + let input = "From: alice\r\nTo: bob\r\nSubject: hi\r\n\r\n" + var names: [String] = [] + let message = MIMEMessage.data(Data(input.utf8)) + message.withContiguousBytes { buffer in + message.enumerateHeaderLines(in: buffer) { name, _ in + names.append(name.utf8String) + return true + } + } + #expect(names == ["From", "To", "Subject"]) + } + + @Test("Stops enumeration when body returns false") + func stopsOnFalse() { + let input = "A: 1\r\nB: 2\r\nC: 3\r\n\r\n" + var count = 0 + let message = MIMEMessage.data(Data(input.utf8)) + message.withContiguousBytes { buffer in + message.enumerateHeaderLines(in: buffer) { _, _ in + count += 1 + return count < 2 + } + } + #expect(count == 2) + } + + private func dateFrom(_ string: String) -> String? { + let message = MIMEMessage.data(Data(string.utf8)) + guard let date = message.dateHeader() else { return nil } + return String(date) + } +} + +@Suite("MIMEMessage.messageIDHeader()") +struct MIMEMessageMessageIDTests { + + @Test("Finds Message-ID header") + func findsMessageID() { + let input = "Date: Mon, 01 Jan 2024 00:00:00 +0000\r\nMessage-ID: \r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + let result = message.messageIDHeader() + #expect(result != nil) + #expect(String(result!) == "") + } + + @Test("Case-insensitive Message-ID matching") + func caseInsensitive() { + let input = "MESSAGE-ID: \r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + #expect(String(message.messageIDHeader()!) == "") + } + + @Test("Returns nil when not present") + func notPresent() { + let input = "Date: Mon, 01 Jan 2024 00:00:00 +0000\r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + #expect(message.messageIDHeader() == nil) + } + + @Test("Does not match partial name like X-Message-ID") + func doesNotMatchPartial() { + let input = "X-Message-ID: \r\nMessage-ID: \r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + #expect(String(message.messageIDHeader()!) == "") + } +} + +@Suite("MIMEMessage.headersOfInterest()") +struct MIMEMessageHeadersOfInterestTests { + + @Test("Returns both date and message-id in a single pass") + func returnsBoth() { + let input = "Message-ID: \r\nDate: Wed, 10 Apr 2024 08:15:30 +0000\r\nSubject: Hello\r\n\r\nBody" + let message = MIMEMessage.data(Data(input.utf8)) + let result = message.headersOfInterest() + #expect(result != nil) + #expect(String(result!.date) == "Wed, 10 Apr 2024 08:15:30 +0000") + #expect(String(result!.messageID) == "") + } + + @Test("Returns nil when date is missing") + func missingDate() { + let input = "Message-ID: \r\nSubject: Hello\r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + #expect(message.headersOfInterest() == nil) + } + + @Test("Returns nil when message-id is missing") + func missingMessageID() { + let input = "Date: Wed, 10 Apr 2024 08:15:30 +0000\r\nSubject: Hello\r\n\r\n" + let message = MIMEMessage.data(Data(input.utf8)) + #expect(message.headersOfInterest() == nil) + } + + @Test("Stops scanning once both are found") + func stopsEarly() { + let input = + "Date: Wed, 10 Apr 2024 08:15:30 +0000\r\nMessage-ID: \r\nX-Extra: should not be reached\r\n\r\n" + var headerCount = 0 + let data = Data(input.utf8) + let message = MIMEMessage.data(data) + message.withContiguousBytes { buffer in + var date: InternetMessageDate? + var messageID: MessageID? + message.enumerateHeaderLines(in: buffer) { name, value in + headerCount += 1 + let nameStr = name.utf8String.lowercased() + if nameStr == "date" { + date = InternetMessageDate("x") + } else if nameStr == "message-id" { + messageID = MessageID("x") + } + return date == nil || messageID == nil + } + } + #expect(headerCount == 2) + } + + @Test("Works with ByteBuffer") + func worksWithByteBuffer() { + let input = "Message-ID: \r\nDate: Fri, 01 Jan 2024 00:00:00 +0000\r\n\r\n" + let message = MIMEMessage.byteBuffer(ByteBuffer(string: input)) + let result = message.headersOfInterest() + #expect(result != nil) + #expect(String(result!.messageID) == "") + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AppendTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AppendTests.swift new file mode 100644 index 00000000..f83ab840 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AppendTests.swift @@ -0,0 +1,439 @@ +//===----------------------------------------------------------------------===// +// +// 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 +@testable import IMAPToolLib +import Foundation +import NIO +import NIOIMAP +import Testing + +@Suite("Append", .timeLimit(.minutes(1))) +private struct AppendTests { + let messageA = #""" + From: foo@example.apple.com + To: bar@example.apple.com + Message-ID: <1@example.apple.com> + Subject: Test A + Date: Tue, 30 Apr 2024 14:31:07 +0000 + + Hello! + + """#.replacingOccurrences(of: "\n", with: "\r\n") + + let dateA = ServerMessageDate( + .init(year: 2024, month: 4, day: 30, hour: 14, minute: 31, second: 7, timeZoneMinutes: 0)! + ) + + func singleMessageExpectedCommand( + message: String, + internalDate: ServerMessageDate?, + completion: TaggedResponse.State = .ok(.init(text: "Done")) + ) -> TestServer.ExpectedCommand { + .init( + part: .append( + MailboxName("Food"), + [ + .beginMessage( + message: AppendMessage( + options: AppendOptions( + internalDate: internalDate + ), + data: AppendData(byteCount: message.utf8.count) + ) + ), + .messageBytes(ByteBuffer(string: message)), + .endMessage, + .finish, + ] + ), + responses: [], + completion: completion + ) + } + + @Test + func singleMessage_noInternalDate() async throws { + let message: MessageToAppend = try { + var m = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + m.serverMessageDate = nil + return m + }() + + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: nil + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_withInternalDate() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.append( + message: MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ), + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_literalPlus() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + // Turn on LITERAL+ support: + try await connection.setEncodingOptions( + .fixed( + CommandEncodingOptions( + useQuotedString: true, + useSynchronizingLiteral: false, + useNonSynchronizingLiteralPlus: true, + useNonSynchronizingLiteralMinus: false, + useBinaryLiteral: false + ) + ) + ) + + let result = try await connection.append( + message: MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ), + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_serverReturnsNo() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: dateA, + completion: .no(ResponseText(text: "Not allowed")) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection -> Void in + await #expect( + throws: FailedToAppendMessage(state: .no(ResponseText(text: "Not allowed"))) + ) { + _ = try await connection.append( + message: MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ), + into: MailboxName("Food") + ) + } + } + } + } + + @Test + func singleMessageWithUIDPLUS() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: dateA, + completion: .ok( + ResponseText( + code: .uidAppend( + ResponseCodeAppend( + uidValidity: 0x123456, + uids: [785_048] + ) + ), + text: "Done appending" + ) + ) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.append( + message: MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ), + into: MailboxName("Food") + ) + #expect(result?.uidValidity == 0x123456) + #expect(result?.uids == [785_048]) + } + } + } + + // Helper function for creating expected commands with flags + func singleMessageExpectedCommandWithFlags( + message: String, + flags: [NIOIMAP.Flag], + internalDate: ServerMessageDate?, + completion: TaggedResponse.State = .ok(.init(text: "Done")) + ) -> TestServer.ExpectedCommand { + .init( + part: .append( + MailboxName("Food"), + [ + .beginMessage( + message: AppendMessage( + options: AppendOptions( + flagList: flags, + internalDate: internalDate + ), + data: AppendData(byteCount: message.utf8.count) + ) + ), + .messageBytes(ByteBuffer(string: message)), + .endMessage, + .finish, + ] + ), + responses: [], + completion: completion + ) + } + + @Test + func singleMessage_withFlags() async throws { + let flags: [NIOIMAP.Flag] = [.seen, .flagged] + + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommandWithFlags( + message: messageA, + flags: flags, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + var message = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + message.flags = flags + + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_withMultipleFlags() async throws { + let flags: [NIOIMAP.Flag] = [.seen, .flagged, .answered, .draft] + + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommandWithFlags( + message: messageA, + flags: flags, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + var message = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + message.flags = flags + + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_withCustomFlags() async throws { + let customFlag = NIOIMAP.Flag("\\CustomFlag") + let recentFlag = NIOIMAP.Flag("\\Recent") + let flags: [NIOIMAP.Flag] = [.seen, customFlag, recentFlag] + + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommandWithFlags( + message: messageA, + flags: flags, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + var message = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + message.flags = flags + + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_withEmptyFlags() async throws { + let flags: [NIOIMAP.Flag] = [] + + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommandWithFlags( + message: messageA, + flags: flags, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + var message = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + message.flags = flags + + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } + + @Test + func singleMessage_nilFlags() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + singleMessageExpectedCommand( + message: messageA, + internalDate: dateA + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + var message = try MessageToAppend( + message: EmailMessage( + data: Data(messageA.utf8) + ), + id: "foobar" + ) + message.flags = nil + + let result = try await connection.append( + message: message, + into: MailboxName("Food") + ) + #expect(result == nil) + } + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Append_FilesTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Append_FilesTests.swift new file mode 100644 index 00000000..30a26473 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Append_FilesTests.swift @@ -0,0 +1,581 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import NIOIMAP +import SystemPackage +import Testing +@testable import IMAPToolLib + +@Suite("Append Files") +private enum Append_FilesTests { + static func createFile( + dir: FilePath, + name: String, + content: String + ) throws -> FilePath { + let path = dir.appending(name) + try Data(content.utf8).write(to: URL(path)) + return path + } + + static func createFiles( + dir: FilePath, + content: [String] + ) throws -> [FilePath] { + return try content.enumerated().map { index, content in + try createFile( + dir: dir, + name: "\(index)", + content: content + ) + } + } + + static func create3Files( + dir: FilePath, + ) throws -> (FilePath, FilePath, FilePath) { + let all = try createFiles( + dir: dir, + content: [ + #""" + From: a@example.apple.com + Subject: A + Message-id: + Date: Tue, 13 Sep 2016 04:08:04 -0700 + + a + """#, + #""" + From: b@example.apple.com + Subject: B + Message-id: + Date: Tue, 30 Apr 2024 14:31:07 +0000 + + b + """#, + #""" + From: c@example.apple.com + Subject: C + Message-id: + Date: Thu, 25 Apr 2024 16:41:32 +0200 + + c + """#, + ] + ) + try #require(all.count == 3) + let a = all[0] + let b = all[1] + let c = all[2] + return (a, b, c) + } + + @Test + static func readingSingleFile() async throws { + try await withTemporaryDirectory { dir in + let all = try createFiles( + dir: dir, + content: [ + #""" + From: a@example.apple.com + Subject: A + Message-id: + Date: Tue, 13 Sep 2016 04:08:04 -0700 + + a + """# + ] + ) + let path = try #require(all.first) + + let result = try await FileBasedMessageToAppendSequence.readSingleMessage( + path: path, + originalIndex: 95_824 + ) + #expect( + result + == FileBasedMessageToAppendSequence.IndexedFilePath( + originalIndex: 95_824, + nestedIndex: 0, + path: .init( + filePath: path, + date: Date(timeIntervalSinceReferenceDate: 495_457_684) + ) + ) + ) + } + } + + @Test + static func readingSingleFileWithInvalidDate() async throws { + try await withTemporaryDirectory { dir in + let all = try createFiles( + dir: dir, + content: [ + #""" + From: a@example.apple.com + Subject: A + Message-id: + Date: foo bar baz + + a + """# + ] + ) + let path = try #require(all.first) + + do { + _ = try await FileBasedMessageToAppendSequence.readSingleMessage( + path: path, + originalIndex: 95_824 + ) + Issue.record("Should have thrown an error") + } catch let error as FileBasedMessageToAppendSequence.UnableToParseFile { + #expect(error.filePath == path) + #expect( + (error.underlying as? FileBasedMessageToAppendSequence.UnableToParseDate)?.date == "foo bar baz" + ) + } + } + } + + @Test + static func readingSingleFileWithoutDate() async throws { + try await withTemporaryDirectory { dir in + let all = try createFiles( + dir: dir, + content: [ + #""" + From: a@example.apple.com + Subject: A + Message-id: + + a + """# + ] + ) + let path = try #require(all.first) + + do { + _ = try await FileBasedMessageToAppendSequence.readSingleMessage( + path: path, + originalIndex: 95_824 + ) + Issue.record("Should have thrown an error") + } catch let error as FileBasedMessageToAppendSequence.UnableToParseFile { + #expect(error.filePath == path) + #expect((error.underlying as? FileBasedMessageToAppendSequence.NoMessageDateInFile) != nil) + } + } + } + + @Test + static func readDirectory() async throws { + try await withTemporaryDirectory { dir in + let (a, b, c) = try create3Files(dir: dir) + + let files = try FileBasedMessageToAppendSequence.allRegularFiles(in: dir) + #expect(Set(files) == Set([a, b, c])) + + let messages = try await FileBasedMessageToAppendSequence.readDirectory( + directoryPath: dir, + originalIndex: 75_465 + ).compactMap { + try? $0.get() + }.sorted(by: { $0.sortIndex < $1.sortIndex }) + #expect(messages.map { $0.originalIndex } == [75_465, 75_465, 75_465]) + #expect(messages.map { $0.nestedIndex } == [0, 1, 2]) + #expect(Set(messages.map { $0.path.filePath }) == Set([a, b, c])) + } + } + + @Test + static func readDirectorySkippingUnreadableFiles() async throws { + try await withTemporaryDirectory { dir in + let all = try createFiles( + dir: dir, + content: [ + #""" + This is not an email + """#, + #""" + From: a@example.apple.com + Subject: A + Message-id: + Date: Tue, 13 Sep 2016 04:08:04 -0700 + + a + """#, + #""" + From: b@example.apple.com + Subject: B + Message-id: + Date: invalid date + + b + """#, + ] + ) + try #require(all.count == 3) + let a = all[0] + let b = all[1] + let c = all[2] + + let files = try FileBasedMessageToAppendSequence.allRegularFiles(in: dir) + #expect(Set(files) == Set(all)) + + let result = try await FileBasedMessageToAppendSequence.readDirectory( + directoryPath: dir, + originalIndex: 75_465 + ) + let messages = result.compactMap { + try? $0.get() + }.sorted(by: { $0.sortIndex < $1.sortIndex }) + #expect(messages.map { $0.originalIndex } == [75_465]) + #expect(messages.map { $0.path.filePath } == [b]) + + let errors: [FileBasedMessageToAppendSequence.UnableToParseFile] = result.compactMap { + guard case .failure(let error) = $0 else { return nil } + return error + } + #expect(Set(errors.map { $0.filePath }) == Set([a, c])) + } + } + + @Test + static func sortedFileSequence() async throws { + try await withTemporaryDirectory { dir in + let (a, b, c) = try create3Files(dir: dir) + + let seq = FileBasedMessageToAppendSequence( + paths: [ + a, + b, + c, + ], + options: [.sort] // <-- Messages should be sorted by date + ) + + let messages: [MessageToAppend] = try await seq.reduce(into: []) { + $0.append($1) + } + + #expect( + messages.map { $0.id } == [a, c, b] + ) + #expect( + messages.map { $0.messageID } == [ + MessageID(""), + MessageID(""), + MessageID(""), + ] + ) + + #expect( + messages.map { $0.serverMessageDate } == [ + ServerMessageDate( + .init(year: 2016, month: 9, day: 13, hour: 11, minute: 8, second: 4, timeZoneMinutes: 0)! + ), + ServerMessageDate( + .init(year: 2024, month: 4, day: 25, hour: 14, minute: 41, second: 32, timeZoneMinutes: 0)! + ), + ServerMessageDate( + .init(year: 2024, month: 4, day: 30, hour: 14, minute: 31, second: 7, timeZoneMinutes: 0)! + ), + ], + ) + } + } + + @Test + static func unsortedFileSequence() async throws { + try await withTemporaryDirectory { dir in + let (a, b, c) = try create3Files(dir: dir) + + let seq = FileBasedMessageToAppendSequence( + paths: [ + a, + b, + c, + ], + options: [] // <-- no sorting + ) + + let messages: [MessageToAppend] = try await seq.reduce(into: []) { + $0.append($1) + } + + #expect( + messages.map { $0.id } == [a, b, c] + ) + #expect( + messages.map { $0.messageID } == [ + MessageID(""), + MessageID(""), + MessageID(""), + ] + ) + + #expect( + messages.map { $0.serverMessageDate } == [ + ServerMessageDate( + .init(year: 2016, month: 9, day: 13, hour: 11, minute: 8, second: 4, timeZoneMinutes: 0)! + ), + ServerMessageDate( + .init(year: 2024, month: 4, day: 30, hour: 14, minute: 31, second: 7, timeZoneMinutes: 0)! + ), + ServerMessageDate( + .init(year: 2024, month: 4, day: 25, hour: 14, minute: 41, second: 32, timeZoneMinutes: 0)! + ), + ], + ) + } + } + + @Test + static func fileSequenceSkippingInvalid() async throws { + try await withTemporaryDirectory { dir in + let all = try createFiles( + dir: dir, + content: [ + #""" + This is not an email + """#, + #""" + From: b@example.apple.com + Subject: B + Message-id: + Date: Tue, 30 Apr 2024 14:31:07 +0000 + + b + """#, + ] + ) + try #require(all.count == 2) + let a = all[0] + let b = all[1] + let c = dir.appending("does-not-exist") + + let seq = FileBasedMessageToAppendSequence( + paths: [ + a, + b, + c, + ], + options: [.skipErrors] + ) + + let messages: [MessageToAppend] = try await seq.reduce(into: []) { + $0.append($1) + } + + #expect( + messages.map { $0.id } == [b] + ) + #expect( + messages.map { $0.messageID } == [ + MessageID("") + ] + ) + + #expect( + messages.map { $0.serverMessageDate } == [ + ServerMessageDate( + .init(year: 2024, month: 4, day: 30, hour: 14, minute: 31, second: 7, timeZoneMinutes: 0)! + ) + ], + ) + } + } + + struct UnableToCreateDirectory: Swift.Error {} + + @Test + static func fileSequenceWithDirectories() async throws { + try await withTemporaryDirectory { topLevelDir in + let dirA = topLevelDir.appending("A") + try dirA.withPlatformString { path in + guard mkdir(path, 0o777) == 0 else { throw UnableToCreateDirectory() } + } + + let dirB = topLevelDir.appending("B") + try dirB.withPlatformString { path in + guard mkdir(path, 0o777) == 0 else { throw UnableToCreateDirectory() } + } + + let filesA = try createFiles( + dir: dirA, + content: [ + #""" + From: b@example.apple.com + Subject: B + Message-id: + Date: Tue, 30 Apr 2024 14:31:07 +0000 + + b + """# + ] + ) + try #require(filesA.count == 1) + let b = filesA[0] + + let filesB = try createFiles( + dir: dirB, + content: [ + #""" + This is not an email + """#, + #""" + From: a@example.apple.com + Subject: A + Message-id: + Date: Tue, 13 Sep 2016 04:08:04 -0700 + + a + """#, + #""" + From: c@example.apple.com + Subject: C + Message-id: + Date: Thu, 25 Apr 2024 16:41:32 +0200 + + c + """#, + ] + ) + try #require(filesB.count == 3) + let a = filesB[1] + let c = filesB[2] + + let seq = FileBasedMessageToAppendSequence( + paths: [ + dirA, + dirB, + ], + options: [.skipErrors, .sort] + ) + + let messages: [MessageToAppend] = try await seq.reduce(into: []) { + $0.append($1) + } + + #expect( + messages.map { $0.id } == [a, c, b] + ) + } + } + + @Test + static func flagExtraction_fromOptions() async throws { + try await withTemporaryDirectory { dir in + let (file, _, _) = try create3Files(dir: dir) + let flags: [NIOIMAP.Flag] = [.seen, .flagged, .answered] + + let seq = FileBasedMessageToAppendSequence( + paths: [file], + options: [.flags(flags)] + ) + + let message = try await seq.first { _ in true } + #expect(message?.flags == flags) + } + } + + @Test + static func flagExtraction_noFlags() async throws { + try await withTemporaryDirectory { dir in + let (file, _, _) = try create3Files(dir: dir) + + let seq = FileBasedMessageToAppendSequence( + paths: [file], + options: [] + ) + + let message = try await seq.first { _ in true } + #expect(message?.flags == nil || message?.flags?.isEmpty == true) + } + } + + @Test + static func flagExtraction_emptyFlags() async throws { + try await withTemporaryDirectory { dir in + let (file, _, _) = try create3Files(dir: dir) + + let seq = FileBasedMessageToAppendSequence( + paths: [file], + options: [.flags([])] + ) + + let message = try await seq.first { _ in true } + #expect(message?.flags == nil) + } + } + + @Test + static func flagExtraction_multipleFiles() async throws { + try await withTemporaryDirectory { dir in + let (a, b, c) = try create3Files(dir: dir) + let flags: [NIOIMAP.Flag] = [.seen, .draft] + + let seq = FileBasedMessageToAppendSequence( + paths: [a, b, c], + options: [.flags(flags)] + ) + + let messages: [MessageToAppend] = try await seq.reduce(into: []) { + $0.append($1) + } + + // All messages should have the same flags + for message in messages { + #expect(message.flags == flags) + } + } + } + + @Test + static func flagExtraction_customFlags() async throws { + try await withTemporaryDirectory { dir in + let (file, _, _) = try create3Files(dir: dir) + let customFlag = NIOIMAP.Flag("\\CustomFlag") + let recentFlag = NIOIMAP.Flag("\\Recent") + let flags: [NIOIMAP.Flag] = [.seen, customFlag, recentFlag] + + let seq = FileBasedMessageToAppendSequence( + paths: [file], + options: [.flags(flags)] + ) + + let message = try await seq.first { _ in true } + #expect(message?.flags == flags) + } + } + + @Test + static func flagExtraction_mixedOptions() async throws { + try await withTemporaryDirectory { dir in + let (file, _, _) = try create3Files(dir: dir) + let flags: [NIOIMAP.Flag] = [.flagged, .answered] + + let seq = FileBasedMessageToAppendSequence( + paths: [file], + options: [.skipErrors, .sort, .flags(flags), .createMailbox([])] + ) + + let message = try await seq.first { _ in true } + #expect(message?.flags == flags) + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AsyncReadFileTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AsyncReadFileTests.swift new file mode 100644 index 00000000..ce5e4e3b --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AsyncReadFileTests.swift @@ -0,0 +1,72 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import NIOCore +@testable import NIOIMAP +import SystemPackage +import Testing +@testable import IMAPToolLib + +@Suite("Async Read File") +private enum AsyncReadFileTests { + static func createFile( + dir: FilePath, + name: String, + content: String + ) throws -> FilePath { + let path = dir.appending(name) + try Data(content.utf8).write(to: URL(path)) + return path + } + + @Test + static func filePathComponent() async throws { + try await withTemporaryDirectory { dir in + let count = 10 + + let paths = try (1...count).map { index -> (Int, FilePath) in + ( + index, + try createFile( + dir: dir, + name: "\(index)", + content: "\(index)" + ) + ) + } + + let all = try await withThrowingTaskGroup { group in + for element in paths { + let index = element.0 + let path = element.1 + group.addTask { + let buffer = try await ByteBuffer(asyncContentsOf: path) + let s = String(buffer: buffer) + return (index, s) + } + } + + var result: [(Int, String)] = [] + for try await element in group { + result.append(element) + } + result.sort(by: { $0.0 < $1.0 }) + return result.map { $0.1 } + } + + #expect(all == (1...count).map { "\($0)" }) + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AuthenticationTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AuthenticationTests.swift new file mode 100644 index 00000000..970f2245 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/AuthenticationTests.swift @@ -0,0 +1,470 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPCommands +import Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite("Authentication", .timeLimit(.minutes(1))) +private struct AuthenticationTests { + @Test + func testLogin() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + .init( + command: .capability, + untagged: [ + .capabilityData([.imap4rev1, .imap4, .authenticate(AuthenticationMechanism("FOOBAR")!)]) + ], + completion: .ok(.init(text: "Done")) + ), + .init( + command: .login(username: "john", password: "secret"), + completion: .ok(.init(text: "Welcome to the test server")) + ), + .init( + command: .capability, + untagged: [.capabilityData([.imap4rev1, .imap4, .move])], + completion: .ok(.init(text: "Done")) + ), + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func testSASL() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + .init( + command: .capability, + untagged: [ + .capabilityData([.imap4rev1, .imap4, .saslIR, .authenticate(.plain)]) + ], + completion: .ok(.init(text: "Capabilities Done")) + ), + .init( + command: .authenticate( + mechanism: .plain, + initialResponse: InitialResponse( + ByteBuffer(bytes: [ + 0x0, 0x6a, 0x6f, 0x68, 0x6e, 0x0, 0x73, 0x65, 0x63, 0x72, 0x65, 0x74, + ]) + ) + ), + completion: .ok(.init(text: "Welcome to the test server")) + ), + .init( + command: .capability, + untagged: [.capabilityData([.imap4rev1, .imap4, .move])], + completion: .ok(.init(text: "Capabilities Done 2")) + ), + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func testSASL_capabilitiesInResponse() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + .init( + command: .capability, + untagged: [ + .capabilityData([.imap4rev1, .imap4, .saslIR, .authenticate(.plain)]) + ], + completion: .ok(.init(text: "Capabilities Done")) + ), + .init( + command: .authenticate( + mechanism: .plain, + initialResponse: InitialResponse( + ByteBuffer(bytes: [ + 0x0, 0x6a, 0x6f, 0x68, 0x6e, 0x0, 0x73, 0x65, 0x63, 0x72, 0x65, 0x74, + ]) + ) + ), + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ), + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func testSASL_capabilitiesInGreetingAndResponse() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .saslIR, .authenticate(.plain)]), + text: "Hello" + ) + ), + expectedCommands: [ + .init( + command: .authenticate( + mechanism: .plain, + initialResponse: InitialResponse( + ByteBuffer(bytes: [ + 0x0, 0x6a, 0x6f, 0x68, 0x6e, 0x0, 0x73, 0x65, 0x63, 0x72, 0x65, 0x74, + ]) + ) + ), + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func testSASL_noIR() async throws { + // If the server doesn’t support SASL-IR, we’ll have to wait + // for an authentication challenge and then send the IR + // in the continuation response: + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .authenticate(.plain)]), + text: "Hello" + ) + ), + expectedCommands: [ + .init( + part: .command( + .authenticate( + mechanism: .plain, + initialResponse: nil + ) + ), + responses: [ + .authenticationChallenge(ByteBuffer(string: "Go ahead")) + ], + completion: nil + ), + .init( + part: .continuationResponse( + ByteBuffer(bytes: [ + 0x0, 0x6a, 0x6f, 0x68, 0x6e, 0x0, 0x73, 0x65, 0x63, 0x72, 0x65, 0x74, + ]) + ), + responses: [], + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ), + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func testThatItFailsWhenTheServerDoesNotReturnCapabilities() async throws { + await TestServer.runSingleConnectionServer( + greeting: .ok(.init(text: "Hello")), + expectedCommands: [ + .init( + command: .capability, + untagged: [], // <--- no capabilities + completion: .ok(.init(text: "Done")) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + _ = await #expect( + throws: AuthenticationError(message: "Server did not return Capabilities") + ) { + try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + } + } + } + } + + @Test + func login() async throws { + // If the server doesn’t support SASL PLAIN, we’ll have + // use LOGIN + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4]), + text: "Hello" + ) + ), + expectedCommands: [ + .init( + part: .command(.login(username: "john", password: "secret")), + responses: [], + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func forceLogin() async throws { + // Even though the server advertises AUTH=PLAIN, `.login` must use LOGIN. + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .saslIR, .authenticate(.plain)]), + text: "Hello" + ) + ), + expectedCommands: [ + .init( + command: .login(username: "john", password: "secret"), + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .login + ) + + #expect(result.responseText == "Welcome to the test server") + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } + + @Test + func forceLoginWithSASLCredential() async throws { + // A SASL credential has no username and password, so LOGIN can’t be used. + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .authenticate(.plain)]), + text: "Hello" + ) + ), + expectedCommands: [] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + _ = await #expect( + throws: AuthenticationError( + message: "The given credential can only be used with AUTHENTICATE, not LOGIN." + ) + ) { + try await connection.authenticate( + greeting: greeting, + credential: .sasl(mechanism: .plain, response: Data([0x41])), + disableSASLIR: false, + method: .login + ) + } + } + } + } + + @Test + func loginDisabled() async throws { + // LOGINDISABLED (RFC 3501) prohibits LOGIN, so don’t even try. + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .loginDisabled]), + text: "Hello" + ) + ), + expectedCommands: [] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + _ = await #expect( + throws: AuthenticationError( + message: "The server advertises LOGINDISABLED, which prohibits the LOGIN command." + ) + ) { + try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + } + } + } + } + + @Test + func loginDisabledDoesNotAffectAUTHENTICATE() async throws { + // LOGINDISABLED only prohibits LOGIN. When the mechanism is advertised, + // `.automatic` must still authenticate. + await TestServer.runSingleConnectionServer( + greeting: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .loginDisabled, .saslIR, .authenticate(.plain)]), + text: "Hello" + ) + ), + expectedCommands: [ + .init( + command: .authenticate( + mechanism: .plain, + initialResponse: InitialResponse( + ByteBuffer(bytes: [ + 0x0, 0x6a, 0x6f, 0x68, 0x6e, 0x0, 0x73, 0x65, 0x63, 0x72, 0x65, 0x74, + ]) + ) + ), + completion: .ok( + .init( + code: .capability([.imap4rev1, .imap4, .move]), + text: "Welcome to the test server" + ) + ) + ) + ] + ) { path in + try await IMAPConnection.withConnection( + configuration: IMAPConnection.Configuration(path) + ) { greeting, connection in + let result = try await connection.authenticate( + greeting: greeting, + credential: .username("john", password: "secret"), + disableSASLIR: false, + method: .automatic + ) + + #expect(result.capabilities == [.imap4rev1, .imap4, .move]) + } + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/BatchSizeTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/BatchSizeTests.swift new file mode 100644 index 00000000..4d25f332 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/BatchSizeTests.swift @@ -0,0 +1,84 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import NIOIMAP +import Testing + +@Suite +private enum BatchSizeTests { + @Test(arguments: [0, -1]) + static func rejectsNonPositive(_ count: Int) { + #expect(BatchSize(count) == nil) + } + + struct MessageLimitFixture: Sendable, CustomTestStringConvertible { + var capabilities: [Capability] + var expected: BatchSize + + var testDescription: String { "\(capabilities)" } + } + + @Test(arguments: [ + MessageLimitFixture(capabilities: [], expected: 1_000), + MessageLimitFixture(capabilities: [.messageLimit(999)], expected: 1_000), + MessageLimitFixture(capabilities: [.messageLimit(1_000)], expected: 1_000), + MessageLimitFixture(capabilities: [.messageLimit(10_000)], expected: 10_000), + MessageLimitFixture(capabilities: [Capability("MESSAGELIMIT=4294967295")], expected: 4_294_967_295), + ]) + static func messageLimit(_ fixture: MessageLimitFixture) { + #expect(BatchSize(capabilities: fixture.capabilities) == fixture.expected) + } + + /// Missing, unparsable, or out-of-range `MESSAGELIMIT` falls back to `minimum`. + @Test(arguments: [ + Capability("MESSAGELIMIT"), + Capability("MESSAGELIMIT=abc"), + Capability("MESSAGELIMIT=0"), + Capability("MESSAGELIMIT=-5000"), + Capability("MESSAGELIMIT=4294967296"), + Capability("MESSAGELIMIT=99999999999"), + ]) + static func invalidMessageLimit(_ capability: Capability) { + #expect(BatchSize(capabilities: [capability]) == .minimum) + } + + struct PartialRangeFixture: Sendable, CustomTestStringConvertible { + var size: BatchSize + var batch: Int + var expected: ClosedRange + + var testDescription: String { "\(size) #\(batch)" } + } + + @Test(arguments: [ + PartialRangeFixture(size: 1_000, batch: 0, expected: 1...1_000), + PartialRangeFixture(size: 1_000, batch: 1, expected: 1_001...2_000), + PartialRangeFixture(size: 1_200, batch: 2, expected: 2_401...3_600), + PartialRangeFixture(size: 1, batch: 0, expected: 1...1), + PartialRangeFixture(size: 1, batch: 4, expected: 5...5), + // End clamped to `SequenceNumber.max`: + PartialRangeFixture(size: 3_000_000_000, batch: 1, expected: 3_000_000_001...4_294_967_295), + ]) + static func partialRange(_ fixture: PartialRangeFixture) { + #expect(fixture.size.partialRange(batch: fixture.batch) == fixture.expected) + } + + /// A batch size above `UInt32.max / 2` must not overflow past the last batch. + @Test + static func partialFetchBatches_hugeBatchSize() { + let batches = PartialFetchBatches(last: 5, batchSize: 3_000_000_000) + #expect(Array(batches) == [.partialLast(.last(1...5))]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/CreateMailboxTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/CreateMailboxTests.swift new file mode 100644 index 00000000..b35759cd --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/CreateMailboxTests.swift @@ -0,0 +1,208 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPCommands +@testable import IMAPToolLib +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite("Create Mailbox") +struct CreateMailboxTests { + @Test + static func endToEnd() async throws { + let connection = try TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .create("foo", []), + untagged: [] + ), + .init( + command: .listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(string: "foo")), + [] + ), + untagged: [ + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .hasNoChildren + ], + path: MailboxPath( + name: "foo", + pathSeparator: "." + ), + extensions: [:] + ) + ) + ) + ] + ), + .init( + command: .status( + "foo", + [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ] + ), + untagged: [ + .mailboxData( + .status( + "foo", + MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ) + ] + ), + ] + ) + + let info = try await connection.createIfNeededAndList( + capabilities: [.imap4rev1, .condStore], + mailbox: .create("foo", []) + ) + + #expect( + try info + == MailboxInfoAndStatus( + path: MailboxPath( + name: "foo", + pathSeparator: "." + ), + attributes: [ + .hasNoChildren + ], + status: MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ) + } + + @Test + static func endToEnd_alreadyExists() async throws { + let connection = try TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(string: "foo")), + [] + ), + untagged: [ + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .hasNoChildren + ], + path: MailboxPath( + name: "foo", + pathSeparator: "." + ), + extensions: [:] + ) + ) + ) + ] + ), + .init( + command: .status( + "foo", + [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ] + ), + untagged: [ + .mailboxData( + .status( + "foo", + MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ) + ] + ), + ] + ) + + let info = try await connection.createIfNeededAndList( + capabilities: [.imap4rev1, .condStore], + mailbox: .alreadyExists("foo") + ) + + #expect( + try info + == MailboxInfoAndStatus( + path: MailboxPath( + name: "foo", + pathSeparator: "." + ), + attributes: [ + .hasNoChildren + ], + status: MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMailboxTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMailboxTests.swift new file mode 100644 index 00000000..5d51da03 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMailboxTests.swift @@ -0,0 +1,100 @@ +//===----------------------------------------------------------------------===// +// +// 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 Testing +import IMAPCommands +@testable import IMAPToolLib +import NIOIMAP + +@Suite +enum DeleteMailboxTests { + + // MARK: - Happy Path Tests + + @Test + static func deleteMailbox_success() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .delete("TestMailbox"), + responses: [], + completion: .ok(.init(text: "DELETE completed")) + ) + ]) + + try await connection.deleteMailbox( + capabilities: [.imap4rev1], + mailbox: "TestMailbox" + ) + + await #expect(connection.expectedCommands == []) + } + + @Test + static func deleteMailbox_nestedMailbox() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .delete("Projects/Work/Archive"), + responses: [], + completion: .ok(.init(text: "DELETE completed")) + ) + ]) + + try await connection.deleteMailbox( + capabilities: [.imap4rev1], + mailbox: "Projects/Work/Archive" + ) + + await #expect(connection.expectedCommands == []) + } + + // MARK: - Error Handling Tests + + @Test + static func deleteMailbox_notFound() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .delete("NonExistentMailbox"), + responses: [], + completion: .no(.init(text: "Mailbox does not exist")) + ) + ]) + + await #expect(throws: TaggedResponse.StateNotOK.self) { + _ = try await connection.deleteMailbox( + capabilities: [.imap4rev1], + mailbox: "NonExistentMailbox" + ) + } + + await #expect(connection.expectedCommands == []) + } + + @Test + static func deleteMailbox_specialCharacters() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .delete("Special & Characters (Test)"), + responses: [], + completion: .ok(.init(text: "DELETE completed")) + ) + ]) + + try await connection.deleteMailbox( + capabilities: [.imap4rev1], + mailbox: "Special & Characters (Test)" + ) + + await #expect(connection.expectedCommands == []) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMessagesTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMessagesTests.swift new file mode 100644 index 00000000..5704fc6b --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DeleteMessagesTests.swift @@ -0,0 +1,64 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum DeleteMessagesTests { + @Test + static func test() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidStore( + .set([309_727, 967_986]), + [], + .flags( + StoreFlags.add( + silent: true, + list: [.deleted] + ) + ) + ), + responses: [], + completion: .ok(.init(text: "Updated")) + ), + .init( + command: .expunge, + responses: [ + .untagged(.messageData(.expunge(44))), + .untagged(.messageData(.expunge(55))), + ], + completion: .ok(.init(text: "Done")) + ), + ]) + try await connection.deleteMessages( + uids: [309_727, 967_986] + ) + } + + @Test + static func empty() async throws { + let connection = TestConnection( + expectedCommands: [] + ) + try await connection.deleteMessages( + uids: [] + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryTests.swift new file mode 100644 index 00000000..0e0baa8b --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryTests.swift @@ -0,0 +1,246 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import NIOCore +import NIOIMAP +import SystemPackage +import Testing +@testable import IMAPToolLib + +@Suite +enum DownloadDirectoryTests { + @Test + static func filePathComponent() async throws { + #expect( + FilePath.Component(DownloadDirectory.Filename.message(1, 1)).description + == "1.01.message" + ) + #expect( + FilePath.Component(DownloadDirectory.Filename.message(790_954, 212_451)).description + == "790954.033de3.message" + ) + #expect( + FilePath.Component(DownloadDirectory.Filename.message(121_047_307, 8_445_624)).description + == "121047307.80deb8.message" + ) + #expect( + FilePath.Component(DownloadDirectory.Filename.temporary("12bt3x434A56")).description + == ".12bt3x434A56.message" + ) + } + + @Test(arguments: [ + ( + "790954.033de3.message", + DownloadDirectory.Filename.message(790_954, 212_451) + ), + ( + "1.01.message", + DownloadDirectory.Filename.message(1, 1) + ), + ( + ".12bt3x434A56.message", + DownloadDirectory.Filename.temporary("12bt3x434A56") + ), + ]) + static func initFromFilename( + fixture: (String, DownloadDirectory.Filename) + ) async throws { + var name = fixture.0 + name.withUTF8 { buffer in + #expect( + DownloadDirectory.Filename(regularFilename: buffer.span) + == fixture.1 + ) + } + } + + /// Malformed filenames — in particular ones whose UID or UID-validity would + /// overflow `UInt32` — must be rejected (returning `nil`) without trapping, + /// so a stray file in the download directory is simply skipped. + @Test(arguments: [ + "9999999999.0001.message", // UID overflows UInt32 + "4294967296.01.message", // UID = UInt32.max + 1 + "0.01.message", // UID 0 is invalid + "1.ffffffffff.message", // UID-validity overflows UInt32 + "1.0100000000.message", // UID-validity = UInt32.max + 1 + ]) + static func initFromFilenameRejectsOverflow(name: String) async throws { + var name = name + name.withUTF8 { buffer in + #expect(DownloadDirectory.Filename(regularFilename: buffer.span) == nil) + } + } + + @Test + static func directoryEnumeration() async throws { + try await withTemporaryDirectory { dir in + func create(name: FilePath.Component) throws { + let path = dir.appending(name) + try Data().write(to: URL(path)) + } + + try create(name: "790954.033de3.message") + try create(name: ".12bt3x434A56.message") + try create(name: "121047307.80deb8.message") + try create(name: ".aXmooQRwysCmrgQG.message") + + var all = Set() + var count = 0 + try DownloadDirectory.withFilenames(in: dir) { + count += 1 + all.insert($0) + } + + #expect(count == 4) + #expect( + all == [ + .message(790_954, 212_451), + .message(121_047_307, 8_445_624), + .temporary("12bt3x434A56"), + .temporary("aXmooQRwysCmrgQG"), + ] + ) + } + } + + @Test + static func deletingOtherFiles() async throws { + try await withTemporaryDirectory { dir in + func create(name: FilePath.Component) throws { + let path = dir.appending(name) + try Data().write(to: URL(path)) + } + + try create(name: "790954.033de3.message") + try create(name: ".12bt3x434A56.message") + try create(name: "121047307.80deb8.message") + try create(name: ".aXmooQRwysCmrgQG.message") + try create(name: "545548.033de3.message") + + let sut = try DownloadDirectory.openDeletingInvalidFiles( + directory: dir, + uidValidity: 212_451, + deleteUnknown: true + ) + + #expect(fileExists(at: dir.appending("790954.033de3.message"))) + #expect(!fileExists(at: dir.appending(".12bt3x434A56.message"))) + #expect(!fileExists(at: dir.appending("121047307.80deb8.message"))) + #expect(!fileExists(at: dir.appending(".aXmooQRwysCmrgQG.message"))) + #expect(fileExists(at: dir.appending("545548.033de3.message"))) + + #expect(sut.root == dir) + #expect(sut.downloadedUIDs == [790_954, 545_548]) + } + } + + @Test + static func notDeletingOtherFiles() async throws { + try await withTemporaryDirectory { dir in + func create(name: FilePath.Component) throws { + let path = dir.appending(name) + try Data().write(to: URL(path)) + } + + try create(name: "790954.033de3.message") + try create(name: ".12bt3x434A56.message") + try create(name: "121047307.80deb8.message") + try create(name: ".aXmooQRwysCmrgQG.message") + try create(name: "545548.033de3.message") + + let sut = try DownloadDirectory.openDeletingInvalidFiles( + directory: dir, + uidValidity: 212_451, + deleteUnknown: false + ) + + #expect(fileExists(at: dir.appending("790954.033de3.message"))) + #expect(fileExists(at: dir.appending(".12bt3x434A56.message"))) + #expect(fileExists(at: dir.appending("121047307.80deb8.message"))) + #expect(fileExists(at: dir.appending(".aXmooQRwysCmrgQG.message"))) + #expect(fileExists(at: dir.appending("545548.033de3.message"))) + + #expect(sut.root == dir) + #expect(sut.downloadedUIDs == [790_954, 545_548]) + } + } + + @Test + static func fileWriter() async throws { + try await withTemporaryDirectory { dir in + print("A: ", String(decoding: dir)) + + let sut = try DownloadDirectory.openDeletingInvalidFiles( + directory: dir, + uidValidity: 212_451, + deleteUnknown: false + ) + + do { + let writer = try sut.makeWriter(uid: 790_954) + writer.write(ByteBuffer(bytes: [0x1, 0x2, 0x3, 0x4])) + writer.write(ByteBuffer(bytes: [0xa1, 0xa2, 0xa3, 0xa4])) + writer.closeAndSucceed() + await writer.waitForCompletion() + + #expect(fileExists(at: dir.appending("790954.033de3.message"))) + + #expect( + Data(contentsOf: dir.appending("790954.033de3.message")) + == Data([0x1, 0x2, 0x3, 0x4, 0xa1, 0xa2, 0xa3, 0xa4]) + ) + } + + do { + let writer = try sut.makeWriter(uid: 545_548) + writer.write(ByteBuffer(bytes: [0x1, 0x2, 0x3, 0x4])) + writer.write(ByteBuffer(bytes: [0xa1, 0xa2, 0xa3, 0xa4])) + writer.closeAndFail() // <- Failing here. + await writer.waitForCompletion() + + #expect(!fileExists(at: dir.appending("545548.033de3.message"))) + } + } + } +} + +// MARK: - + +func fileExists(at path: FilePath) -> Bool { + (try? URL(path).checkResourceIsReachable()) == true +} + +extension Data { + init?(contentsOf path: FilePath) { + guard + let data = try? Data(contentsOf: URL(path)) + else { return nil } + self = data + } +} + +extension String { + init?(contentsOf path: FilePath) { + guard + let data = Data(contentsOf: path) + else { return nil } + self = String(decoding: data, as: UTF8.self) + } + + func write(to path: FilePath) throws { + try Data(utf8).write(to: URL(path)) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryWriterStallTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryWriterStallTests.swift new file mode 100644 index 00000000..935254ef --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadDirectoryWriterStallTests.swift @@ -0,0 +1,90 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import NIOCore +@testable import IMAPToolLib +import NIOIMAP +import Synchronization +import SystemPackage +import Testing + +@Suite("DownloadDirectory.Writer stall") +enum DownloadDirectoryWriterStallTests { + + /// Bug #4 (regression): `waitForCompletion()` must return even when the writer has + /// already finished everything — including moving the file into place — before it is + /// called. The original DispatchIO implementation parked a continuation that the + /// already-fired, one-shot cleanup handler could never resume, stalling the download. + /// + /// This test forces that ordering by waiting until the file exists at its final path + /// before calling `waitForCompletion()`. + @Test(.timeLimit(.minutes(1))) + static func waitForCompletionDoesNotStallWhenCleanupRanFirst() async throws { + try await withTemporaryDirectory { dir in + let uid: UID = 42 + let uidValidity: UIDValidity = 1 + let finalPath = dir.appending(.message(uid, uidValidity)) + + let setupError = Mutex(nil) + let reachedWait = Mutex(false) + + let finished = await finishesWithoutStalling(within: 10) { + do { + let tempPath = dir.appending(.temporary("stalltest.\(uid)")) + let writer = try DownloadDirectory.Writer( + uid: uid, + path: tempPath, + finalPath: finalPath + ) + writer.write(ByteBuffer(string: "From: test\r\n\r\nbody\r\n")) + writer.closeAndSucceed() + + // Wait until the writing task has moved the file into place, so that + // it has finished before `waitForCompletion()` is called. + var attempts = 0 + while !FileManager.default.fileExists(atPath: finalPath.string) { + attempts += 1 + if attempts > 1_000 { + setupError.withLock { $0 = "writing task never ran (final file was not created)" } + return + } + try await Task.sleep(for: .milliseconds(10)) + } + // Let the writing task finish completely. + try await Task.sleep(for: .milliseconds(50)) + + reachedWait.withLock { $0 = true } + // With the bug, this parked a continuation that nothing could resume. + await writer.waitForCompletion() + } catch { + setupError.withLock { $0 = "\(error)" } + } + } + + #expect( + setupError.withLock { $0 } == nil, + "Test setup failed: \(setupError.withLock { $0 } ?? "")" + ) + #expect( + reachedWait.withLock { $0 }, + "Test never reached waitForCompletion()." + ) + #expect( + finished, + "Writer.waitForCompletion() stalled after the writer had already completed." + ) + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadTests.swift new file mode 100644 index 00000000..ba084042 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/DownloadTests.swift @@ -0,0 +1,224 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum DownloadTests { + @Test + static func downloadingUIDs() async throws { + let section = SectionSpecifier(part: [], kind: .complete) + + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidFetch( + .set(UIDSetNonEmpty(range: 309_727...309_727)), + [.uid, .bodySection(peek: true, section, nil)], + [] + ), + fetchResponses: [ + .start(50_683), + .simpleAttribute(.uid(309_727)), + .streamingBegin(kind: .body(section: section, offset: nil), byteCount: 10), + .streamingBytes(ByteBuffer(string: "0123456")), + .streamingBytes(ByteBuffer(string: "789")), + .streamingEnd, + .finish, + ], + completion: .ok(.init(text: "Done")) + ), + .init( + command: .uidFetch( + .set(UIDSetNonEmpty(range: 967_986...967_986)), + [.uid, .bodySection(peek: true, SectionSpecifier(part: [], kind: .complete), nil)], + [] + ), + fetchResponses: [ + .start(81_434), + .simpleAttribute(.uid(967_986)), + .streamingBegin(kind: .body(section: section, offset: nil), byteCount: 10), + .streamingBytes(ByteBuffer(string: "abcdefghij")), + .streamingEnd, + .finish, + ], + completion: .ok(.init(text: "Done")) + ), + ] + ) + try await withTemporaryDirectory { root in + var dir = try DownloadDirectory.openDeletingInvalidFiles( + directory: root, + uidValidity: 543, + deleteUnknown: false + ) + try await connection.download( + uids: [309_727, 967_986], + into: &dir + ) + + #expect(dir.downloadedUIDs == [309_727, 967_986]) + #expect(fileExists(at: root.appending("309727.021f.message"))) + #expect(fileExists(at: root.appending("967986.021f.message"))) + + #expect(String(contentsOf: root.appending("309727.021f.message")) == "0123456789") + #expect(String(contentsOf: root.appending("967986.021f.message")) == "abcdefghij") + } + } + + @Test + static func skippingAlreadyExistingUIDs() async throws { + // Should not download UID 309_727 because it already exists. + let section = SectionSpecifier(part: [], kind: .complete) + + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidFetch( + .set(UIDSetNonEmpty(range: 967_986...967_986)), + [.uid, .bodySection(peek: true, SectionSpecifier(part: [], kind: .complete), nil)], + [] + ), + fetchResponses: [ + .start(81_434), + .simpleAttribute(.uid(967_986)), + .streamingBegin(kind: .body(section: section, offset: nil), byteCount: 10), + .streamingBytes(ByteBuffer(string: "abcdefghij")), + .streamingEnd, + .finish, + ], + completion: .ok(.init(text: "Done")) + ) + ]) + try await withTemporaryDirectory { root in + try "0123456789".write(to: root.appending("309727.021f.message")) + var dir = try DownloadDirectory.openDeletingInvalidFiles( + directory: root, + uidValidity: 543, + deleteUnknown: false + ) + #expect(dir.downloadedUIDs == [309_727]) + + try await connection.download( + uids: [309_727, 967_986], + into: &dir + ) + + #expect(dir.downloadedUIDs == [309_727, 967_986]) + #expect(fileExists(at: root.appending("309727.021f.message"))) + #expect(fileExists(at: root.appending("967986.021f.message"))) + + #expect(String(contentsOf: root.appending("309727.021f.message")) == "0123456789") + #expect(String(contentsOf: root.appending("967986.021f.message")) == "abcdefghij") + } + } + + @Test + static func downloadingNoUIDs() async throws { + let connection = TestConnection(expectedCommands: []) + try await withTemporaryDirectory { root in + try "0123456789".write(to: root.appending("309727.021f.message")) + try "abcdefghij".write(to: root.appending("967986.021f.message")) + + var dir = try DownloadDirectory.openDeletingInvalidFiles( + directory: root, + uidValidity: 543, + deleteUnknown: false + ) + #expect(dir.downloadedUIDs == [309_727, 967_986]) + + try await connection.download( + uids: [309_727, 967_986], + into: &dir + ) + + #expect(dir.downloadedUIDs == [309_727, 967_986]) + #expect(fileExists(at: root.appending("309727.021f.message"))) + #expect(fileExists(at: root.appending("967986.021f.message"))) + + #expect(String(contentsOf: root.appending("309727.021f.message")) == "0123456789") + #expect(String(contentsOf: root.appending("967986.021f.message")) == "abcdefghij") + } + } + + @Test + static func downloadingManyUIDs() async throws { + let section = SectionSpecifier(part: [], kind: .complete) + + let allUIDs = UIDSet([ + 13_719, 15_358, 15_802, 16_274, 19_494, 25_159, 27_002, 34_672, 37_566, 38_755, + 38_787, 40_041, 42_625, 45_739, 49_607, 51_759, 60_241, 74_413, 74_769, 79_327, + 88_869, 93_311, 94_624, 94_799, + 128_233, 183_861, 222_318, 223_884, 349_921, 363_045, 410_554, 480_784, 497_318, 505_423, + 508_061, 549_435, 558_588, 583_859, 611_911, 617_912, 630_519, 727_792, 748_941, 762_112, + 778_651, 787_041, 788_830, 984_143, + ]) + + let expectedCommands: [TestConnection.CommandAndResponses] = + allUIDs + .enumerated() + .map { index, uid in + let seq = SequenceNumber.min.advanced(by: Int64(index)) + let messageA = "message" + let messageB = "-\(uid)" + return TestConnection.CommandAndResponses( + command: .uidFetch( + .set(UIDSetNonEmpty(range: uid...uid)), + [.uid, .bodySection(peek: true, section, nil)], + [] + ), + fetchResponses: [ + .start(seq), + .simpleAttribute(.uid(uid)), + .streamingBegin( + kind: .body(section: section, offset: nil), + byteCount: messageA.utf8.count + messageB.utf8.count + ), + .streamingBytes(ByteBuffer(string: messageA)), + .streamingBytes(ByteBuffer(string: messageB)), + .streamingEnd, + .finish, + ], + completion: .ok(.init(text: "Done \(uid)")) + ) + } + + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: expectedCommands + ) + try await withTemporaryDirectory { root in + var dir = try DownloadDirectory.openDeletingInvalidFiles( + directory: root, + uidValidity: 543, + deleteUnknown: false + ) + try await connection.download( + uids: allUIDs, + into: &dir + ) + + #expect(dir.downloadedUIDs == allUIDs) + for uid in allUIDs { + #expect(fileExists(at: root.appending("\(uid).021f.message")), "\(uid)") + #expect(String(contentsOf: root.appending("\(uid).021f.message")) == "message-\(uid)", "\(uid)") + } + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/EmailMessageTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/EmailMessageTests.swift new file mode 100644 index 00000000..65eb442a --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/EmailMessageTests.swift @@ -0,0 +1,87 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +import Foundation +@testable import IMAPToolLib +import Testing +import SystemPackage + +@Suite("EmailMessage") +private enum EmailMessageTests { + @Test + static func convertLineEndings() throws { + let sut = EmailMessage.convertingLineEndings( + #""" + To: noreply@apple.com + Subject: Test + + Hello + """#.data(using: .utf8)! + ) + + #expect( + Array(sut.data) == [ + 0x54, 0x6F, 0x3A, 0x20, 0x6E, 0x6F, 0x72, 0x65, 0x70, 0x6C, 0x79, 0x40, 0x61, 0x70, 0x70, 0x6C, 0x65, + 0x2E, 0x63, 0x6F, 0x6D, + 0xD, 0xA, + 0x53, 0x75, 0x62, 0x6A, 0x65, 0x63, 0x74, 0x3A, 0x20, 0x54, 0x65, 0x73, 0x74, + 0xD, 0xA, + 0xD, 0xA, + 0x48, 0x65, 0x6C, 0x6C, 0x6F, + ] + ) + } + + @Test + static func findMessageID() throws { + let sut = EmailMessage.convertingLineEndings( + #""" + From: bar@none.com + To: phooey@all.com + Subject: Here's how to do it + Message-ID: <970701.32784@VIers.none.com> + Date: Tue, 10 Jun 2025 21:49:03 +0000 (GMT) + Content-type: text/html; charset=usascii + + + previous message, shows how the approach you propose can be + used to accomplish + """#.data(using: .utf8)! + ) + + #expect(sut.headersOfInterest?.messageID == "<970701.32784@VIers.none.com>") + #expect(sut.headersOfInterest?.date == "Tue, 10 Jun 2025 21:49:03 +0000 (GMT)") + } + + @Test + static func headerIsCRLFCleanWithCRLFEndings() throws { + // The first four line breaks must all be CRLF. + let input = "To: noreply@apple.com\r\nSubject: Test\r\nFrom: x@y.com\r\nDate: now\r\n\r\nHello\n" + .data(using: .utf8)! + #expect(EmailMessage.headerIsCRLFClean(input)) + } + + @Test + static func headerIsNotCRLFCleanWithLFEndings() throws { + let input = "To: noreply@apple.com\nSubject: Test\n\nHello\n".data(using: .utf8)! + #expect(!EmailMessage.headerIsCRLFClean(input)) + } + + @Test + static func headerIsNotCRLFCleanWithBareCR() throws { + let input = "To: noreply@apple.com\rSubject: Test\r\n".data(using: .utf8)! + #expect(!EmailMessage.headerIsCRLFClean(input)) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ExistingMailboxHierarchyTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ExistingMailboxHierarchyTests.swift new file mode 100644 index 00000000..1bba3552 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ExistingMailboxHierarchyTests.swift @@ -0,0 +1,162 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Testing +import NIOIMAP + +@Suite +private enum ExistingMailboxHierarchyTests { + @Test + static func makeMailboxPath_basics() throws { + let sut = try ExistingMailboxHierarchy( + mailboxPaths: [ + .init( + name: .inbox, + pathSeparator: "/" + ), + .init( + name: "a/b", + pathSeparator: "/" + ), + .init( + name: "a", + pathSeparator: "/" + ), + ] + ) + + #expect(sut.bestParent(displayStrings: ["c"]) == nil) + #expect(try sut.makeMailboxPath(displayStrings: ["c"]) == MailboxPath(name: "c", pathSeparator: "/")) + + #expect(sut.bestParent(displayStrings: ["a", "c"])?.mailboxPath.name == "a") + #expect(try sut.makeMailboxPath(displayStrings: ["a", "c"]) == MailboxPath(name: "a/c", pathSeparator: "/")) + + #expect(sut.bestParent(displayStrings: ["a", "b", "c"])?.mailboxPath.name == "a/b") + #expect( + try sut.makeMailboxPath(displayStrings: ["a", "b", "c"]) == MailboxPath(name: "a/b/c", pathSeparator: "/") + ) + + #expect(sut.bestParent(displayStrings: ["foo", "bar"]) == nil) + #expect( + try sut.makeMailboxPath(displayStrings: ["foo", "bar"]) == MailboxPath(name: "foo/bar", pathSeparator: "/") + ) + } + + @Test + static func makeMailboxPath_differentPathSeparators() throws { + let sut = try ExistingMailboxHierarchy( + mailboxPaths: [ + .init( + name: .inbox, + pathSeparator: "/" + ), + .init( + name: "a", + pathSeparator: "." + ), + .init( + name: "b", + pathSeparator: "-" + ), + ] + ) + + #expect(sut.bestParent(displayStrings: ["c"]) == nil) + #expect(try sut.makeMailboxPath(displayStrings: ["c"]) == MailboxPath(name: "c", pathSeparator: "/")) + + #expect(sut.bestParent(displayStrings: ["a", "c"])?.mailboxPath.name == "a") + #expect(try sut.makeMailboxPath(displayStrings: ["a", "c"]) == MailboxPath(name: "a.c", pathSeparator: ".")) + + #expect(sut.bestParent(displayStrings: ["b", "c"])?.mailboxPath.name == "b") + #expect(try sut.makeMailboxPath(displayStrings: ["b", "c"]) == MailboxPath(name: "b-c", pathSeparator: "-")) + + #expect(sut.bestParent(displayStrings: ["a", "c", "d"])?.mailboxPath.name == "a") + #expect( + try sut.makeMailboxPath(displayStrings: ["a", "c", "d"]) == MailboxPath(name: "a.c.d", pathSeparator: ".") + ) + } + + @Test + static func makeMailboxNamesForCreation() throws { + let sut = try ExistingMailboxHierarchy( + mailboxPaths: [ + .init( + name: .inbox, + pathSeparator: "/" + ), + .init( + name: "a", + pathSeparator: "/" + ), + .init( + name: "b", + pathSeparator: "." + ), + ] + ) + + let result = try sut.makeMailboxNamesForCreation([ + .init(namePath: ["a", "b", "c"], parameters: []), + .init(namePath: ["a", "b"], parameters: []), + .init(namePath: ["b", "a"], parameters: []), + ]) + #expect( + result == [ + .create("a/b", []), + .create("b.a", []), + .create("a/b/c", []), + ] + ) + } + + @Test + static func makeMailboxNamesForCreation_withExisting() throws { + let sut = try ExistingMailboxHierarchy( + mailboxPaths: [ + .init( + name: .inbox, + pathSeparator: "/" + ), + .init( + name: "a", + pathSeparator: "/" + ), + .init( + name: "a/b", + pathSeparator: "/" + ), + .init( + name: "b", + pathSeparator: "." + ), + ] + ) + + let result = try sut.makeMailboxNamesForCreation([ + .init(namePath: ["a", "b", "c"], parameters: []), + .init(namePath: ["a", "b"], parameters: []), + .init(namePath: ["b", "a"], parameters: []), + .init(namePath: ["b", "a"], parameters: []), + ]) + #expect( + result == [ + .alreadyExists("a/b"), + .create("b.a", []), + .alreadyExists("b.a"), + .create("a/b/c", []), + ] + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchCountTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchCountTests.swift new file mode 100644 index 00000000..2e1e2a23 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchCountTests.swift @@ -0,0 +1,65 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite("FetchBatch — count honoring") +enum FetchBatchCountTests { + + /// Bug #6 (fixed): On a server without RFC 9394 `PARTIAL`, `makeBoundaryFetchBatch` + /// used an early guard that only inspected `mailboxMessageCount` (not the requested + /// `count`) and short-circuited to `.fixed([UID.min...UID.max])` for small mailboxes. + /// So a `.last(count:)` request on a small mailbox fetched the *entire* mailbox, + /// ignoring `--count`. Now the whole-mailbox shortcut applies only to `.all`, and + /// `.last(count:)` issues a bounded SEARCH for the last `count` messages. + /// + /// Here `BatchSize.minimum` is 1,000, so `batchSize / 2 == 500 > 400`, which + /// previously triggered the over-fetch: `.last(count: 100)` on 400 messages fetched + /// all 400. It now searches sequence numbers `301...*` (the last 100 of 400). + @Test + static func lastCountDoesNotFetchWholeMailbox() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [301...])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged(.mailboxData(.search([512, 4_096], nil))) + ], + completion: .ok(.init(text: "Done searching")) + ) + ]) + let batches = try await connection.makeBatches( + query: .last(count: 100), + mailboxMessageCount: 400, + capabilities: [.imap4rev1] + ) + #expect( + Array(batches) != [.uidRange(.all)], + "Requesting the last 100 of 400 messages must not fetch the entire mailbox." + ) + #expect(Array(batches) == [.uidRange(512...4_096)]) + #expect( + await connection.expectedCommands == [], + "Should have issued the bounded boundary SEARCH for the last 100 messages." + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchMakeBatchesTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchMakeBatchesTests.swift new file mode 100644 index 00000000..134e028a --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchMakeBatchesTests.swift @@ -0,0 +1,455 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +private enum `FetchBatch makeBatches Tests` { + struct MakeBatchesFixture: Sendable, CustomTestStringConvertible { + var name: String + var query: FetchQuery + var mailboxMessageCount: Int + var capabilities: [Capability] + var expectedCommands: [TestConnection.CommandAndResponses] + var expectedBatches: [FetchBatch] + + var testDescription: String { name } + } + + @Test(arguments: [ + MakeBatchesFixture( + name: "plain, RFC 3501, low count, low mailbox count", + query: .last(count: 100), + mailboxMessageCount: 400, + capabilities: [.imap4rev1], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [301...])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [512, 4_096], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(512...4_096) + ] + ), + MakeBatchesFixture( + name: "plain, RFC 3501, low count", + query: .last(count: 100), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [9_901...])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 1_079, 1_283, 2_322, 5_182, 6_006, 7_819, 7_883, 8_070, 8_474, 8_528, + 8_620, 9_807, 10_005, 12_082, 12_597, 12_691, 14_703, 15_888, 16_782, 16_872, + 17_454, 17_555, 19_137, 19_828, 20_042, 20_086, 20_377, 20_431, 21_962, 26_433, + 26_812, 29_345, 30_321, 30_489, 30_888, 31_770, 32_312, 34_426, 34_729, 36_694, + 40_553, 42_606, 45_058, 47_190, 48_397, 49_179, 49_180, 49_465, 49_870, 50_844, + 54_726, 54_832, 57_006, 57_560, 58_010, 58_370, 60_014, 60_205, 60_658, 61_121, + 63_208, 64_805, 65_387, 66_388, 68_296, 69_005, 69_826, 71_466, 72_523, 73_406, + 74_642, 75_624, 76_758, 76_852, 77_549, 77_758, 77_999, 79_296, 80_852, 83_383, + 83_793, 84_020, 85_746, 86_013, 86_383, 87_165, 87_551, 88_094, 88_206, 88_709, + 91_139, 91_531, 92_567, 92_941, 93_030, 93_158, 94_107, 94_577, 94_882, 98_793, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(1_079...98_793) + ] + ), + MakeBatchesFixture( + name: "plain, RFC 3501, larger count", + query: .last(count: 900), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [99_101, 100_000])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 6_987_831, + 9_879_779, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(6_987_831...9_879_779) + ] + ), + MakeBatchesFixture( + name: "plain, RFC 3501, count spanning multiple batches", + query: .last(count: 2_300), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers( + .set( + .init(set: [ + 97_701, + 98_000, + 99_000, + 100_000, + ])! + ) + ), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 1_132_068, + 3_842_087, + 7_706_447, + 9_155_708, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(7_706_448...9_155_708), + .uidRange(3_842_088...7_706_447), + .uidRange(1_132_068...3_842_087), + ] + ), + MakeBatchesFixture( + name: "plain, RFC 3501, count spanning multiple batches, message limit, extended search", + query: .last(count: 2_300), + mailboxMessageCount: 100_000, + capabilities: [ + .imap4rev1, + .messageLimit(2_000), + .extendedSearch, + ], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers( + .set( + .init(set: [ + 97_701, + 98_000, + 100_000, + ])! + ) + ), + charset: nil, + returnOptions: [.all] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), + kind: .uid, + returnData: [ + .all( + .set([ + 3_344_364, + 5_503_918, + 9_920_245, + ]) + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(5_503_919...9_920_245), + .uidRange(3_344_364...5_503_918), + ] + ), + MakeBatchesFixture( + name: "partial, RFC 9394, low count", + query: .last(count: 100), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_200)], + expectedCommands: [], + expectedBatches: [ + .partialLast(.last(1...100)) + ] + ), + MakeBatchesFixture( + name: "partial, RFC 9394", + query: .last(count: 3_000), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_200)], + expectedCommands: [], + expectedBatches: [ + .partialLast(.last(1...1_200)), + .partialLast(.last(1_201...2_400)), + .partialLast(.last(2_401...3_000)), + ] + ), + MakeBatchesFixture( + name: ".uids with Partial, sparse UIDs", + query: .uids([100, 5_000, 10_000]), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_200)], + expectedCommands: [], + expectedBatches: [ + .partialLast(.last(1...3)) + ] + ), + MakeBatchesFixture( + name: ".uids without Partial, sparse UIDs spanning multiple batches", + query: .uids([100, 200, 5_000, 10_000]), + mailboxMessageCount: 20_000, + capabilities: [.imap4rev1], + expectedCommands: [], + expectedBatches: [ + .uidRange(100...10_000) + ] + ), + MakeBatchesFixture( + name: ".all without Partial, multiple batches", + query: .all, + mailboxMessageCount: 2_300, + capabilities: [.imap4rev1], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers( + .set( + .init(set: [ + 1, + 300, + 1_300, + 2_300, + ])! + ) + ), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 100, + 5_000, + 8_000, + 15_000, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(8_001...15_000), + .uidRange(5_001...8_000), + .uidRange(100...5_000), + ] + ), + MakeBatchesFixture( + name: ".all with Partial, multiple batches", + query: .all, + mailboxMessageCount: 2_300, + capabilities: [.imap4rev1, .partial, .messageLimit(1_000)], + expectedCommands: [], + expectedBatches: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + .partialLast(.last(2_001...2_300)), + ] + ), + MakeBatchesFixture( + name: ".uids with Partial, large UID set needing multiple batches", + query: .uids(UIDSet(1...3_000)), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_000)], + expectedCommands: [], + expectedBatches: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + .partialLast(.last(2_001...3_000)), + ] + ), + MakeBatchesFixture( + name: ".all without Partial, empty mailbox", + query: .all, + mailboxMessageCount: 0, + capabilities: [.imap4rev1], + expectedCommands: [], + expectedBatches: [ + .uidRange(.all) + ] + ), + MakeBatchesFixture( + name: ".all without Partial, mailbox with few messages", + query: .all, + mailboxMessageCount: 400, + capabilities: [.imap4rev1], + expectedCommands: [], + expectedBatches: [ + .uidRange(.all) + ] + ), + MakeBatchesFixture( + name: ".uids without Partial, empty UID set", + query: .uids([]), + mailboxMessageCount: 1_000, + capabilities: [.imap4rev1], + expectedCommands: [], + expectedBatches: [] + ), + MakeBatchesFixture( + name: ".uids without Partial, large UID set forcing batching", + query: .uids(UIDSet(1_000...2_500)), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .messageLimit(1_000)], + expectedCommands: [], + expectedBatches: [ + .uidRange(1_501...2_500), + .uidRange(1_000...1_500), + ] + ), + MakeBatchesFixture( + name: ".uids without Partial, contiguous UIDs split into batches", + query: .uids(UIDSet(5_000...7_000)), + mailboxMessageCount: 10_000, + capabilities: [.imap4rev1, .messageLimit(1_000)], + expectedCommands: [], + expectedBatches: [ + .uidRange(6_001...7_000), + .uidRange(5_001...6_000), + .uidRange(5_000...5_000), + ] + ), + MakeBatchesFixture( + name: ".all with message limit, multiple batches", + query: .all, + mailboxMessageCount: 2_300, + capabilities: [.imap4rev1, .messageLimit(1_000)], + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers( + .set( + .init(set: [ + 1, + 300, + 1_300, + 2_300, + ])! + ) + ), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 100, + 5_000, + 8_000, + 15_000, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ], + expectedBatches: [ + .uidRange(8_001...15_000), + .uidRange(5_001...8_000), + .uidRange(100...5_000), + ] + ), + ]) + static func `test makeBatches`( + _ fixture: MakeBatchesFixture + ) async throws { + let connection = TestConnection(expectedCommands: fixture.expectedCommands) + let batches = try await connection.makeBatches( + query: fixture.query, + mailboxMessageCount: fixture.mailboxMessageCount, + capabilities: fixture.capabilities + ) + #expect(Array(batches) == fixture.expectedBatches) + #expect(await connection.expectedCommands == [], "Should not have any commands remaining.") + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchTests.swift new file mode 100644 index 00000000..2d89d3ff --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchBatchTests.swift @@ -0,0 +1,336 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +private enum FetchBatchTests { + struct FetchBatchesIteratorFixture: Sendable, CustomTestStringConvertible { + var batches: FetchBatches + var expected: [FetchBatch] + + var testDescription: String { "\(batches)" } + } + + @Test(arguments: [ + FetchBatchesIteratorFixture( + batches: .fixed([ + 1...1_000, + 1_001...2_000, + ]), + expected: [ + .uidRange(1...1_000), + .uidRange(1_001...2_000), + ] + ), + FetchBatchesIteratorFixture( + batches: .fixed([]), + expected: [] + ), + FetchBatchesIteratorFixture( + batches: .fixed([100...200]), + expected: [.uidRange(100...200)] + ), + FetchBatchesIteratorFixture( + batches: .partial( + PartialFetchBatches( + last: 2_000, + batchSize: 1_000 + ) + ), + expected: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + ] + ), + FetchBatchesIteratorFixture( + batches: .partial( + PartialFetchBatches( + last: 100, + batchSize: 1_000 + ) + ), + expected: [ + .partialLast(.last(1...100)) + ] + ), + FetchBatchesIteratorFixture( + batches: .fromBoundaries( + UIDBatchFromBoundaries(boundaries: [100, 5_000, 10_000, 15_000]) + ), + expected: [ + .uidRange(10_001...15_000), + .uidRange(5_001...10_000), + .uidRange(100...5_000), + ] + ), + FetchBatchesIteratorFixture( + batches: .fromBoundaries( + UIDBatchFromBoundaries(boundaries: [100, 200]) + ), + expected: [ + .uidRange(100...200) + ] + ), + FetchBatchesIteratorFixture( + batches: .fromBoundaries( + UIDBatchFromBoundaries(boundaries: []) + ), + expected: [] + ), + ]) + static func fetchBatchesIterator( + _ fixture: FetchBatchesIteratorFixture + ) { + var iterator = fixture.batches.makeIterator() + var actual: [FetchBatch] = [] + while let batch = iterator.next() { + actual.append(batch) + guard actual.count < 50 else { + Issue.record("Too many iterations.") + break + } + } + #expect(actual == fixture.expected) + } + + struct SplitUIDsIntoRangesFixture: Sendable, CustomTestStringConvertible { + var uids: UIDSet + var batchSize: BatchSize + var expected: [UIDRange] + + var testDescription: String { "uids: \(uids), batchSize: \(batchSize)" } + } + + @Test(arguments: [ + SplitUIDsIntoRangesFixture( + uids: [], + batchSize: 1_000, + expected: [] + ), + SplitUIDsIntoRangesFixture( + uids: [100, 200, 300], + batchSize: 5, + expected: [100...300] + ), + SplitUIDsIntoRangesFixture( + uids: [100, 200, 1_500, 2_000], + batchSize: 2, + expected: [ + 1_500...2_000, + 100...200, + ] + ), + SplitUIDsIntoRangesFixture( + uids: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], + batchSize: 3, + expected: [ + 8...10, + 5...7, + 2...4, + 1...1, + ] + ), + SplitUIDsIntoRangesFixture( + uids: [100], + batchSize: 1, + expected: [100...100] + ), + SplitUIDsIntoRangesFixture( + uids: [100, 200, 300, 400, 500], + batchSize: 1, + expected: [ + 500...500, + 400...400, + 300...300, + 200...200, + 100...100, + ] + ), + SplitUIDsIntoRangesFixture( + uids: [1, 2, 3, 100, 200, 300, 1_000, 2_000, 3_000], + batchSize: 4, + expected: [ + 300...3_000, + 2...200, + 1...1, + ] + ), + ]) + static func splitUIDsIntoRanges_test( + _ fixture: SplitUIDsIntoRangesFixture + ) { + let result = splitUIDsIntoRanges( + uids: fixture.uids, + batchSize: fixture.batchSize + ) + #expect(result == fixture.expected) + } + + struct PartialSequenceFixture: Sendable, CustomTestStringConvertible { + var batches: PartialFetchBatches + var expected: [FetchBatch] + + var testDescription: String { "\(batches)" } + } + + @Test(arguments: [ + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 200, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...200)) + ] + ), + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 1, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...1)) + ] + ), + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 1_000, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...1_000)) + ] + ), + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 2_000, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + ] + ), + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 2_100, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + .partialLast(.last(2_001...2_100)), + ] + ), + PartialSequenceFixture( + batches: PartialFetchBatches( + last: 2_999, + batchSize: 1_000 + ), + expected: [ + .partialLast(.last(1...1_000)), + .partialLast(.last(1_001...2_000)), + .partialLast(.last(2_001...2_999)), + ] + ), + ]) + static func partialSequence( + _ fixture: PartialSequenceFixture + ) { + #expect(Array(fixture.batches) == fixture.expected) + } + + @Test + static func partialSequence_all() { + #expect( + PartialFetchBatches( + query: .all, + mailboxMessageCount: 765, + batchSize: 1_000 + ) + == PartialFetchBatches( + last: 765, + batchSize: 1_000 + ) + ) + #expect( + PartialFetchBatches( + query: .all, + mailboxMessageCount: 0, + batchSize: 1_000 + ) == nil + ) + #expect( + PartialFetchBatches( + query: .all, + mailboxMessageCount: 1, + batchSize: 1_000 + ) + == PartialFetchBatches( + last: 1, + batchSize: 1_000 + ) + ) + } + + @Test + static func partialSequence_last() { + #expect( + PartialFetchBatches( + query: .last(count: 2_000), + mailboxMessageCount: 765, + batchSize: 1_000 + ) + == PartialFetchBatches( + last: 765, + batchSize: 1_000 + ) + ) + #expect( + PartialFetchBatches( + query: .last(count: 2_000), + mailboxMessageCount: 0, + batchSize: 1_000 + ) == nil + ) + #expect( + PartialFetchBatches( + query: .last(count: 2_000), + mailboxMessageCount: 2_001, + batchSize: 1_000 + ) + == PartialFetchBatches( + last: 2_000, + batchSize: 1_000 + ) + ) + #expect( + PartialFetchBatches( + query: .last(count: 2_000), + mailboxMessageCount: 77_777, + batchSize: 1_000 + ) + == PartialFetchBatches( + last: 2_000, + batchSize: 1_000 + ) + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchTests.swift new file mode 100644 index 00000000..9001c9f0 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/FetchTests.swift @@ -0,0 +1,383 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum FetchTests { + struct MessageInfoFixture: Sendable, CustomTestStringConvertible { + var name: String + var mailboxMessageCount: Int + var capabilities: [Capability] + var query: FetchQuery + var expectedCommands: [TestConnection.CommandAndResponses] + var expectedResults: [ExpectedMessageInfo] + + var testDescription: String { name } + + struct ExpectedMessageInfo: Sendable { + var uid: UID + var date: String? + var subject: String? + var from: String? + var to: String? + var cc: String? + var messageID: String? + var inReplyTo: String? + var flags: [String] + } + } + + @Test(arguments: [ + MessageInfoFixture( + name: "last 2 messages", + mailboxMessageCount: 10_000, + capabilities: [], + query: .last(count: 2), + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [9_999...])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 309_727, + 967_986, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidFetch( + .set([309_727...967_986]), + [.uid, .flags, .envelope], + [] + ), + responses: [ + .fetch(.start(5)), + .fetch(.simpleAttribute(.uid(309_727))), + .fetch(.simpleAttribute(.flags([.seen]))), + .fetch( + .simpleAttribute( + .envelope( + Envelope( + date: InternetMessageDate("Mon, 10 Feb 2025 12:14:53 -0700 (MST)"), + subject: ByteBuffer(string: "Fwd: iOS email"), + from: [.a], + sender: [.b], + reply: [.c], + to: [.d], + cc: [.e], + bcc: [.f], + inReplyTo: "<13D87EC32432@example.apple.com>", + messageID: "<2F89B1064815@example.apple.com>" + ) + ) + ) + ), + .fetch(.finish), + .fetch(.start(55)), + .fetch(.simpleAttribute(.uid(967_986))), + .fetch(.simpleAttribute(.flags([.answered]))), + .fetch( + .simpleAttribute( + .envelope( + Envelope( + date: InternetMessageDate("Sat, 29 Jun 2024 22:25:38 +0900"), + subject: ByteBuffer(string: "Fotowelt"), + from: [.f], + sender: [.e], + reply: [], + to: [.a], + cc: [], + bcc: [], + inReplyTo: nil, + messageID: "<7A9EEFC3D051@example.apple.com>" + ) + ) + ) + ), + .fetch(.finish), + ], + completion: .ok(.init(text: "Fetch done")) + ), + ], + expectedResults: [ + .init( + uid: 309_727, + date: "Mon, 10 Feb 2025 12:14:53 -0700 (MST)", + subject: "Fwd: iOS email", + from: "a@example.apple.com", + to: "d@example.apple.com", + cc: "e@example.apple.com", + messageID: "<2F89B1064815@example.apple.com>", + inReplyTo: "<13D87EC32432@example.apple.com>", + flags: ["\\Seen"] + ), + .init( + uid: 967_986, + date: "Sat, 29 Jun 2024 22:25:38 +0900", + subject: "Fotowelt", + from: "f@example.apple.com", + to: "a@example.apple.com", + cc: nil, + messageID: "<7A9EEFC3D051@example.apple.com>", + inReplyTo: nil, + flags: ["\\Answered"] + ), + ] + ), + MessageInfoFixture( + name: "specific UIDs", + mailboxMessageCount: 1_000, + capabilities: [], + query: .uids([10, 20]), + expectedCommands: [ + .init( + command: .uidFetch( + .set([10, 20]), + [.uid, .flags, .envelope], + [] + ), + responses: [ + .fetch(.start(1)), + .fetch(.simpleAttribute(.uid(10))), + .fetch(.simpleAttribute(.flags([.draft]))), + .fetch( + .simpleAttribute( + .envelope( + Envelope( + date: InternetMessageDate("Wed, 15 Jan 2025 08:00:00 +0000"), + subject: ByteBuffer(string: "Test Subject"), + from: [.a], + sender: [.a], + reply: [.a], + to: [.b], + cc: [], + bcc: [], + inReplyTo: nil, + messageID: "" + ) + ) + ) + ), + .fetch(.finish), + .fetch(.start(2)), + .fetch(.simpleAttribute(.uid(20))), + .fetch(.simpleAttribute(.flags([]))), + .fetch( + .simpleAttribute( + .envelope( + Envelope( + date: InternetMessageDate("Thu, 16 Jan 2025 09:30:00 +0000"), + subject: ByteBuffer(string: "Another Test"), + from: [.b], + sender: [.b], + reply: [.b], + to: [.a], + cc: [], + bcc: [], + inReplyTo: nil, + messageID: "" + ) + ) + ) + ), + .fetch(.finish), + ], + completion: .ok(.init(text: "Fetch done")) + ) + ], + expectedResults: [ + .init( + uid: 10, + date: "Wed, 15 Jan 2025 08:00:00 +0000", + subject: "Test Subject", + from: "a@example.apple.com", + to: "b@example.apple.com", + cc: nil, + messageID: "", + inReplyTo: nil, + flags: ["\\Draft"] + ), + .init( + uid: 20, + date: "Thu, 16 Jan 2025 09:30:00 +0000", + subject: "Another Test", + from: "b@example.apple.com", + to: "a@example.apple.com", + cc: nil, + messageID: "", + inReplyTo: nil, + flags: [] + ), + ] + ), + ]) + static func messageInfo(_ fixture: MessageInfoFixture) async throws { + let connection = TestConnection(expectedCommands: fixture.expectedCommands) + let result = try await connection.fetchMessageInfo( + mailboxMessageCount: fixture.mailboxMessageCount, + capabilities: fixture.capabilities, + query: fixture.query + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(result.count == fixture.expectedResults.count) + + for (actual, expected) in zip(result, fixture.expectedResults) { + #expect(actual.uid == expected.uid) + #expect(actual.date == expected.date) + #expect(actual.subject == expected.subject) + #expect(actual.from == expected.from) + #expect(actual.to == expected.to) + #expect(actual.cc == expected.cc) + #expect(actual.messageID == expected.messageID) + #expect(actual.inReplyTo == expected.inReplyTo) + #expect(actual.flags == expected.flags) + } + } + + @Test + static func simpleAttributes() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidFetch( + .set([309_727, 967_986]), + [.uid, .flags, .internalDate], + [] + ), + responses: [ + .fetch(.start(5)), + .fetch(.simpleAttribute(.uid(309_727))), + .fetch(.simpleAttribute(.flags([.seen]))), + .fetch( + .simpleAttribute( + .internalDate( + ServerMessageDate( + .init( + year: 2025, + month: 4, + day: 7, + hour: 17, + minute: 46, + second: 22, + timeZoneMinutes: 600 + )! + ) + ) + ) + ), + .fetch(.finish), + + .fetch(.start(55)), + .fetch(.simpleAttribute(.uid(967_986))), + .fetch(.simpleAttribute(.flags([.answered]))), + .fetch( + .simpleAttribute( + .internalDate( + ServerMessageDate( + .init( + year: 2025, + month: 4, + day: 7, + hour: 17, + minute: 47, + second: 55, + timeZoneMinutes: 600 + )! + ) + ) + ) + ), + .fetch(.finish), + ], + completion: .ok(.init(text: "Fetch done")) + ) + ]) + let result: [(UID, SequenceNumber?, [MessageAttribute])] + result = try await connection.fetchSimpleAttributes( + capabilities: [], + uids: [309_727, 967_986], + attributes: [.flags, .internalDate], + modifiers: [], + into: [] + ) { all, uid, seq, attr in + all.append((uid, seq, attr)) + } + #expect(await connection.expectedCommands.isEmpty) + #expect(result.count == 2) + + #expect(result.first?.0 == 309_727) + #expect(result.first?.1 == 5) + #expect( + result.first?.2 == [ + .uid(309_727), + .flags([.seen]), + .internalDate( + ServerMessageDate( + .init(year: 2025, month: 4, day: 7, hour: 17, minute: 46, second: 22, timeZoneMinutes: 600)! + ) + ), + ] + ) + + #expect(result.last?.0 == 967_986) + #expect(result.last?.1 == 55) + #expect( + result.last?.2 == [ + .uid(967_986), + .flags([.answered]), + .internalDate( + ServerMessageDate( + .init(year: 2025, month: 4, day: 7, hour: 17, minute: 47, second: 55, timeZoneMinutes: 600)! + ) + ), + ] + ) + } +} + +extension EmailAddressListElement { + static var a: EmailAddressListElement { .example("a") } + static var b: EmailAddressListElement { .example("b") } + static var c: EmailAddressListElement { .example("c") } + static var d: EmailAddressListElement { .example("d") } + static var e: EmailAddressListElement { .example("e") } + static var f: EmailAddressListElement { .example("f") } + + static func example(_ name: String) -> EmailAddressListElement { + .singleAddress( + EmailAddress( + personName: nil, + sourceRoot: nil, + mailbox: ByteBuffer(string: name), + host: ByteBuffer(string: "example.apple.com") + ) + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentifyTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentifyTests.swift new file mode 100644 index 00000000..4457f729 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentifyTests.swift @@ -0,0 +1,62 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum IdentifyTests { + @Test + static func roundTrip() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .id([ + "name": "imap-tool", + "os": Identity.operatingSystemName, + "os-version": Identity.operatingSystemVersion, + ]), + responses: [ + .untagged( + .id([ + "foo": nil, + "bar": "baz", + ]) + ) + ], + completion: .ok(.init(text: "Done")) + ) + ]) + let r = try await connection.identify( + capabilities: [.imap4rev1, .condStore, .id] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(r.serverID == ["foo": nil, "bar": "baz"]) + #expect(r.capabilities == [.imap4rev1, .condStore, .id]) + } + + @Test + static func serverWithoutID() async throws { + let connection = TestConnection(expectedCommands: []) + let r = try await connection.identify( + capabilities: [.imap4rev1, .condStore] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(r.serverID == [:]) + #expect(r.capabilities == [.imap4rev1, .condStore]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentityTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentityTests.swift new file mode 100644 index 00000000..62cf2894 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdentityTests.swift @@ -0,0 +1,36 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Testing + +@Suite +private enum IdentityTests { + + #if os(Linux) + @Test + static func os() { + #expect(Identity.operatingSystemName == "Linux") + #expect(Identity.operatingSystemVersion?.isEmpty == false) + } + + #else + @Test + static func os() { + #expect(Identity.operatingSystemName == "Darwin") + #expect(Identity.operatingSystemVersion?.isEmpty == false) + } + + #endif +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdleEventsTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdleEventsTests.swift new file mode 100644 index 00000000..2f009414 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/IdleEventsTests.swift @@ -0,0 +1,204 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +private enum IdleEventsTests { + @Test + static func encoding() async throws { + func jsonEncode(_ event: IdleEvent) -> String { + do { + return try String(decoding: makeResultData(event, format: .json), as: UTF8.self) + } catch { + return "failed: \(error)" + } + } + + #expect( + jsonEncode(.exists(208976)) == #""" + { + "count" : 208976, + "kind" : "exists" + } + """# + ) + #expect( + jsonEncode(.expunge(200622)) == #""" + { + "kind" : "expunge", + "sequenceNumber" : 200622 + } + """# + ) + #expect( + jsonEncode(.vanished([1_109_412])) == #""" + { + "kind" : "vanished", + "uids" : "1109412", + "uidsList" : [ + 1109412 + ] + } + """# + ) + #expect( + jsonEncode( + .vanished([51327, 65956, 258891, 469223, 565342, 722572, 985909, 1_406_543, 1_681_131, 1_831_100]) + ) == #""" + { + "kind" : "vanished", + "uids" : "51327,65956,258891,469223,565342,722572,985909,1406543,1681131,1831100", + "uidsList" : [ + 51327, + 65956, + 258891, + 469223, + 565342, + 722572, + 985909, + 1406543, + 1681131, + 1831100 + ] + } + """# + ) + #expect( + jsonEncode(.vanished([51327, 65956...65960, 1_831_100])) == #""" + { + "kind" : "vanished", + "uids" : "51327,65956:65960,1831100", + "uidsList" : [ + 51327, + 65956, + 65957, + 65958, + 65959, + 65960, + 1831100 + ] + } + """# + ) + #expect( + jsonEncode(.fetch(1_331_855, [.flags([.seen])])) == #""" + { + "flags" : [ + "\\Seen" + ], + "kind" : "fetch", + "sequenceNumber" : 1331855 + } + """# + ) + #expect( + jsonEncode(.fetch(378_377, [.flags([]), .uid(1_893_959)])) == #""" + { + "flags" : [ + + ], + "kind" : "fetch", + "sequenceNumber" : 378377, + "uid" : 1893959 + } + """# + ) + #expect( + jsonEncode(.fetch(18_081, [.flags([.seen, .deleted]), .uid(771_126)])) == #""" + { + "flags" : [ + "\\Seen", + "\\Deleted" + ], + "kind" : "fetch", + "sequenceNumber" : 18081, + "uid" : 771126 + } + """# + ) + #expect( + jsonEncode(.fetch(nil, [.rfc822Size(98_453), .uid(499_452)])) == #""" + { + "kind" : "fetch", + "rfc822Size" : 98453, + "uid" : 499452 + } + """# + ) + } + + @Test + static func decoding() { + func decode(_ input: [Response]) -> [IdleEvent] { + var decoder = IdleEventDecoder.normal + var result: [IdleEvent] = [] + for response in input { + if let e = decoder.update(response) { + result.append(e) + } + } + return result + } + + #expect( + decode([ + .untagged(.mailboxData(.exists(1_271_487))) + ]) == [ + .exists(1_271_487) + ] + ) + #expect( + decode([ + .untagged(.messageData(.expunge(576_840))) + ]) == [ + .expunge(576_840) + ] + ) + #expect( + decode([ + .untagged(.messageData(.vanished([557, 991, 1031, 1658, 1825, 1895]))) + ]) == [ + .vanished([557, 991, 1031, 1658, 1825, 1895]) + ] + ) + #expect( + decode([ + .fetch(.start(504_274)), + .fetch(.simpleAttribute(.flags([.seen]))), + .fetch(.finish), + ]) == [ + .fetch(504_274, [.flags([.seen])]) + ] + ) + #expect( + decode([ + .untagged(.mailboxData(.exists(90_124))), + .fetch(.start(504_274)), + .fetch(.simpleAttribute(.flags([.seen]))), + .fetch(.finish), + .untagged(.mailboxData(.exists(1_816_239))), + ]) == [ + .exists(90_124), + .fetch(504_274, [.flags([.seen])]), + .exists(1_816_239), + ] + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ListStatusTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ListStatusTests.swift new file mode 100644 index 00000000..b68bb2b8 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ListStatusTests.swift @@ -0,0 +1,431 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum ListStatusTests { + struct StrategyFixture: Hashable, CustomTestStringConvertible { + var capabilities: [Capability] + var expected: ListStatusStrategy + + var testDescription: String { + capabilities.map { String($0) }.joined(separator: " ") + } + } + + @Test(arguments: [ + StrategyFixture( + capabilities: [], + expected: ListStatusStrategy( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + ], + kind: .listThenStatus + ) + ), + StrategyFixture( + capabilities: [.listStatus], + expected: ListStatusStrategy( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + ], + kind: .listStatus + ) + ), + StrategyFixture( + capabilities: [.condStore], + expected: ListStatusStrategy( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ], + kind: .listThenStatus + ) + ), + StrategyFixture( + capabilities: [.specialUse], + expected: ListStatusStrategy( + listReturnOptions: [ + .specialUse + ], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + ], + kind: .listThenStatus + ) + ), + StrategyFixture( + capabilities: [.appendLimit(1234)], + expected: ListStatusStrategy( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + ], + kind: .listThenStatus + ) + ), + StrategyFixture( + capabilities: [Capability("STATUS=SIZE")], + expected: ListStatusStrategy( + listReturnOptions: [], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .size, + ], + kind: .listThenStatus + ) + ), + StrategyFixture( + capabilities: [ + .listStatus, + .condStore, + .specialUse, + .appendLimit(1234), + Capability("STATUS=SIZE"), + ], + expected: ListStatusStrategy( + listReturnOptions: [ + .specialUse + ], + statusAttributes: [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + .size, + ], + kind: .listStatus + ) + ), + ]) + static func strategy( + fixture: StrategyFixture + ) throws { + #expect(ListStatusStrategy(capabilities: fixture.capabilities) == fixture.expected) + } + + @Test + static func endToEnd_listThenStatus() async throws { + let connection = try TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(string: "*")), + [] + ), + untagged: [ + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .noInferiors + ], + path: MailboxPath( + name: .inbox, + pathSeparator: "/" + ), + extensions: [:] + ) + ) + ), + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .hasNoChildren + ], + path: MailboxPath( + name: "Trash", + pathSeparator: "." + ), + extensions: [:] + ) + ) + ), + ] + ), + .init( + command: .status( + .inbox, + [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ] + ), + untagged: [ + .mailboxData( + .status( + .inbox, + MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ) + ] + ), + .init( + command: .status( + "Trash", + [ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ] + ), + untagged: [ + .mailboxData( + .status( + "Trash", + MailboxStatus( + messageCount: 345, + recentCount: nil, + nextUID: 5_262, + uidValidity: 75_386_78, + unseenCount: 12, + size: nil, + highestModificationSequence: 364_949, + appendLimit: nil + ) + ) + ) + ] + ), + ] + ) + + let info = try await connection.listMailboxes( + capabilities: [.imap4rev1, .condStore] + ) + + #expect(info.count == 2) + #expect( + info == [ + try MailboxInfoAndStatus( + path: MailboxPath( + name: .inbox, + pathSeparator: "/" + ), + attributes: [ + .noInferiors + ], + status: MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ), + try MailboxInfoAndStatus( + path: MailboxPath( + name: "Trash", + pathSeparator: "." + ), + attributes: [ + .hasNoChildren + ], + status: MailboxStatus( + messageCount: 345, + recentCount: nil, + nextUID: 5_262, + uidValidity: 75_386_78, + unseenCount: 12, + size: nil, + highestModificationSequence: 364_949, + appendLimit: nil + ) + ), + ] + ) + } + + @Test + static func endToEnd_listStatus() async throws { + let connection = try TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .listIndependent( + [], + reference: MailboxName([]), + .mailbox(ByteBuffer(string: "*")), + [ + .statusOption([ + .messageCount, + .uidNext, + .uidValidity, + .unseenCount, + .highestModificationSequence, + ]) + ] + ), + untagged: [ + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .noInferiors + ], + path: MailboxPath( + name: .inbox, + pathSeparator: "/" + ), + extensions: [:] + ) + ) + ), + .mailboxData( + .status( + .inbox, + MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ) + ), + .mailboxData( + .list( + MailboxInfo( + attributes: [ + .hasNoChildren + ], + path: MailboxPath( + name: "Trash", + pathSeparator: "." + ), + extensions: [:] + ) + ) + ), + .mailboxData( + .status( + "Trash", + MailboxStatus( + messageCount: 345, + recentCount: nil, + nextUID: 5_262, + uidValidity: 75_386_78, + unseenCount: 12, + size: nil, + highestModificationSequence: 364_949, + appendLimit: nil + ) + ) + ), + ] + ) + ] + ) + + let info = try await connection.listMailboxes( + capabilities: [.imap4rev1, .condStore, .listStatus] + ) + + #expect(info.count == 2) + #expect( + info == [ + try MailboxInfoAndStatus( + path: MailboxPath( + name: .inbox, + pathSeparator: "/" + ), + attributes: [ + .noInferiors + ], + status: MailboxStatus( + messageCount: 8_640_873, + recentCount: nil, + nextUID: 25_922_595, + uidValidity: 34_563_456, + unseenCount: 17_234, + size: nil, + highestModificationSequence: 9_604_355, + appendLimit: nil + ) + ), + try MailboxInfoAndStatus( + path: MailboxPath( + name: "Trash", + pathSeparator: "." + ), + attributes: [ + .hasNoChildren + ], + status: MailboxStatus( + messageCount: 345, + recentCount: nil, + nextUID: 5_262, + uidValidity: 75_386_78, + unseenCount: 12, + size: nil, + highestModificationSequence: 364_949, + appendLimit: nil + ) + ), + ] + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MessageInfoTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MessageInfoTests.swift new file mode 100644 index 00000000..2da95c1d --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MessageInfoTests.swift @@ -0,0 +1,81 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +private enum MessageInfoTests { + @Test + static func fromMessageAttributes() { + #expect( + MessageInfo( + uid: 8_089_525, + attributes: [ + MessageAttribute.envelope( + Envelope( + date: "Sat, 19 Oct 2024 03:36:04 +0000", + subject: ByteBuffer(string: "Your Tripper Bus Ticket"), + from: [ + EmailAddressListElement.singleAddress( + EmailAddress( + personName: ByteBuffer(string: "TripperBus"), + sourceRoot: nil, + mailbox: ByteBuffer(string: "noreply"), + host: ByteBuffer(string: "tripperbus.com") + ) + ) + ], + sender: [], + reply: [], + to: [ + EmailAddressListElement.singleAddress( + EmailAddress( + personName: ByteBuffer(string: "Jacob Black"), + sourceRoot: nil, + mailbox: ByteBuffer(string: "jacob.black.paid"), + host: ByteBuffer(string: "icloud.com") + ) + ) + ], + cc: [], + bcc: [], + inReplyTo: nil, + messageID: MessageID("<20250619033604.32962e456969f8f6@tripperbus.com>") + ) + ), + MessageAttribute.flags([.answered, .seen]), + ] + ) + == MessageInfo( + uid: 8_089_525, + date: "Sat, 19 Oct 2024 03:36:04 +0000", + dateSeconds: 1_729_308_964, + subject: "Your Tripper Bus Ticket", + from: #""TripperBus" "#, + to: #""Jacob Black" "#, + cc: nil, + messageID: "<20250619033604.32962e456969f8f6@tripperbus.com>", + inReplyTo: nil, + flags: [ + #"\Answered"#, + #"\Seen"#, + ] + ) + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MoveMessageTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MoveMessageTests.swift new file mode 100644 index 00000000..b073ba85 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/MoveMessageTests.swift @@ -0,0 +1,218 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +enum MoveMessageTests { + @Test + static func testUsingMoveCommand() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidMove( + .set([123, 456]), + "Archive" + ), + responses: [], + completion: .ok(.init(text: "Moved")) + ) + ]) + + let selectInfo = SelectInfo( + mailbox: "INBOX", + responseText: .init(text: "Selected"), + flags: [], + permanentFlags: [], + messageCount: 10, + uidNext: 500, + uidValidity: 12345 + ) + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: [.move], + uids: [123, 456], + to: "Archive" + ) + } + + @Test + static func testUsingCopyCommand() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidCopy( + .set([789, 101112]), + "Sent" + ), + responses: [], + completion: .ok(.init(text: "Copied")) + ), + .init( + command: .uidStore( + .set([789, 101112]), + [], + .flags( + StoreFlags.add( + silent: true, + list: [.deleted] + ) + ) + ), + responses: [], + completion: .ok(.init(text: "Updated")) + ), + .init( + command: .expunge, + responses: [ + .untagged(.messageData(.expunge(5))), + .untagged(.messageData(.expunge(8))), + ], + completion: .ok(.init(text: "Done")) + ), + ]) + + let selectInfo = SelectInfo( + mailbox: "INBOX", + responseText: .init(text: "Selected"), + flags: [], + permanentFlags: [], + messageCount: 20, + uidNext: 150000, + uidValidity: 67890 + ) + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: [], + uids: [789, 101112], + to: "Sent" + ) + } + + @Test + static func testEmpty() async throws { + let connection = TestConnection( + expectedCommands: [] + ) + + let selectInfo = SelectInfo( + mailbox: "INBOX", + responseText: .init(text: "Selected"), + flags: [], + permanentFlags: [], + messageCount: 0, + uidNext: 1, + uidValidity: 11111 + ) + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: [.move], + uids: [], + to: "Archive" + ) + } + + @Test + static func testSingleMessage() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidMove( + .set([42]), + "Trash" + ), + responses: [], + completion: .ok(.init(text: "Moved")) + ) + ]) + + let selectInfo = SelectInfo( + mailbox: "INBOX", + responseText: .init(text: "Selected"), + flags: [], + permanentFlags: [], + messageCount: 5, + uidNext: 100, + uidValidity: 99999 + ) + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: [.move], + uids: [42], + to: "Trash" + ) + } + + @Test + static func testMultipleMessagesWithCopyFallback() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidCopy( + .set([1, 2, 3, 4, 5]), + "Important" + ), + responses: [], + completion: .ok(.init(text: "Copied")) + ), + .init( + command: .uidStore( + .set([1, 2, 3, 4, 5]), + [], + .flags( + StoreFlags.add( + silent: true, + list: [.deleted] + ) + ) + ), + responses: [], + completion: .ok(.init(text: "Updated")) + ), + .init( + command: .expunge, + responses: [ + .untagged(.messageData(.expunge(1))), + .untagged(.messageData(.expunge(2))), + .untagged(.messageData(.expunge(3))), + .untagged(.messageData(.expunge(4))), + .untagged(.messageData(.expunge(5))), + ], + completion: .ok(.init(text: "Done")) + ), + ]) + + let selectInfo = SelectInfo( + mailbox: "INBOX", + responseText: .init(text: "Selected"), + flags: [], + permanentFlags: [], + messageCount: 50, + uidNext: 200, + uidValidity: 54321 + ) + + try await connection.moveMessages( + selectInfo: selectInfo, + capabilities: [], + uids: [1, 2, 3, 4, 5], + to: "Important" + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/RenameMailboxTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/RenameMailboxTests.swift new file mode 100644 index 00000000..10abe553 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/RenameMailboxTests.swift @@ -0,0 +1,187 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPCommands +import Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite("Rename Mailbox") +struct RenameMailboxTests { + + // MARK: - Happy Path Tests + + @Test + static func renameMailbox_success() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "OldFolder", to: "NewFolder", parameters: [:]), + untagged: [], + completion: .ok(.init(text: "RENAME completed")) + ) + ] + ) + + try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "OldFolder", + new: "NewFolder" + ) + + await #expect(connection.expectedCommands == []) + } + + @Test + static func renameMailbox_successWithCustomMessage() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "INBOX.Drafts", to: "INBOX.MyDrafts", parameters: [:]), + untagged: [], + completion: .ok(.init(text: "Mailbox renamed successfully")) + ) + ] + ) + + try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "INBOX.Drafts", + new: "INBOX.MyDrafts" + ) + + await #expect(connection.expectedCommands == []) + } + + @Test + static func renameMailbox_nestedMailbox() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "INBOX.Work.2023", to: "INBOX.Archives.2023", parameters: [:]), + untagged: [], + completion: .ok(.init(text: "RENAME completed")) + ) + ] + ) + + try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "INBOX.Work.2023", + new: "INBOX.Archives.2023" + ) + + await #expect(connection.expectedCommands == []) + } + + @Test + static func renameMailbox_moveToTopLevel() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "INBOX.Work.ImportantProject", to: "ImportantProject", parameters: [:]), + untagged: [], + completion: .ok(.init(text: "RENAME completed")) + ) + ] + ) + + try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "INBOX.Work.ImportantProject", + new: "ImportantProject" + ) + + await #expect(connection.expectedCommands == []) + } + + @Test + static func renameMailbox_moveToNestedLevel() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "TempFolder", to: "INBOX.Archives.TempFolder", parameters: [:]), + untagged: [], + completion: .ok(.init(text: "RENAME completed")) + ) + ] + ) + + try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "TempFolder", + new: "INBOX.Archives.TempFolder" + ) + + await #expect(connection.expectedCommands == []) + } + + // MARK: - Error Handling Tests + + @Test + static func renameMailbox_sourceNotFound() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "NonExistentFolder", to: "NewFolder", parameters: [:]), + untagged: [], + completion: .no(.init(text: "Source mailbox does not exist")) + ) + ] + ) + + await #expect(throws: TaggedResponse.StateNotOK.self) { + _ = try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "NonExistentFolder", + new: "NewFolder" + ) + } + + await #expect(connection.expectedCommands == []) + } + + @Test + static func renameMailbox_badResponse() async throws { + let connection = try TestConnection( + expectedOrdering: .inOrder, + expectedCommands: [ + .init( + command: .rename(from: "SourceFolder", to: "TargetFolder", parameters: [:]), + untagged: [], + completion: .bad(.init(text: "Invalid command syntax")) + ) + ] + ) + + await #expect(throws: TaggedResponse.StateNotOK.self) { + _ = try await connection.renameMailbox( + capabilities: [.imap4rev1], + old: "SourceFolder", + new: "TargetFolder" + ) + } + + await #expect(connection.expectedCommands == []) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchEndToEndTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchEndToEndTests.swift new file mode 100644 index 00000000..9df767c4 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchEndToEndTests.swift @@ -0,0 +1,557 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite(.timeLimit(.minutes(1))) +private enum SearchEndToEndTests { + @Test + static func extended_RFC_4731() async throws { + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .not(.deleted), + charset: nil, + returnOptions: [.all] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), // <--- we need to hard-code this. + kind: .uid, + returnData: [.all(.set([309_727, 967_986]))] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ] + ) + let uids = try await connection.search( + capabilities: [.extendedSearch], + key: .not(.deleted) + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(uids == [309_727, 967_986]) + } + + @Test + static func partial_RFC_9394() async throws { + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .not(.deleted), + charset: nil, + returnOptions: [.partial(.last(1...1_200))] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), // <--- we need to hard-code this. + kind: .uid, + returnData: [ + .partial( + .last(1...1_200), + [309_727, 967_986] + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .not(.deleted), + charset: nil, + returnOptions: [.partial(.last(1_201...2_400))] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A2"), // <--- we need to hard-code this. + kind: .uid, + returnData: [ + .partial( + .last(1_201...2_400), + [] + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + ] + ) + let uids = try await connection.search( + capabilities: [.partial, .messageLimit(1_200)], + key: .not(.deleted) + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(uids == [309_727, 967_986]) + } + + @Test + static func allUIDs_rfc3501() async throws { + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [99_101, 100_000])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 6_987_831, + 9_879_779, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 6_987_831...9_879_779))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + ] + ) + let result: UIDSet = try await connection.allUIDs( + query: .last(count: 900), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1] + ) + #expect( + result == [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ] + ) + } + + @Test + static func seenUIDs_rfc3501() async throws { + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [99_101, 100_000])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 6_987_831, + 9_879_779, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .and([ + .uid(.set(UIDSetNonEmpty(range: 6_987_831...9_879_779))), + .seen, + ]), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search( + [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ], + nil + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .seen, + query: .last(count: 900), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1] + ) + #expect( + result == [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ] + ) + } + + @Test + static func seenUIDs_partial() async throws { + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .seen, + charset: nil, + returnOptions: [.partial(.last(1...900))] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), // <--- we need to hard-code this. + kind: .uid, + returnData: [ + .partial( + .last(1...900), + [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ] + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .seen, + query: .last(count: 900), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_200)] + ) + #expect( + result == [ + 6_987_831, 7_125_543, 7_263_255, 7_400_966, 7_538_678, + 7_676_390, 7_814_102, 7_951_814, 8_089_525, 8_227_237, + 8_364_949, 8_502_661, 8_640_373, 8_778_085, 8_915_796, + 9_053_508, 9_191_220, 9_328_932, 9_466_644, 9_604_355, + 9_742_067, 9_879_779, + ] + ) + } + + @Test + static func uids_rfc3501_multipleBatches() async throws { + // Tests that batchedSearch correctly intersects requested UIDs with each batch's UID range + // and combines results across multiple batches when the server doesn't support PARTIAL. + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 2_994...4_000))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([3_956, 3_607, 3_358], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 2_000...2_993))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([2_272, 2_878, 2_850], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .all, + query: .uids([2_000...4_000]), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1, .messageLimit(1_007)] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(result == [2_272, 2_878, 2_850, 3_956, 3_607, 3_358]) + } + + @Test + static func uids_partial() async throws { + // Tests that batchedSearch with PARTIAL capability correctly searches for specific UIDs. + // With PARTIAL, the search is limited to the last N messages in the mailbox. + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(set: [100, 200, 1_500, 2_000])!)), + charset: nil, + returnOptions: [.partial(.last(1...4))] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), + kind: .uid, + returnData: [ + .partial( + .last(1...4), + [1_500, 2_000] + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .all, + query: .uids([100, 200, 1_500, 2_000]), + mailboxMessageCount: 100_000, + capabilities: [.imap4rev1, .partial, .messageLimit(1_200)] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(result == [1_500, 2_000]) + } + + @Test + static func all_rfc3501_multipleBatches() async throws { + // Tests that batchedSearch correctly iterates through all batches when fetching + // the entire mailbox using UID range batching (without PARTIAL). + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .sequenceNumbers(.set(.init(set: [1, 1_000, 2_000, 3_000])!)), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([100, 5_000, 10_000, 15_000], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 10_001...15_000))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([11_000, 12_000, 13_000, 14_000, 15_000], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 5_001...10_000))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([6_000, 7_000, 8_000, 9_000, 10_000], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + .init( + command: .uidSearch( + key: .uid(.set(UIDSetNonEmpty(range: 100...5_000))), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged( + .mailboxData( + .search([100, 1_000, 2_000, 3_000, 4_000, 5_000], nil) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ), + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .all, + query: .all, + mailboxMessageCount: 3_000, + capabilities: [.imap4rev1, .messageLimit(1_000)] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect( + result == [ + 100, 1_000, 2_000, 3_000, 4_000, 5_000, + 6_000, 7_000, 8_000, 9_000, 10_000, + 11_000, 12_000, 13_000, 14_000, 15_000, + ] + ) + } + + @Test + static func all_partial() async throws { + // Tests that batchedSearch with PARTIAL capability correctly searches the entire mailbox + // using PARTIAL ranges. With a small mailbox, this should require only one partial batch. + let connection = TestConnection( + expectedOrdering: .anyOrder, + expectedCommands: [ + .init( + command: .uidSearch( + key: .all, + charset: nil, + returnOptions: [.partial(.last(1...3_000))] + ), + responses: [ + .untagged( + .mailboxData( + .extendedSearch( + ExtendedSearchResponse( + correlator: SearchCorrelator(tag: "A1"), + kind: .uid, + returnData: [ + .partial( + .last(1...3_000), + [ + 100, 1_000, 2_000, 3_000, 4_000, 5_000, + 6_000, 7_000, 8_000, 9_000, 10_000, + 11_000, 12_000, 13_000, 14_000, 15_000, + ] + ) + ] + ) + ) + ) + ) + ], + completion: .ok(.init(text: "Done searching")) + ) + ] + ) + let result: UIDSet = try await connection.batchedSearch( + key: .all, + query: .all, + mailboxMessageCount: 3_000, + capabilities: [.imap4rev1, .partial, .messageLimit(5_000)] + ) + #expect(await connection.expectedCommands.isEmpty) + #expect( + result == [ + 100, 1_000, 2_000, 3_000, 4_000, 5_000, + 6_000, 7_000, 8_000, 9_000, 10_000, + 11_000, 12_000, 13_000, 14_000, 15_000, + ] + ) + } + +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchTests.swift new file mode 100644 index 00000000..7e27b205 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SearchTests.swift @@ -0,0 +1,208 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite +private enum SearchTests { + struct CombineKeyAndBatchFixture: Sendable, CustomTestStringConvertible { + var key: SearchKey + var query: FetchQuery + var batch: FetchBatch + var expected: SearchKey + + var testDescription: String { "\(key) \(query) \(batch)" } + } + + @Test(arguments: [ + CombineKeyAndBatchFixture( + key: .flagged, + query: .all, + batch: FetchBatch.partialLast(.last(1...40)), + expected: .flagged + ), + CombineKeyAndBatchFixture( + key: .seen, + query: .last(count: 100), + batch: FetchBatch.partialLast(.last(1...50)), + expected: .seen + ), + CombineKeyAndBatchFixture( + key: .all, + query: .all, + batch: FetchBatch.uidRange(100...200), + expected: .uid(.set(UIDSetNonEmpty(range: 100...200))) + ), + CombineKeyAndBatchFixture( + key: .flagged, + query: .all, + batch: FetchBatch.uidRange(100...200), + expected: .and([.uid(.set(UIDSetNonEmpty(range: 100...200))), .flagged]) + ), + CombineKeyAndBatchFixture( + key: .flagged, + query: .uids([]), + batch: FetchBatch.uidRange(100...200), + expected: .not(.all) + ), + CombineKeyAndBatchFixture( + key: .seen, + query: .uids([]), + batch: FetchBatch.partialLast(.last(1...50)), + expected: .not(.all) + ), + CombineKeyAndBatchFixture( + key: .answered, + query: .uids([50, 150, 250]), + batch: FetchBatch.uidRange(100...200), + expected: .and([.uid(.set(UIDSetNonEmpty(range: 150...150))), .answered]) + ), + CombineKeyAndBatchFixture( + key: .draft, + query: .uids([10, 20, 30]), + batch: FetchBatch.partialLast(.last(1...100)), + expected: .and([.uid(.set(UIDSetNonEmpty(set: [10, 20, 30])!)), .draft]) + ), + ]) + static func testCombineKeyAndBatch( + _ fixture: CombineKeyAndBatchFixture + ) { + #expect( + SearchKey.combine( + key: fixture.key, + query: fixture.query, + batch: fixture.batch + ) == fixture.expected + ) + } + + struct MessageIDKeyFixture: Sendable, CustomTestStringConvertible { + var input: [MessageID] + var expected: SearchKey? + + var testDescription: String { + input.map { "\($0)" }.joined(separator: ", ") + } + } + + @Test(arguments: [ + MessageIDKeyFixture( + input: [""], + expected: SearchKey.header("message-id", ByteBuffer(string: "")) + ), + MessageIDKeyFixture( + input: [], + expected: nil + ), + MessageIDKeyFixture( + input: [""], + expected: SearchKey.header("message-id", ByteBuffer(string: "")) + ), + MessageIDKeyFixture( + input: ["", ""], + expected: SearchKey.or( + SearchKey.header("message-id", ByteBuffer(string: "")), + SearchKey.header("message-id", ByteBuffer(string: "")) + ) + ), + MessageIDKeyFixture( + input: ["", "", ""], + expected: SearchKey.or( + SearchKey.or( + SearchKey.header("message-id", ByteBuffer(string: "")), + SearchKey.header("message-id", ByteBuffer(string: "")) + ), + SearchKey.header("message-id", ByteBuffer(string: "")) + ) + ), + ]) + static func messageIDKey(_ fixture: MessageIDKeyFixture) { + #expect(SearchKey.messageID(fixture.input) == fixture.expected) + } + + struct LastMessagesKeyFixture: Sendable, CustomTestStringConvertible { + var count: Int + var mailboxMessageCount: Int + var expected: SearchKey + + var testDescription: String { "count: \(count), mailboxMessageCount: \(mailboxMessageCount)" } + } + + @Test(arguments: [ + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 200, + expected: SearchKey.sequenceNumbers(.set(MessageIdentifierSetNonEmpty(range: 191...SequenceNumber.max))) + ), + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 12, + expected: SearchKey.sequenceNumbers(.set(MessageIdentifierSetNonEmpty(range: 3...SequenceNumber.max))) + ), + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 11, + expected: SearchKey.sequenceNumbers(.set(MessageIdentifierSetNonEmpty(range: 2...SequenceNumber.max))) + ), + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 10, + expected: SearchKey.all + ), + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 8, + expected: SearchKey.all + ), + LastMessagesKeyFixture( + count: 10, + mailboxMessageCount: 0, + expected: SearchKey.all + ), + ]) + static func lastMessagesKey(_ fixture: LastMessagesKeyFixture) { + #expect( + SearchKey.lastMessages(count: fixture.count, mailboxMessageCount: fixture.mailboxMessageCount) + == fixture.expected + ) + } + + @Test + static func plain_RFC_3501() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidSearch( + key: .not(.deleted), + charset: nil, + returnOptions: [] + ), + responses: [ + .untagged(.mailboxData(.search([309_727, 967_986], nil))) + ], + completion: .ok(.init(text: "Done searching")) + ) + ]) + let uids = try await connection.search( + capabilities: [], + key: .not(.deleted) + ) + #expect(await connection.expectedCommands.isEmpty) + #expect(uids == [309_727, 967_986]) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Search_PredicateTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Search_PredicateTests.swift new file mode 100644 index 00000000..887ea60d --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/Search_PredicateTests.swift @@ -0,0 +1,226 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Foundation +import NIO +import NIOIMAP +import Testing + +@Suite("Search Predicate Tests") +private enum SearchPredicateTests { + struct CreateSearchKeyFixture: Sendable, CustomTestStringConvertible { + var input: SearchKey.Predicate + var expected: SearchKey + var date = Date(timeIntervalSinceReferenceDate: 782_115_211) + var timeZone = TimeZone(secondsFromGMT: 120)! + + var testDescription: String { "\(input)" } + } + + @Test(arguments: [ + CreateSearchKeyFixture( + input: SearchKey.Predicate(), + expected: .all + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(olderThanDays: 7), + expected: .sentBefore( + IMAPCalendarDay( + year: 2025, + month: 10, + day: 7 + )! + ) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(newerThanDays: 3), + expected: .sentSince( + IMAPCalendarDay( + year: 2025, + month: 10, + day: 11 + )! + ) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(subject: "test"), + expected: .subject(ByteBuffer(string: "test")) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(from: "alice@example.com"), + expected: .from(ByteBuffer(string: "alice@example.com")) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(to: "bob@example.com"), + expected: .to(ByteBuffer(string: "bob@example.com")) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(cc: "charlie@example.com"), + expected: .cc(ByteBuffer(string: "charlie@example.com")) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(text: "important"), + expected: .text(ByteBuffer(string: "important")) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + messageSizeSmallerThan: 1024 + ), + expected: .messageSizeSmaller(1024) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + messageSizeLargerThan: 8192 + ), + expected: .messageSizeLarger(8192) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(messageID: ""), + expected: .messageID("") + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(emailID: "email-id-123"), + expected: .emailID("email-id-123") + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(threadID: "thread-id-456"), + expected: .threadID("thread-id-456") + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(flagsSet: [.answered]), + expected: .answered + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate(flagsNotSet: [.seen]), + expected: .unseen + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + olderThanDays: 7, + subject: "test" + ), + expected: .and([ + .sentBefore( + IMAPCalendarDay( + year: 2025, + month: 10, + day: 7 + )! + ), + .subject(ByteBuffer(string: "test")), + ]) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + from: "alice@example.com", + flagsSet: [.flagged] + ), + expected: .and([ + .from(ByteBuffer(string: "alice@example.com")), + .flagged, + ]) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + messageSizeLargerThan: 1024, + flagsNotSet: [.deleted] + ), + expected: .and([ + .messageSizeLarger(1024), + .undeleted, + ]) + ), + CreateSearchKeyFixture( + input: SearchKey.Predicate( + flagsSet: [ + NIOIMAP.Flag("$MailFlagBit0"), + .flagged, + ], + flagsNotSet: [ + NIOIMAP.Flag("$MailFlagBit1"), + NIOIMAP.Flag("$MailFlagBit2"), + ] + ), + expected: .and([ + .keyword(Flag.Keyword("$MailFlagBit0")), + .flagged, + .not(.keyword(Flag.Keyword("$MailFlagBit1"))), + .not(.keyword(Flag.Keyword("$MailFlagBit2"))), + ]) + ), + ]) + static func `make search key`( + fixture: CreateSearchKeyFixture + ) throws { + let actual = try SearchKey( + fixture.input, + now: fixture.date, + timeZone: fixture.timeZone + ) + #expect( + actual == fixture.expected + ) + } + + struct FlagSearchKeyFixture: Sendable, CustomTestStringConvertible { + var input: NIOIMAP.Flag + var expected: SearchKey + var expectedInverted: SearchKey + + var testDescription: String { + let d = String(input) + return d.isEmpty ? "/" : d + } + } + + @Test(arguments: [ + FlagSearchKeyFixture( + input: .answered, + expected: .answered, + expectedInverted: .unanswered + ), + FlagSearchKeyFixture( + input: .flagged, + expected: .flagged, + expectedInverted: .unflagged + ), + FlagSearchKeyFixture( + input: .deleted, + expected: .deleted, + expectedInverted: .undeleted + ), + FlagSearchKeyFixture( + input: .seen, + expected: .seen, + expectedInverted: .unseen + ), + FlagSearchKeyFixture( + input: NIOIMAP.Flag("$MailFlagBit0"), + expected: .keyword(Flag.Keyword("$MailFlagBit0")), + expectedInverted: .not(.keyword(Flag.Keyword("$MailFlagBit0"))) + ), + FlagSearchKeyFixture( + input: NIOIMAP.Flag("$MailFlagBit2"), + expected: .keyword(Flag.Keyword("$MailFlagBit2")), + expectedInverted: .not(.keyword(Flag.Keyword("$MailFlagBit2"))) + ), + ]) + static func `make search key from flag`( + fixture: FlagSearchKeyFixture + ) throws { + #expect(try SearchKey(flag: fixture.input) == fixture.expected) + #expect(try SearchKey(notFlag: fixture.input) == fixture.expectedInverted) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SelectMailboxTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SelectMailboxTests.swift new file mode 100644 index 00000000..2aa7c26b --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/SelectMailboxTests.swift @@ -0,0 +1,169 @@ +//===----------------------------------------------------------------------===// +// +// 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 ArgumentParser +@testable import IMAPCommands +import Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +@Suite("Select Mailbox") +struct SelectMailboxTests { + @Test(.timeLimit(.minutes(1))) + func test() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .select(.inbox, []), + untagged: [ + .mailboxData(.flags([.answered, .flagged, .deleted, .seen, .draft])), + .mailboxData(.exists(136_599)), + .conditionalState( + .ok(.init(code: .permanentFlags([.flag(.deleted), .flag(.seen), .wildcard]), text: "")) + ), + .conditionalState(.ok(.init(code: .uidNext(939_012), text: ""))), + .conditionalState(.ok(.init(code: .uidValidity(537_470), text: ""))), + ] + ) + ]) + + let info = try await connection.select( + mailbox: .inbox, + createMailbox: .fail + ) + + #expect(info.mailbox == .inbox) + #expect(info.responseText == .init(text: "Done")) + #expect(info.flags == [.answered, .flagged, .deleted, .seen, .draft]) + #expect(info.permanentFlags == [.flag(.deleted), .flag(.seen), .wildcard]) + #expect(info.messageCount == 136_599) + #expect(info.uidNext == 939_012) + #expect(info.uidValidity == 537_470) + } + + @Test(.timeLimit(.minutes(1))) + func testOtherMailbox() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .select("Food", []), + untagged: [ + .conditionalState(.ok(.init(code: .uidValidity(265_058), text: ""))), + .conditionalState(.ok(.init(code: .uidNext(287_187), text: ""))), + .conditionalState(.ok(.init(code: .permanentFlags([.flag(.flagged), .flag(.draft)]), text: ""))), + .mailboxData(.flags([.flagged, .draft, .answered])), + .mailboxData(.exists(93_97)), + ] + ) + ]) + + let info = try await connection.select( + mailbox: "Food" as MailboxName, + createMailbox: .fail + ) + + #expect(info.mailbox == "Food") + #expect(info.responseText == .init(text: "Done")) + #expect(info.flags == [.flagged, .draft, .answered]) + #expect(info.permanentFlags == [.flag(.flagged), .flag(.draft)]) + #expect(info.messageCount == 93_97) + #expect(info.uidNext == 287_187) + #expect(info.uidValidity == 265_058) + } + + @Test(.timeLimit(.minutes(1))) + func testFailure() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .select("Food", []), + untagged: [], + completion: .no(ResponseText(text: "Unknown mailbox")) + ) + ]) + async #expect( + performing: { + _ = try await connection.select( + mailbox: "Food" as MailboxName, + createMailbox: .fail + ) + }, + throws: { _ in true } + ) + } + + @Test(.timeLimit(.minutes(1))) + func testCreatingMailboxWhenSelectionFails() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .select("Food", []), + untagged: [], + completion: .no(ResponseText(text: "Unknown mailbox")) + ), + .init( + command: .create("Food", [.attributes([.sent])]), + untagged: [], + completion: .ok(ResponseText(text: "Did create mailbox")) + ), + .init( + command: .select("Food", []), + untagged: [ + .conditionalState(.ok(.init(code: .uidValidity(265_058), text: ""))), + .conditionalState(.ok(.init(code: .uidNext(287_187), text: ""))), + .conditionalState(.ok(.init(code: .permanentFlags([.flag(.flagged), .flag(.draft)]), text: ""))), + .mailboxData(.flags([.flagged, .draft, .answered])), + .mailboxData(.exists(93_97)), + ], + completion: .ok(ResponseText(text: "Did select mailbox")) + ), + ]) + + let info = try await connection.select( + mailbox: "Food" as MailboxName, + createMailbox: .create([.attributes([.sent])]) + ) + + #expect(info.mailbox == "Food") + #expect(info.responseText == .init(text: "Did select mailbox")) + #expect(info.flags == [.flagged, .draft, .answered]) + #expect(info.permanentFlags == [.flag(.flagged), .flag(.draft)]) + #expect(info.messageCount == 93_97) + #expect(info.uidNext == 287_187) + #expect(info.uidValidity == 265_058) + } + + @Test(.timeLimit(.minutes(1))) + func testCreatingMailboxFailsWhenSelectionFails() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .select("Food", []), + untagged: [], + completion: .no(ResponseText(text: "Unknown mailbox")) + ), + .init( + command: .create("Food", [.attributes([.sent])]), + untagged: [], + completion: .no(ResponseText(text: "Can not create mailbox")) + ), + ]) + async #expect( + performing: { + _ = try await connection.select( + mailbox: "Food" as MailboxName, + createMailbox: .create([.attributes([.sent])]) + ) + }, + throws: { _ in true } + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift new file mode 100644 index 00000000..db5df493 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift @@ -0,0 +1,154 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP + +extension TestConnection { + struct CommandAndResponses: Hashable, Sendable { + var command: NIOIMAPCore.Command + var responses: [Response] + var completion: TaggedResponse.State + } +} + +extension TestConnection.CommandAndResponses { + init( + command: NIOIMAPCore.Command, + untagged: [ResponsePayload], + completion: TaggedResponse.State = .ok(.init(text: "Done")) + ) { + self.init( + command: command, + responses: untagged.map { .untagged($0) }, + completion: completion + ) + } +} + +extension TestConnection.CommandAndResponses { + init( + command: NIOIMAPCore.Command, + fetchResponses: [FetchResponse], + completion: TaggedResponse.State = .ok(.init(text: "Done")) + ) { + self.init( + command: command, + responses: fetchResponses.map { .fetch($0) }, + completion: completion + ) + } +} + +// MARK: - + +/// A simple connection for tests — with expected commands and their responses. +final actor TestConnection: ConnectionProtocol { + init( + expectedOrdering: Ordering = .inOrder, + expectedCommands: [CommandAndResponses] + ) { + self.expectedOrdering = expectedOrdering + self.expectedCommands = expectedCommands + } + + enum Ordering: Hashable, Sendable { + case inOrder + case anyOrder + } + + var _nextTag = IMAPConnection.Tag.first + + func makeNextTag() -> IMAPConnection.Tag { + defer { _nextTag = _nextTag.makeNext() } + return _nextTag + } + + let expectedOrdering: Ordering + var expectedCommands: [CommandAndResponses] + + private var currentContinuations: + [IMAPConnection.Tag: AsyncThrowingStream.Continuation] = [:] + + /// Runs in the caller's isolation domain — like `IMAPConnection.send(_:_:)` — rather than on + /// this actor, so that the handler does too. `nonisolated` is explicit because an actor's + /// methods are otherwise isolated to `self`. + nonisolated(nonsending) func send( + _ command: NIOIMAPCore.Command, + _ handler: nonisolated(nonsending) (IMAPConnection.Tag, IMAPConnection.ResponseStream) async throws -> Result + ) async throws -> Result { + let (tag, responses) = try await beginCommand(command) + let r = try await handler(tag, responses) + await finishCommand(tag: tag) + return r + } + + private func beginCommand( + _ command: NIOIMAPCore.Command + ) throws -> (IMAPConnection.Tag, IMAPConnection.ResponseStream) { + let commandAndResponses: TestConnection.CommandAndResponses + switch expectedOrdering { + case .inOrder: + guard + !expectedCommands.isEmpty, + expectedCommands.first?.command == command + else { throw Error.unexpectedCommand(command) } + commandAndResponses = expectedCommands.removeFirst() + case .anyOrder: + guard + let index = expectedCommands.firstIndex(where: { $0.command == command }) + else { throw Error.unexpectedCommand(command) } + commandAndResponses = expectedCommands.remove(at: index) + } + + let tag = makeNextTag() + let responses = makeResponseStream( + tag: tag, + commandAndResponses: commandAndResponses + ) + return (tag, responses) + } + + private func finishCommand(tag: IMAPConnection.Tag) { + currentContinuations.removeValue(forKey: tag) + } + + private func makeResponseStream( + tag: IMAPConnection.Tag, + commandAndResponses: CommandAndResponses + ) -> IMAPConnection.ResponseStream { + let (stream, continuation) = AsyncThrowingStream.makeStream(of: Response.self) + for r in commandAndResponses.responses { + continuation.yield(r) + } + let state = commandAndResponses.completion + continuation.yield( + .tagged( + TaggedResponse( + tag: "\(tag)", + state: state + ) + ) + ) + continuation.finish() + return IMAPConnection.ResponseStream(underlying: stream) + } + + enum Error: Swift.Error { + case unexpectedCommand(NIOIMAPCore.Command) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift new file mode 100644 index 00000000..3f6cf960 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift @@ -0,0 +1,620 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import Logging +import NIO +import NIOIMAP +import Testing +import IMAPCommands +@testable import IMAPToolLib + +extension TestServer { + /// Runs a test server that accepts a single client connection. + /// + /// Example: + /// ``` + /// await TestServer.runSingleConnectionServer( + /// greeting: .ok(.init(text: "Hello")), + /// expectedCommands: [ + /// .init( + /// command: .capability, + /// untagged: [.capabilityData([.imap4rev1, .imap4, .authenticate(AuthenticationMechanism("FOOBAR")!)])], + /// completion: .ok(.init(text: "Done")) + /// ), + /// + /// // add more expected commands here + /// + /// ] + /// ) { path in + /// try await IMAPConnection.withConnection( + /// configuration: IMAPConnection.Configuration(path) + /// ) { greeting, connection in + /// + /// // add test code here + /// + /// } + /// } + /// ``` + static func runSingleConnectionServer( + greeting: UntaggedStatus, + expectedCommands: [ExpectedCommand], + sourceLocation: SourceLocation = #_sourceLocation, + body: @Sendable @escaping (UnixDomainSocketPath) async throws -> Void + ) async { + let path = UnixDomainSocketPath(path: "/tmp/imap-\(String(UInt128.random(in: 0...UInt128.max), radix: 16))") + do { + try await runSingleConnectionTestServer( + path: path, + sourceLocation: sourceLocation, + runClient: body + ) { inbound, outbound in + await TestServer( + inbound: inbound, + outbound: outbound, + greeting: greeting, + expectedCommands: expectedCommands, + sourceLocation: sourceLocation + ).run() + } + } catch { + Issue.record(error, sourceLocation: sourceLocation) + } + } +} + +// MARK: - + +final actor TestServer: Sendable { + private let inbound: NIOAsyncChannelInboundStream + private let outbound: NIOAsyncChannelOutboundWriter + private let responseStream: AsyncStream + private let responseContinuation: AsyncStream.Continuation + let sourceLocation: SourceLocation + + enum Ordering: Hashable, Sendable { + case inOrder + case anyOrder + } + + struct ExpectedCommand { + var part: ExpectedPart + var responses: [Response] + var completion: TaggedResponse.State? + + enum ExpectedPart { + case continuationResponse(ByteBuffer) + case command(Command) + case append(MailboxName, [NIOIMAPCore.AppendCommand]) + } + + /// Creates an expected command. + /// + /// - Parameters: + /// - command: The expected ``Command``. + /// - untagged: Untagged responses to send before the tagged response. + /// - completion: The tagged response to send. + init( + command: Command, + untagged: [ResponsePayload] = [], + completion: TaggedResponse.State = .ok(.init(text: "Done")) + ) { + self.part = .command(command) + self.responses = untagged.map { .untagged($0) } + self.completion = completion + } + + init( + part: ExpectedPart, + responses: [Response], + completion: TaggedResponse.State? + ) { + self.part = part + self.responses = responses + self.completion = completion + } + } + + let greeting: UntaggedStatus + let expectedOrdering: Ordering + private var expectedCommands: [ExpectedCommand] + private var previousTag: String? + private var runningAppend: RunningAppend? + + private init( + inbound: NIOAsyncChannelInboundStream, + outbound: NIOAsyncChannelOutboundWriter, + greeting: UntaggedStatus, + expectedOrdering: Ordering = .inOrder, + expectedCommands: [ExpectedCommand], + sourceLocation: SourceLocation + ) { + self.inbound = inbound + self.outbound = outbound + let (a, b) = AsyncStream.makeStream() + self.responseStream = a + self.responseContinuation = b + self.greeting = greeting + self.expectedOrdering = expectedOrdering + self.expectedCommands = expectedCommands + self.sourceLocation = sourceLocation + } + + func waitForAll( + deadline: Date = Date.init(timeIntervalSinceNow: 10), + sourceLocation: SourceLocation = #_sourceLocation + ) async { + while Date() < deadline { + guard !expectedCommands.isEmpty else { return } + try? await Task.sleep(for: .milliseconds(1)) + } + let remaining = expectedCommands + Issue.record("Timed out waiting. Remaining: \(remaining)", sourceLocation: sourceLocation) + } + + private func run() async { + let sourceLocation = self.sourceLocation + let greeting = self.greeting + let inbound = self.inbound + let outbound = self.outbound + await withTaskGroup { group in + group.addTask { + do { + for try await part in inbound { + try await self.didReceive(part) + } + } catch is CancellationError { + // Ignore + } catch { + Issue.record(error, "Error while receiving inbound", sourceLocation: sourceLocation) + } + await self.close() + print("Inbound done.") + } + group.addTask { + do { + try await outbound.write(.untagged(.conditionalState(greeting))) + print("Server sent greeting.") + for try await response in self.responseStream { + try await outbound.write(response) + print("S: \(String(reflecting: response)).") + } + } catch is CancellationError { + // Ignore + } catch { + Issue.record(error, "Error while sending outbound", sourceLocation: sourceLocation) + } + outbound.finish() + print("Outbound done.") + } + await group.waitForAll() + } + let remaining = expectedCommands + if !remaining.isEmpty { + Issue.record( + "Did not receive all expected commands. Remaining: \(remaining)", + sourceLocation: sourceLocation + ) + } + } + + private func didReceive(_ part: CommandStreamPart) throws { + switch part { + case .tagged(let command): + let expectation = try popExpected( + command: command + ) + try didReceive( + command: command, + expectation: expectation + ) + case .continuationResponse(let response): + let expectation = try popExpected(continuationResponse: response) + try didReceive( + continuationResponse: response, + expectation: expectation + ) + case .append(.start(tag: let tag, appendingTo: let mailbox)): + let expectation = try popExpected(appendInto: mailbox) + try didReceive( + appendInto: mailbox, + tag: tag, + expectation: expectation + ) + case .append(let command): + try didReceive(appendCommand: command) + default: + struct UnexpectedCommandStreamPart: Swift.Error { + var part: CommandStreamPart + } + throw UnexpectedCommandStreamPart(part: part) + } + } + + func close() { + responseContinuation.finish() + } +} + +// MARK: Command + +extension TestServer { + private func popExpected( + command: TaggedCommand, + ) throws -> ExpectedCommand { + struct UnexpectedCommand: Swift.Error { + var command: TaggedCommand + } + + let index: Int + switch expectedOrdering { + case .anyOrder: + guard + let i = expectedCommands.firstIndex(where: { + switch $0.part { + case .command(command.command): true + default: false + } + }) + else { + throw UnexpectedCommand(command: command) + } + index = i + case .inOrder: + guard + case .command(command.command) = expectedCommands.first?.part + else { + throw UnexpectedCommand(command: command) + } + index = 0 + } + + return expectedCommands.remove(at: index) + } + + private func didReceive( + command: TaggedCommand, + expectation: ExpectedCommand + ) throws { + print("S: -> Received command '\(command.tag)'") + guard + runningAppend == nil + else { throw HasRunningAppend(mailbox: runningAppend!.mailbox) } + + guard + previousTag == nil + else { + struct ReceivedCommandWhileWaitingForContinuation: Swift.Error { + var previousTag: String + var command: TaggedCommand + } + throw ReceivedCommandWhileWaitingForContinuation( + previousTag: previousTag!, + command: command + ) + } + + for response in expectation.responses { + print("S: <- Sending response") + responseContinuation.yield(response) + } + if let c = expectation.completion { + print("S: <- Sending completion for command '\(command.tag)'") + responseContinuation.yield( + .tagged( + TaggedResponse( + tag: command.tag, + state: c + ) + ) + ) + } else { + previousTag = command.tag + } + } +} + +// MARK: Continuation Response + +extension TestServer { + private func popExpected( + continuationResponse response: ByteBuffer + ) throws -> ExpectedCommand { + struct UnexpectedContinuationResponse: Swift.Error { + var bytes: ByteBuffer + } + + let index: Int + switch expectedOrdering { + case .anyOrder: + guard + let i = expectedCommands.firstIndex(where: { + switch $0.part { + case .continuationResponse(response): true + default: false + } + }) + else { + throw UnexpectedContinuationResponse(bytes: response) + } + index = i + case .inOrder: + guard + case .continuationResponse(response) = expectedCommands.first?.part + else { + throw UnexpectedContinuationResponse(bytes: response) + } + index = 0 + } + return expectedCommands.remove(at: index) + } + + private func didReceive( + continuationResponse: ByteBuffer, + expectation: TestServer.ExpectedCommand + ) throws { + print("S: -> Received continuation response") + guard + runningAppend == nil + else { throw HasRunningAppend(mailbox: runningAppend!.mailbox) } + + for response in expectation.responses { + print("S: <- Sending response") + responseContinuation.yield(response) + } + if let c = expectation.completion { + struct NoPreviousTagForTaggedResponse: Swift.Error { + var continuationResponse: ByteBuffer + } + + guard + let tag = previousTag + else { + throw NoPreviousTagForTaggedResponse( + continuationResponse: continuationResponse + ) + } + previousTag = nil + + print("S: <- Sending completion for command '\(tag)'") + responseContinuation.yield( + .tagged( + TaggedResponse( + tag: tag, + state: c + ) + ) + ) + } + } +} + +// MARK: Append + +extension TestServer { + private func popExpected( + appendInto mailbox: MailboxName + ) throws -> RunningAppend { + struct UnexpectedAppend: Swift.Error { + var mailbox: MailboxName + } + + let index: Int + switch expectedOrdering { + case .anyOrder: + guard + let i = expectedCommands.firstIndex(where: { + switch $0.part { + case .append(mailbox, _): true + default: false + } + }) + else { + throw UnexpectedAppend(mailbox: mailbox) + } + index = i + case .inOrder: + guard + case .append(mailbox, _) = expectedCommands.first?.part + else { + throw UnexpectedAppend(mailbox: mailbox) + } + index = 0 + } + let e = expectedCommands.remove(at: index) + guard + case .append(_, let commands) = e.part + else { fatalError() } + return RunningAppend( + mailbox: mailbox, + remainingCommands: commands[...], + responses: e.responses, + completion: e.completion + ) + } + + private func didReceive( + appendInto mailbox: MailboxName, + tag: String, + expectation: RunningAppend + ) throws { + guard + runningAppend == nil + else { throw HasRunningAppend(mailbox: runningAppend!.mailbox) } + + runningAppend = expectation + previousTag = tag + } + + private func didReceive( + appendCommand command: NIOIMAPCore.AppendCommand + ) throws { + switch command { + case .start: print("S: -> Received append command (start)") + case .beginMessage: print("S: -> Received append command (beginMessage)") + case .messageBytes: print("S: -> Received append command (messageBytes)") + case .endMessage: print("S: -> Received append command (endMessage)") + case .beginCatenate: print("S: -> Received append command (beginCatenate)") + case .catenateURL: print("S: -> Received append command (catenateURL)") + case .catenateData: print("S: -> Received append command (catenateData)") + case .endCatenate: print("S: -> Received append command (endCatenate)") + case .finish: print("S: -> Received append command (finish)") + } + + struct UnexpectedAppendCommand: Swift.Error { + var command: NIOIMAPCore.AppendCommand + } + + guard var runningAppend else { throw UnexpectedAppendCommand(command: command) } + + let expected = runningAppend.remainingCommands.popFirst() + guard command == expected else { throw UnexpectedAppendCommand(command: command) } + + guard + runningAppend.remainingCommands.isEmpty + else { + self.runningAppend = runningAppend + return + } + + self.runningAppend = nil + + for response in runningAppend.responses { + print("S: <- Sending response") + responseContinuation.yield(response) + } + if let c = runningAppend.completion { + struct NoPreviousTagForTaggedResponse: Swift.Error { + var append: MailboxName + } + + guard + let tag = previousTag + else { + throw NoPreviousTagForTaggedResponse( + append: runningAppend.mailbox + ) + } + previousTag = nil + + print("S: <- Sending completion for append command '\(tag)'") + responseContinuation.yield( + .tagged( + TaggedResponse( + tag: tag, + state: c + ) + ) + ) + } + } + + struct HasRunningAppend: Swift.Error { + var mailbox: MailboxName + } + + struct RunningAppend { + var mailbox: MailboxName + var remainingCommands: ArraySlice + var responses: [Response] + var completion: TaggedResponse.State? + } +} + +struct UnixDomainSocketPath: Hashable, Sendable { + var path: String +} + +extension IMAPConnection.Configuration { + init( + _ path: UnixDomainSocketPath + ) { + self.init( + endpoint: .unixDomainSocket(path: path.path), + useTLS: false, + logging: .logging + ) + } +} + +private func runSingleConnectionTestServer( + path: UnixDomainSocketPath, + sourceLocation: SourceLocation, + runClient: @Sendable @escaping (UnixDomainSocketPath) async throws -> Void, + runConnection: + @Sendable @escaping (NIOAsyncChannelInboundStream, NIOAsyncChannelOutboundWriter) + async throws -> Void, +) async throws { + let channel = try await makeServerChannel(path: path) + try await withThrowingTaskGroup { group in + try await channel.executeThenClose { serverChannelInbound in + group.addTask { + print("Client started.") + do { + try await runClient(path) + } catch { + Issue.record(error, sourceLocation: sourceLocation) + throw error + } + print("Client done.") + } + + for try await connectionChannel in serverChannelInbound { + group.addTask { + print("New server connection.") + do { + try await connectionChannel.executeThenClose { inbound, outbound in + try await runConnection(inbound, outbound) + } + } catch { + print("Server error: \(error)") + } + print("Server connection done.") + } + // Exit the loop. We only want 1 connection. + break + } + + _ = await group.nextResult() + group.cancelAll() + } + print("Server done.") + } +} + +private func makeServerChannel( + path: UnixDomainSocketPath, +) async throws -> NIOAsyncChannel, Never> { + // The debug handlers used to be labelled "S" to tell the server's traffic apart from the + // client's. They log through swift-log now, so that label is logger metadata instead. + var logger = Logger.current + logger[metadataKey: "imap.side"] = "S" + return try await ServerBootstrap( + group: MultiThreadedEventLoopGroup.sharedEventLoopGroup + ).bind( + unixDomainSocketPath: path.path, + cleanupExistingSocketFile: true, + serverBackPressureStrategy: nil + ) { [logger] childChannel in + childChannel.eventLoop.makeCompletedFuture { + try childChannel.pipeline.syncOperations.addHandler(ByteToMessageHandler(FrameDecoder())) + try childChannel.pipeline.syncOperations.addHandler(makeInboundDebugHandler(logger: logger)) + try childChannel.pipeline.syncOperations.addHandler(makeOutboundDebugHandler(logger: logger)) + try childChannel.pipeline.syncOperations.addHandler(IMAPServerHandler()) + return try NIOAsyncChannel( + wrappingChannelSynchronously: childChannel + ) + } + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ThroughputEstimatorTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ThroughputEstimatorTests.swift new file mode 100644 index 00000000..c1470e99 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/ThroughputEstimatorTests.swift @@ -0,0 +1,419 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import Testing + +@Suite +enum ThroughputEstimatorTests { + struct ThroughputFormatFixture: CustomTestStringConvertible { + var throughput: ThroughputEstimator.Throughput + var fractionLength: Int + var expectedFormattedTasksPerSecond: String + + var testDescription: String { + "\(throughput.tasksPerSecond)-\(fractionLength)" + } + } + + @Test(arguments: [ + // Zero throughput + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0 + ), + fractionLength: 1, + expectedFormattedTasksPerSecond: "0.0" + ), + // Basic decimal with 1 fraction digit + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.2 + ), + fractionLength: 1, + expectedFormattedTasksPerSecond: "1.2" + ), + // No fraction digits + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 3.7 + ), + fractionLength: 0, + expectedFormattedTasksPerSecond: "4" + ), + // Multiple fraction digits + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 2.3456 + ), + fractionLength: 3, + expectedFormattedTasksPerSecond: "2.346" + ), + // Very small number + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0.001 + ), + fractionLength: 3, + expectedFormattedTasksPerSecond: "0.001" + ), + // Large number + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1234.5678 + ), + fractionLength: 2, + expectedFormattedTasksPerSecond: "1,234.57" + ), + // Integer value with fraction length + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 5.0 + ), + fractionLength: 2, + expectedFormattedTasksPerSecond: "5.00" + ), + // Very high precision + ThroughputFormatFixture( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.0 + ), + fractionLength: 5, + expectedFormattedTasksPerSecond: "1.00000" + ), + ]) + static func formattedTasksPerSecond( + fixture: ThroughputFormatFixture + ) async throws { + #expect( + fixture.throughput.formattedTasksPerSecond( + fractionLength: fixture.fractionLength + ) == fixture.expectedFormattedTasksPerSecond + ) + } + + struct ThroughputFormatTimeRemaining: CustomTestStringConvertible { + var throughput: ThroughputEstimator.Throughput + var remainingCount: Int + var remainingCountCutOff: Int + var expected: String? + + var testDescription: String { + "\(throughput.tasksPerSecond)-\(remainingCount)/\(remainingCountCutOff)" + } + } + + @Test(arguments: [ + // Zero throughput - no time estimate + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0 + ), + remainingCount: 200, + remainingCountCutOff: 10, + expected: nil + ), + // Basic time calculation + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.2 + ), + remainingCount: 200, + remainingCountCutOff: 10, + expected: "2min 46sec" + ), + // Very low throughput (just above threshold) + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0.002 + ), + remainingCount: 100, + remainingCountCutOff: 10, + expected: "13hr 53min 20sec" + ), + // Below threshold throughput - no estimate + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0.0001 + ), + remainingCount: 100, + remainingCountCutOff: 10, + expected: nil + ), + // Remaining count at cutoff - no estimate + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 2.0 + ), + remainingCount: 10, + remainingCountCutOff: 10, + expected: nil + ), + // Remaining count below cutoff - no estimate + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 2.0 + ), + remainingCount: 5, + remainingCountCutOff: 10, + expected: nil + ), + // Fast throughput - seconds only + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 10.0 + ), + remainingCount: 45, + remainingCountCutOff: 5, + expected: "4sec" + ), + // Medium throughput - minutes and seconds + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0.5 + ), + remainingCount: 150, + remainingCountCutOff: 20, + expected: "5min" + ), + // Slow throughput - hours and minutes + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 0.1 + ), + remainingCount: 1000, + remainingCountCutOff: 50, + expected: "2hr 46min 40sec" + ), + // Very fast throughput - sub-second + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 100.0 + ), + remainingCount: 50, + remainingCountCutOff: 10, + expected: "0sec" + ), + // Zero remaining count cutoff + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.0 + ), + remainingCount: 30, + remainingCountCutOff: 0, + expected: "30sec" + ), + // Exactly 1 hour + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.0 + ), + remainingCount: 3600, + remainingCountCutOff: 10, + expected: "1hr" + ), + // Exactly 1 minute + ThroughputFormatTimeRemaining( + throughput: ThroughputEstimator.Throughput( + tasksPerSecond: 1.0 + ), + remainingCount: 60, + remainingCountCutOff: 10, + expected: "1min" + ), + ]) + static func formattedTimeRemaining( + fixture: ThroughputFormatTimeRemaining + ) async throws { + #expect( + fixture.throughput.formattedTimeRemaining( + remainingCount: fixture.remainingCount, + remainingCountCutOff: fixture.remainingCountCutOff + ) == fixture.expected + ) + } + + // MARK: - didComplete() Tests + + @Test("didComplete returns nil on first call") + static func didCompleteFirstCall() async throws { + var estimator = ThroughputEstimator(now: Date()) + let result = estimator.didComplete(now: Date()) + #expect(result == nil) + #expect(estimator.count == 1) + } + + @Test("didComplete returns nil when count is less than 2") + static func didCompleteCountLessThanTwo() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // First call should return nil + let result1 = estimator.didComplete(now: startTime.addingTimeInterval(60)) + #expect(result1 == nil) + #expect(estimator.count == 1) + } + + @Test("didComplete returns nil when duration <= 30 and count <= 60") + static func didCompleteWithinThresholds() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // Complete tasks within 30 seconds and under 60 count + for i in 1...10 { + let result = estimator.didComplete(now: startTime.addingTimeInterval(Double(i) * 2)) // 2 seconds apart + #expect(result == nil) + } + #expect(estimator.count == 10) + } + + @Test("didComplete returns throughput when duration > 30 seconds") + static func didCompleteAfterDurationThreshold() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // First call increments count to 1 + let result1 = estimator.didComplete(now: startTime.addingTimeInterval(10)) + #expect(result1 == nil) + #expect(estimator.count == 1) + + // Second call after 31 seconds should return throughput + let result2 = estimator.didComplete(now: startTime.addingTimeInterval(31)) + #expect(result2 != nil) + + let throughput = try #require(result2) + // 2 tasks in 31 seconds = 2/31 ≈ 0.0645 tasks/second + #expect(abs(throughput.tasksPerSecond - (2.0 / 31.0)) < 0.0001) + + // Estimator should be reset + #expect(estimator.count == 0) + } + + @Test("didComplete returns throughput when count > 60") + static func didCompleteAfterCountThreshold() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // Complete 61 tasks within 30 seconds (very fast) + for i in 1...60 { + let result = estimator.didComplete(now: startTime.addingTimeInterval(Double(i) * 0.1)) // 0.1 seconds apart + #expect(result == nil) + } + + // 61st task should trigger throughput calculation + let result = estimator.didComplete(now: startTime.addingTimeInterval(6.1)) + #expect(result != nil) + + let throughput = try #require(result) + // 61 tasks in 6.1 seconds = 61/6.1 ≈ 10.0 tasks/second + #expect(abs(throughput.tasksPerSecond - (61.0 / 6.1)) < 0.0001) + + // Estimator should be reset + #expect(estimator.count == 0) + } + + @Test("didComplete resets estimator after returning throughput") + static func didCompleteResetsEstimator() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // Get to threshold + let _ = estimator.didComplete(now: startTime.addingTimeInterval(10)) + let throughputResult = estimator.didComplete(now: startTime.addingTimeInterval(35)) + + #expect(throughputResult != nil) + #expect(estimator.count == 0) + + // The start time should be updated to the time of the last didComplete call + // We can verify this by checking that the next call starts counting from 0 again + let nextResult = estimator.didComplete(now: startTime.addingTimeInterval(40)) + #expect(nextResult == nil) + #expect(estimator.count == 1) + } + + @Test("didComplete calculates correct throughput") + static func didCompleteCalculatesCorrectThroughput() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // Complete 5 tasks over 10 seconds + for i in 1...4 { + let result = estimator.didComplete(now: startTime.addingTimeInterval(Double(i) * 2)) + #expect(result == nil) + } + + // 5th task at 50 seconds (duration > 30, so should return throughput) + let result = estimator.didComplete(now: startTime.addingTimeInterval(50)) + #expect(result != nil) + + let throughput = try #require(result) + // 5 tasks in 50 seconds = 0.1 tasks/second + #expect(abs(throughput.tasksPerSecond - 0.1) < 0.0001) + } + + @Test("didComplete with custom now parameter") + static func didCompleteWithCustomNow() async throws { + let startTime = Date() + let customNow = startTime.addingTimeInterval(100) + + var estimator = ThroughputEstimator(now: startTime) + + // First call + let result1 = estimator.didComplete(now: customNow) + #expect(result1 == nil) + #expect(estimator.count == 1) + + // Second call should return throughput (duration = 100 seconds > 30) + let result2 = estimator.didComplete(now: customNow.addingTimeInterval(1)) + #expect(result2 != nil) + + let throughput = try #require(result2) + // 2 tasks in 101 seconds ≈ 0.0198 tasks/second + #expect(abs(throughput.tasksPerSecond - (2.0 / 101.0)) < 0.0001) + } + + @Test("didComplete edge case: exactly 30 seconds duration") + static func didCompleteExactly30Seconds() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // First call + let result1 = estimator.didComplete(now: startTime.addingTimeInterval(10)) + #expect(result1 == nil) + + // Second call at exactly 30 seconds - should return nil (condition is 30 < duration) + let result2 = estimator.didComplete(now: startTime.addingTimeInterval(30)) + #expect(result2 == nil) + #expect(estimator.count == 2) + } + + @Test("didComplete edge case: exactly 60 tasks") + static func didCompleteExactly60Tasks() async throws { + let startTime = Date() + var estimator = ThroughputEstimator(now: startTime) + + // Complete exactly 60 tasks in 10 seconds + for i in 1...60 { + let result = estimator.didComplete(now: startTime.addingTimeInterval(Double(i) * 0.1)) + if i == 60 { + // At exactly 60 tasks with duration < 30, should return nil + #expect(result == nil) + } else { + #expect(result == nil) + } + } + #expect(estimator.count == 60) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/UpdateFlagsTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/UpdateFlagsTests.swift new file mode 100644 index 00000000..4ecb3954 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/UpdateFlagsTests.swift @@ -0,0 +1,152 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +@testable import IMAPToolLib +import NIO +import NIOIMAP +import Testing + +private struct UpdateFlagsTests { + @Test + func setFlags() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidStore( + messages: [123, 456], + modifiers: [], + data: StoreData.flags( + .add( + silent: false, + list: [.seen, .flagged] + ) + ) + )!, + responses: [ + .fetch(.start(123)), + .fetch(.simpleAttribute(.flags([.seen, .flagged]))), + .fetch(.finish), + + .fetch(.start(456)), + .fetch(.simpleAttribute(.flags([.seen, .flagged, .answered]))), + .fetch(.finish), + ], + completion: .ok(.init(text: "STORE completed")) + ) + ]) + + try await connection.updateFlags( + uids: [123, 456], + changes: .init( + set: [.seen, .flagged], + unset: [] + ) + ) + } + + @Test + func unsetFlags() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidStore( + messages: [123, 456], + modifiers: [], + data: StoreData.flags( + .remove( + silent: false, + list: [.seen, .flagged] + ) + ) + )!, + responses: [ + .fetch(.start(123)), + .fetch(.simpleAttribute(.flags([.seen, .flagged]))), + .fetch(.finish), + + .fetch(.start(456)), + .fetch(.simpleAttribute(.flags([.seen, .flagged, .answered]))), + .fetch(.finish), + ], + completion: .ok(.init(text: "STORE completed")) + ) + ]) + + try await connection.updateFlags( + uids: [123, 456], + changes: .init( + set: [], + unset: [.seen, .flagged] + ) + ) + } + + @Test + func setAndUnsetFlags() async throws { + let connection = TestConnection(expectedCommands: [ + .init( + command: .uidStore( + messages: [123, 456], + modifiers: [], + data: StoreData.flags( + .add( + silent: false, + list: [.flagged] + ) + ) + )!, + responses: [ + .fetch(.start(123)), + .fetch(.simpleAttribute(.flags([.seen, .flagged]))), + .fetch(.finish), + + .fetch(.start(456)), + .fetch(.simpleAttribute(.flags([.flagged, .answered]))), + .fetch(.finish), + ], + completion: .ok(.init(text: "STORE 1 completed")) + ), + .init( + command: .uidStore( + messages: [123, 456], + modifiers: [], + data: StoreData.flags( + .remove( + silent: false, + list: [.seen] + ) + ) + )!, + responses: [ + .fetch(.start(123)), + .fetch(.simpleAttribute(.flags([.flagged]))), + .fetch(.finish), + + .fetch(.start(456)), + .fetch(.simpleAttribute(.flags([.flagged, .answered]))), + .fetch(.finish), + ], + completion: .ok(.init(text: "STORE 2 completed")) + ), + ]) + + try await connection.updateFlags( + uids: [123, 456], + changes: .init( + set: [.flagged], + unset: [.seen] + ) + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BarTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BarTests.swift new file mode 100644 index 00000000..136ac19a --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BarTests.swift @@ -0,0 +1,71 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Testing + +@Suite +private enum BarTests { + @Test + static func barWithWidth4() { + #expect(String.bar(fraction: -1.5, width: 4) == " ") + #expect(String.bar(fraction: 0.00, width: 4) == " ") + #expect(String.bar(fraction: 0.25, width: 4) == "█ ") + #expect(String.bar(fraction: 0.50, width: 4) == "██ ") + #expect(String.bar(fraction: 0.75, width: 4) == "███ ") + #expect(String.bar(fraction: 1.00, width: 4) == "████") + #expect(String.bar(fraction: 1.50, width: 4) == "████") + + #expect(String.bar(fraction: 0.11, width: 4) == "▌ ") + #expect(String.bar(fraction: 0.19, width: 4) == "▊ ") + #expect(String.bar(fraction: 0.23, width: 4) == "▉ ") + #expect(String.bar(fraction: 0.33, width: 4) == "█▍ ") + #expect(String.bar(fraction: 0.62, width: 4) == "██▌ ") + #expect(String.bar(fraction: 0.91, width: 4) == "███▋") + #expect(String.bar(fraction: 0.98, width: 4) == "███▉") + } + + @Test + static func barWithLabel() { + #expect(String.barWithLabel(fraction: 0.110, width: 20) == "██▎ 11%") + #expect(String.barWithLabel(fraction: 0.190, width: 20) == "███▊ 19%") + #expect(String.barWithLabel(fraction: 0.207, width: 20) == "████▏ 20.7%") + #expect(String.barWithLabel(fraction: 0.230, width: 20) == "████▋ 23%") + #expect(String.barWithLabel(fraction: 0.330, width: 20) == "██████▋ 33%") + #expect(String.barWithLabel(fraction: 0.492, width: 20) == "█████████▉ 49.2%") + #expect(String.barWithLabel(fraction: 0.620, width: 20) == "█62%████████▍ ") + #expect(String.barWithLabel(fraction: 0.910, width: 20) == "█91%██████████████▎ ") + #expect(String.barWithLabel(fraction: 0.912, width: 20) == "█91.2%████████████▎ ") + #expect(String.barWithLabel(fraction: 0.980, width: 20) == "█98%███████████████▋") + } + + /// A zero or negative width must not trap (e.g. when a long label drives the + /// available bar width non-positive). + @Test + static func barWithNonPositiveWidth() { + #expect(String.bar(fraction: 0.5, width: 0) == "") + #expect(String.bar(fraction: 0.5, width: -1) == "") + #expect(String.bar(fraction: 0.5, width: -100) == "") + } + + /// A width too small to hold a label falls back to the plain bar rather than + /// trapping on out-of-range string indexing. + @Test + static func barWithLabelNarrowWidth() { + // width < 11 -> plain bar, no label. + #expect(String.barWithLabel(fraction: 0.5, width: 4) == "██ ") + #expect(String.barWithLabel(fraction: 0.5, width: 0) == "") + #expect(String.barWithLabel(fraction: 0.5, width: -5) == "") + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BinTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BinTests.swift new file mode 100644 index 00000000..7fc791ec --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/BinTests.swift @@ -0,0 +1,141 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Testing +import Numerics + +@Suite +private enum BinTests { + @Test + static func roundingBinSpan() { + #expect(roundedBinSpan(0.7).isApproximatelyEqual(to: 0.7, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.6).isApproximatelyEqual(to: 0.6, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.9).isApproximatelyEqual(to: 0.9, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(1.0).isApproximatelyEqual(to: 1.0, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(1.1).isApproximatelyEqual(to: 1.2, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(1.2).isApproximatelyEqual(to: 1.2, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(1.3).isApproximatelyEqual(to: 1.4, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(1.4).isApproximatelyEqual(to: 1.4, absoluteTolerance: 0.000_1)) + + #expect(roundedBinSpan(0.07).isApproximatelyEqual(to: 0.07, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.06).isApproximatelyEqual(to: 0.06, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.09).isApproximatelyEqual(to: 0.09, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.10).isApproximatelyEqual(to: 0.10, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.11).isApproximatelyEqual(to: 0.1, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.12).isApproximatelyEqual(to: 0.12, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.13).isApproximatelyEqual(to: 0.14, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.14).isApproximatelyEqual(to: 0.14, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.15).isApproximatelyEqual(to: 0.14, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.16).isApproximatelyEqual(to: 0.16, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.17).isApproximatelyEqual(to: 0.18, absoluteTolerance: 0.000_1)) + + #expect(roundedBinSpan(0.070).isApproximatelyEqual(to: 0.070, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.071).isApproximatelyEqual(to: 0.072, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.072).isApproximatelyEqual(to: 0.072, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.073).isApproximatelyEqual(to: 0.074, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.074).isApproximatelyEqual(to: 0.074, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.075).isApproximatelyEqual(to: 0.076, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.076).isApproximatelyEqual(to: 0.076, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.077).isApproximatelyEqual(to: 0.078, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.078).isApproximatelyEqual(to: 0.078, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.079).isApproximatelyEqual(to: 0.080, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.080).isApproximatelyEqual(to: 0.080, absoluteTolerance: 0.000_1)) + + #expect(roundedBinSpan(0.20562968179143173).isApproximatelyEqual(to: 0.200, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(0.21562968179143173).isApproximatelyEqual(to: 0.220, absoluteTolerance: 0.000_1)) + + // Non-positive / non-finite inputs must not produce NaN. + #expect(roundedBinSpan(0) == 0) + #expect(roundedBinSpan(-1.3).isApproximatelyEqual(to: -1.4, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(-0.072).isApproximatelyEqual(to: -0.072, absoluteTolerance: 0.000_1)) + #expect(roundedBinSpan(.nan) == 0) + #expect(roundedBinSpan(.infinity) == 0) + } + + @Test + static func binRangesFromData() throws { + let bins: [Range] = try #require(binRanges(data: data)).map { r -> Range in + let lower = Int((r.lowerBound * 1000).rounded(.toNearestOrAwayFromZero)) + let upper = Int((r.upperBound * 1000).rounded(.toNearestOrAwayFromZero)) + return lower.. String { + o.text +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/ThroughputEstimatorInfinityTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/ThroughputEstimatorInfinityTests.swift new file mode 100644 index 00000000..11743c56 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Output/ThroughputEstimatorInfinityTests.swift @@ -0,0 +1,66 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +@testable import IMAPToolLib +import Testing + +@Suite("ThroughputEstimator — degenerate durations") +enum ThroughputEstimatorInfinityTests { + + /// Bug #7: `didComplete` allows a batch through on the `60 < count` branch even when + /// the elapsed duration is zero, then divides by it — producing an infinite rate. + @Test + static func manyCompletionsAtSameInstantStayFinite() { + let t0 = Date(timeIntervalSinceReferenceDate: 10_000) + var estimator = ThroughputEstimator(now: t0) + + var emitted: [Double] = [] + for _ in 0..<100 { + if let throughput = estimator.didComplete(now: t0) { + emitted.append(throughput.tasksPerSecond) + } + } + + #expect( + emitted.allSatisfy { $0.isFinite && $0 >= 0 }, + "60+ completions within a zero-length interval produced a non-finite throughput: \(emitted)." + ) + } + + /// Bug #7 (cont.): A backward clock adjustment yields a negative duration, so the + /// same branch produces a negative throughput. + @Test + static func backwardClockDoesNotProduceNegativeRate() { + let t0 = Date(timeIntervalSinceReferenceDate: 10_000) + let earlier = t0.addingTimeInterval(-1) + var estimator = ThroughputEstimator(now: t0) + + var emitted: [Double] = [] + for _ in 0..<100 { + if let throughput = estimator.didComplete(now: earlier) { + emitted.append(throughput.tasksPerSecond) + } + } + + #expect( + emitted.allSatisfy { $0.isFinite && $0 >= 0 }, + "A backward clock adjustment produced a negative/non-finite throughput: \(emitted)." + ) + } +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/StableMailboxNameSortingTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/StableMailboxNameSortingTests.swift new file mode 100644 index 00000000..891a257d --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/StableMailboxNameSortingTests.swift @@ -0,0 +1,151 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import NIOIMAP +import Testing + +@Suite("Stable mailbox-name comparison") +private enum StableMailboxNameSortingTests { + struct CompareFixture: Sendable, CustomTestStringConvertible { + var lhs: MailboxName + var rhs: MailboxName + var expected: Bool + var note: String + + var testDescription: String { note } + } + + @Test(arguments: [ + // INBOX always comes before any non-INBOX mailbox. + CompareFixture( + lhs: .inbox, + rhs: name("Drafts"), + expected: true, + note: "INBOX < Drafts" + ), + CompareFixture( + lhs: name("Drafts"), + rhs: .inbox, + expected: false, + note: "Drafts !< INBOX" + ), + CompareFixture( + lhs: .inbox, + rhs: name("AAA"), + expected: true, + note: "INBOX < AAA (even though byte-wise A < I)" + ), + // INBOX is case-insensitive — `MailboxName` normalizes any spelling to "INBOX". + CompareFixture( + lhs: name("inbox"), + rhs: name("Drafts"), + expected: true, + note: "lowercase inbox normalized to INBOX, still wins" + ), + + // Two INBOXes are equivalent. + CompareFixture( + lhs: .inbox, + rhs: .inbox, + expected: false, + note: "INBOX !< INBOX" + ), + + // Byte-wise ordering of non-INBOX names. + CompareFixture( + lhs: name("Drafts"), + rhs: name("Sent"), + expected: true, + note: "Drafts < Sent" + ), + CompareFixture( + lhs: name("Sent"), + rhs: name("Drafts"), + expected: false, + note: "Sent !< Drafts" + ), + + // Byte-exact comparison: uppercase precedes lowercase in ASCII. + CompareFixture( + lhs: name("ABC"), + rhs: name("abc"), + expected: true, + note: "ABC < abc (byte-exact)" + ), + + // Length tiebreak: when one is a prefix of the other, the shorter wins. + CompareFixture( + lhs: name("Foo"), + rhs: name("Foobar"), + expected: true, + note: "prefix < longer" + ), + CompareFixture( + lhs: name("Foobar"), + rhs: name("Foo"), + expected: false, + note: "longer !< prefix" + ), + + // Equal names compare false (strict less-than). + CompareFixture( + lhs: name("Drafts"), + rhs: name("Drafts"), + expected: false, + note: "Drafts !< Drafts" + ), + ]) + static func compare(fixture: CompareFixture) { + #expect(stableCompare(fixture.lhs, fixture.rhs) == fixture.expected) + } + + /// Higher-level check: `stableCompare` is suitable as a `<` predicate for + /// `sorted(by:)` — INBOX leads, the rest follow in byte order. + @Test + static func sortsAsExpected() { + let input: [MailboxName] = [ + name("Sent"), + name("Drafts"), + .inbox, + name("Archive"), + name("Trash"), + ] + let sorted = input.sorted(by: stableCompare) + let expected: [MailboxName] = [ + .inbox, + name("Archive"), + name("Drafts"), + name("Sent"), + name("Trash"), + ] + #expect(sorted == expected) + } + + /// `MailboxName` stores raw bytes (modified UTF-7 on the wire), so the + /// comparison is byte-exact and unaware of encoding. Names that decode to + /// the same display string but differ in their byte representation are + /// treated as distinct, ordered by their bytes. + @Test + static func comparesRawBytes() { + let a = MailboxName([0x41, 0x42]) // "AB" + let b = MailboxName([0x41, 0x42, 0x43]) // "ABC" + #expect(stableCompare(a, b)) + #expect(!stableCompare(b, a)) + } +} + +private func name(_ s: String) -> MailboxName { + MailboxName(Array(s.utf8)) +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/TimeoutSupport.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/TimeoutSupport.swift new file mode 100644 index 00000000..cfce8046 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/TimeoutSupport.swift @@ -0,0 +1,64 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +/// A one-shot async gate. +/// +/// Used to race an operation against a timeout *without* structured `await`-ing the +/// operation task, so an operation that stalls on a non-cancellable continuation +/// surfaces as a deterministic test failure instead of freezing the whole suite. +actor CompletionGate { + private var resolved: Bool? + private var waiters: [CheckedContinuation] = [] + + func resolve(_ value: Bool) { + guard resolved == nil else { return } + resolved = value + for w in waiters { + w.resume(returning: value) + } + waiters = [] + } + + func wait() async -> Bool { + if let resolved { return resolved } + return await withCheckedContinuation { c in + waiters.append(c) + } + } +} + +/// Runs `operation` and returns `true` if it finished within `seconds`, `false` if it +/// timed out (i.e. stalled). +/// +/// The operation runs in an unstructured task. On timeout that task is cancelled and +/// abandoned — if it is stuck on a non-cancellable continuation it will leak, which is +/// acceptable for a bug-reproduction test that would otherwise stall forever. +func finishesWithoutStalling( + within seconds: Double = 5, + _ operation: @escaping @Sendable () async -> Void +) async -> Bool { + let gate = CompletionGate() + let work = Task { + await operation() + await gate.resolve(true) + } + let timer = Task { + try? await Task.sleep(for: .seconds(seconds)) + await gate.resolve(false) + } + let finished = await gate.wait() + work.cancel() + timer.cancel() + return finished +} diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/TokenBucketTests.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/TokenBucketTests.swift new file mode 100644 index 00000000..56bd7bd1 --- /dev/null +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/TokenBucketTests.swift @@ -0,0 +1,182 @@ +//===----------------------------------------------------------------------===// +// +// 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 IMAPToolLib +import Testing + +@Suite +struct TokenBucketTests { + @Test + func acquireAndReleaseSingleToken() async throws { + let bucket = TokenBucket(tokens: 1) + let result = try await bucket.withToken { 42 } + #expect(result == 42) + + // The token was returned, so we can acquire again. + let again = try await bucket.withToken { 7 } + #expect(again == 7) + } + + @Test + func tokenIsReturnedAfterThrowing() async throws { + let bucket = TokenBucket(tokens: 1) + struct Boom: Swift.Error {} + + await #expect(throws: Boom.self) { + try await bucket.withToken { throw Boom() } + } + + // After a throwing body the token should still be back in the bucket. + let value = try await bucket.withToken { "ok" } + #expect(value == "ok") + } + + @Test + func boundsConcurrencyToTokenCount() async { + let tokens = 3 + let bucket = TokenBucket(tokens: tokens) + let observer = ConcurrencyObserver() + + await withTaskGroup(of: Void.self) { group in + for _ in 0..<20 { + group.addTask { + try? await bucket.withToken { + await observer.didEnter() + // A short sleep so several tasks can pile up while + // another is holding a token. + try? await Task.sleep(for: .milliseconds(5)) + await observer.didExit() + } + } + } + } + + let peak = await observer.peak + #expect(peak <= tokens) + // Also verify that the bucket is saturated at some point. + #expect(peak >= 1) + } + + @Test + func allWaitersEventuallyComplete() async { + // With one token and many waiters, every task must still finish — + // i.e. each release wakes exactly one waiter, no waiters are dropped. + let bucket = TokenBucket(tokens: 1) + let counter = CompletionCounter() + + await withTaskGroup(of: Void.self) { group in + for _ in 0..<25 { + group.addTask { + try? await bucket.withToken { + await counter.increment() + } + } + } + } + + let completed = await counter.value + #expect(completed == 25) + } + + @Test + func cancellingAParkedWaiterThrowsPromptly() async throws { + // No tokens -> any `withToken` parks immediately. A cancelled waiter + // must throw `CancellationError` rather than stall forever. + let bucket = TokenBucket(tokens: 0) + let task = Task { + try await bucket.withToken {} + } + task.cancel() + + // Race the result against a timeout so a regression fails the test + // instead of stalling the whole suite. + let threwCancellation = await withTaskGroup(of: Bool.self) { group in + group.addTask { + do { + try await task.value + return false + } catch is CancellationError { + return true + } catch { + return false + } + } + group.addTask { + try? await Task.sleep(for: .seconds(5)) + return false // timed out + } + let first = await group.next()! + group.cancelAll() + return first + } + #expect(threwCancellation) + } + + @Test + func cancellingAWaiterKeepsAccountingBalanced() async throws { + let bucket = TokenBucket(tokens: 1) + + let acquired = AsyncStream.makeStream(of: Void.self) + let release = AsyncStream.makeStream(of: Void.self) + + // A holder that takes the only token and keeps it until released. + let holder = Task { + try await bucket.withToken { + acquired.continuation.yield(()) + var it = release.stream.makeAsyncIterator() + _ = await it.next() + } + } + + // Wait until the holder actually holds the token. + var acquiredIterator = acquired.stream.makeAsyncIterator() + _ = await acquiredIterator.next() + + // With the token held, this waiter parks; cancelling it must throw. + let waiter = Task { try await bucket.withToken {} } + waiter.cancel() + await #expect(throws: CancellationError.self) { + try await waiter.value + } + + // Release the holder; the token must be back in the bucket. + release.continuation.yield(()) + _ = try await holder.value + + let value = try await bucket.withToken { 99 } + #expect(value == 99) + } +} + +private actor ConcurrencyObserver { + private(set) var current = 0 + private(set) var peak = 0 + + func didEnter() { + current += 1 + if current > peak { peak = current } + } + + func didExit() { + current -= 1 + } +} + +private actor CompletionCounter { + private(set) var value = 0 + + func increment() { + value += 1 + } +} diff --git a/Examples/README.md b/Examples/README.md index d6ec65da..5978fd1b 100644 --- a/Examples/README.md +++ b/Examples/README.md @@ -1,16 +1,18 @@ # Examples -This directory contains example projects built on top of `swift-nio-imap`. +This directory contains example and tool projects built on top of `swift-nio-imap`. Each subdirectory is its **own standalone Swift package** that depends on the library in the repository root via a local path dependency (`.package(path: "../..")`). Keeping them out of the root package means the library's own dependency graph stays -minimal — consumers of `NIOIMAP` don't resolve example-only dependencies such as -`swift-log` or `swift-nio-ssl`. +smaller — consumers don't resolve example-only dependencies such as `ArgumentParser`. +(Dependencies that the library products themselves use — for example `swift-log`, which +`IMAPCommands` depends on — remain part of the root package's graph.) | Example | What it is | | --- | --- | -| [`CLI`](CLI) | A command-line interface plus its supporting `CLILib` (with tests). | +| [`IMAPTool`](IMAPTool) | Command-line IMAP debugging tool (`imap-tool`) built on the `IMAPToolLib` library product. | +| [`CLI`](CLI) | A smaller command-line interface plus its supporting `CLILib` (with tests). | | [`Proxy`](Proxy) | An IMAP proxy that logs the traffic flowing through it. | | [`Fuzzer`](Fuzzer) | Fuzzing harness for the IMAP parser (`NIOIMAPFuzzer`). | | [`PerformanceTester`](PerformanceTester) | Micro-benchmarks for parsing/encoding (`NIOIMAPPerformanceTester`). | @@ -20,8 +22,8 @@ minimal — consumers of `NIOIMAP` don't resolve example-only dependencies such Each example builds independently. From the repository root: ```sh -swift build --package-path Examples/CLI -swift run --package-path Examples/CLI CLI --help +swift build --package-path Examples/IMAPTool +swift run --package-path Examples/IMAPTool imap-tool --help ``` Because they are separate packages, `swift build` / `swift test` at the repository diff --git a/Package.swift b/Package.swift index 0ebd64aa..57e7e36e 100644 --- a/Package.swift +++ b/Package.swift @@ -14,18 +14,26 @@ let package = Package( .visionOS(.v2), ], products: [ - .library(name: "NIOIMAP", targets: ["NIOIMAP"]) + .library(name: "NIOIMAP", targets: ["NIOIMAP"]), + .library(name: "IMAPCommands", targets: ["IMAPCommands"]), ], dependencies: [ + .package(url: "https://github.com/apple/swift-collections", "1.4.0"..<"2.0.0"), + .package(url: "https://github.com/apple/swift-nio-extras", from: "1.0.0"), + .package(url: "https://github.com/apple/swift-nio-ssl", from: "2.24.0"), .package(url: "https://github.com/apple/swift-nio", from: "2.64.0"), - .package(url: "https://github.com/apple/swift-collections.git", "1.1.0"..<"2.0.0"), + // 1.14.0 introduced the task-local `withLogger` / `Logger.current` APIs. + .package(url: "https://github.com/apple/swift-log", from: "1.14.0"), ], targets: [ .target( name: "NIOIMAP", dependencies: [ - "NIOIMAPCore" + .target(name: "NIOIMAPCore") ], + // The documentation is built out-of-band, not by SwiftPM: excluding the catalog + // keeps it out of the build product instead of being copied in as a resource. + exclude: ["NIOIMAP.docc"], swiftSettings: [ .enableUpcomingFeature("MemberImportVisibility") ] @@ -33,8 +41,8 @@ let package = Package( .testTarget( name: "NIOIMAPTests", dependencies: [ - "NIOIMAP", - "NIOIMAPCore", + .target(name: "NIOIMAP"), + .target(name: "NIOIMAPCore"), .product(name: "NIO", package: "swift-nio"), .product(name: "NIOTestUtils", package: "swift-nio"), ], @@ -59,7 +67,7 @@ let package = Package( .testTarget( name: "NIOIMAPCoreTests", dependencies: [ - "NIOIMAPCore", + .target(name: "NIOIMAPCore"), .product(name: "NIO", package: "swift-nio"), .product(name: "NIOTestUtils", package: "swift-nio"), .product(name: "OrderedCollections", package: "swift-collections"), @@ -68,5 +76,35 @@ let package = Package( .enableUpcomingFeature("MemberImportVisibility") ] ), + + .target( + name: "IMAPCommands", + dependencies: [ + .target(name: "NIOIMAP"), + .product(name: "NIO", package: "swift-nio"), + .product(name: "NIOSSL", package: "swift-nio-ssl"), + .product(name: "NIOExtras", package: "swift-nio-extras"), + .product(name: "Logging", package: "swift-log"), + ], + exclude: ["IMAPCommands.docc"], + swiftSettings: [ + // The closure-taking APIs are caller-isolated: their closures need to be able to + // capture, mutate and return non-`Sendable` state belonging to whatever actor + // called them. That requires both the methods and the closure types to be + // `nonisolated(nonsending)`, which is what this makes the default. + .enableUpcomingFeature("NonisolatedNonsendingByDefault") + ] + ), + .testTarget( + name: "IMAPCommandsTests", + dependencies: [ + .target(name: "IMAPCommands"), + .target(name: "NIOIMAP"), + .product(name: "Logging", package: "swift-log"), + ], + swiftSettings: [ + .enableUpcomingFeature("NonisolatedNonsendingByDefault") + ] + ), ] ) diff --git a/README.md b/README.md index 7e578a8a..61e7962c 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,115 @@ # swift-nio-imap -A Swift project that provides an implementation of the IMAP4rev1 protocol, built upon SwiftNIO. +A Swift implementation of the IMAP4rev1 protocol (RFC 3501 and related RFCs), built on [SwiftNIO](https://github.com/apple/swift-nio). -This project implements: - * Parsing IMAPv4 wire-format to type-safe Swift data structures - * Encoding these Swift data structures to the IMAPv4 wire format - * Extensive support for common IMAP extensions - * Integration with SwiftNIO +It is intended as a building block for mail clients and servers, and provides: -For a list of IMAP extensions, see SupportedExtensions.md in the documentation. +* Parsing of the IMAPv4 wire format into type-safe Swift values +* Encoding of those Swift values back into the IMAPv4 wire format +* Extensive support for common IMAP extensions +* Integration with SwiftNIO, plus an imperative-style `async`/`await` client interface -⚠️ **Note:** This library is still in development phases and not ready to be used in production system yet. ⚠️ +> ⚠️ **Note:** This library is still under development and is not yet ready for use in production systems. ⚠️ -### Introduction and Usage +## Overview -`swift-nio-imap` implements the IMAP4rev1 protocol described in RFC 3501 and related RFCs. It is intended as a building block to build mail clients and/or servers. It is built upon SwiftNIO v2.x. +The package is layered, so you can work at whichever level suits your needs: -To use the framework use `import NIOIMAP`. NIOIMAP supports a variety of IMAP extensions, check `EXTENSIONS.md` for full details. +| Module | What it gives you | +| --- | --- | +| **`NIOIMAPCore`** | The IMAP grammar as Swift types, plus the parser and encoder that convert between those types and the wire format. No networking. | +| **`NIOIMAP`** | SwiftNIO `ChannelHandler`s — `IMAPClientHandler` and `IMAPServerHandler` — that plug the parser/encoder into a `ChannelPipeline`. Re-exports `NIOIMAPCore`. | +| **`IMAPCommands`** | An imperative-style `async`/`await` client built on top of `NIOIMAP`, centered on `IMAPConnection`. | -### Example Exchange +`NIOIMAPCore` and `NIOIMAP` are the foundation. On top of them, the package offers **two different client interfaces**, described next. -As a quick example, here’s part of the the exchange listed in RFC 3501 section 8, where lines starting with S: and C: are from the server and client respectively: +## Two client interfaces — pick the one that fits you + +There are two distinct ways to drive an IMAP conversation with this package. They are **two different interface styles**, offered on purpose. + +**Neither is preferred over the other**, and neither is "higher level" in a way that makes it the default choice. One will be a better fit for some clients; the other will be a better fit for others. Choose based on how *your* code wants to be structured — not on any recommendation from us, because we intentionally don't make one. + +### Interface A — Command-centric (`IMAPCommands`) + +An imperative `async`/`await` interface. You open a connection, send commands, and `await` their responses as ordinary asynchronous calls. Commands can be pipelined by sending them concurrently from a task group. + +This style fits code that wants to express an IMAP session as a straightforward sequence (or concurrent set) of "send command → handle its responses" steps. + +```swift +import IMAPCommands + +let configuration = IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 993, + useTLS: true, + logging: .noLogging +) + +try await IMAPConnection.withConnection(configuration: configuration) { greeting, connection in + // Log in. + try await connection.send(.login(username: "mrc", password: "secret")) { tag, responses in + try await responses.waitForCompletion() + } + + // Select a mailbox and inspect the untagged responses it produces. + try await connection.send(.select(.inbox)) { tag, responses in + try await responses.forEach { response in + print(response) + } + } +} +``` + +`IMAPCommands` also provides dedicated APIs for the commands that don't fit the simple request/response shape — `sendIdle` for `IDLE`, `sendAuthenticate` for `AUTHENTICATE` challenge/response, and `append` for streaming an `APPEND`. + +### Interface B — Event stream (`NIOIMAP` channel handlers) + +An event-driven, stream-based interface. `NIOIMAP` provides a pair of SwiftNIO `ChannelHandler`s — `IMAPClientHandler` and `IMAPServerHandler` — that you insert into a `ChannelPipeline`. Wrapped in a `NIOAsyncChannel`, you write `CommandStreamPart` values to the outbound writer and consume decoded `Response` values from the inbound stream. + +This style fits code that already lives in a SwiftNIO pipeline, or that wants direct control over the stream of protocol events and encoding options. + +```swift +import NIOIMAP + +// Connect and wrap the channel so the handler's decoded `Response`s and the +// commands we write flow through async sequences. +let channel = try await ClientBootstrap(group: MultiThreadedEventLoopGroup.singleton) + .connect(host: "mail.example.com", port: 143) + .flatMap { channel in + channel.eventLoop.makeCompletedFuture { + try channel.pipeline.syncOperations.addHandler(IMAPClientHandler()) + return try NIOAsyncChannel( + wrappingChannelSynchronously: channel + ) + } + } + .get() + +try await channel.executeThenClose { inbound, outbound in + // Send a command. + try await outbound.write( + .part(.tagged(TaggedCommand(tag: "a001", command: .login(username: "mrc", password: "secret")))) + ) + + // Consume the stream of decoded responses. + for try await response in inbound { + print(response) + } +} +``` + +### Which should I use? + +Both interfaces talk to the same server and share the same `NIOIMAPCore` types for commands and responses. As a rough guide: + +* Reach for **`IMAPCommands`** when you'd rather write `let response = try await connection.send(...)` and treat each command as an awaitable unit of work. +* Reach for **`NIOIMAP`** when you want to work directly with the SwiftNIO pipeline and consume the raw stream of protocol events. + +If neither obviously fits, prototype the part of your client you care about most in each — they're deliberately close in capability, and the better fit usually becomes clear quickly. + +## The shared type layer + +Whichever interface you choose, commands and responses are the same strongly typed `NIOIMAPCore` values. Here's part of the exchange from RFC 3501 §8, where `S:` and `C:` lines are from the server and client respectively: ```text S: * OK IMAP4rev1 Service Ready @@ -29,42 +118,70 @@ S: a001 OK LOGIN completed C: a002 select inbox S: * 18 EXISTS S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) -S: * 2 RECENT -S: * OK [UNSEEN 17] Message 17 is the first unseen message S: * OK [UIDVALIDITY 3857529045] UIDs valid -S: a002 OK [READ-WRITE] SELECT completed``` +S: a002 OK [READ-WRITE] SELECT completed ``` -The first 3 lines would correspond to the following in SwiftNIO IMAP: +The client commands above are represented as: + +```swift +CommandStreamPart.tagged(TaggedCommand(tag: "a001", command: .login(username: "mrc", password: "secret"))) +CommandStreamPart.tagged(TaggedCommand(tag: "a002", command: .select(.inbox))) +``` + +And the server responses as: + ```swift Response.untagged(.conditionalState(.ok(ResponseText(text: "IMAP4rev1 Service Ready")))) -CommandStreamPart.tagged(TaggedCommand(tag: "a001", command: .login(username: "mrc", password: "secret"))) Response.tagged(.init(tag: "a001", state: .ok(ResponseText(text: "LOGIN completed")))) -``` - -Next, up is the SELECT command and its responses, which are more interesting: -```swift -CommandStreamPart.tagged(TaggedCommand(tag: "a002", command: .select(MailboxName("box1"), []))) Response.untagged(.mailboxData(.exists(18))) Response.untagged(.mailboxData(.flags([.answered, .flagged, .deleted, .seen, .draft]))) -Response.untagged(.mailboxData(.recent(2))) -Response.untagged(.conditionalState(.ok(ResponseText(code: .unseen(17), text: "Message 17 is the first unseen message")))) Response.untagged(.conditionalState(.ok(ResponseText(code: .uidValidity(3857529045), text: "UIDs valid")))) Response.tagged(.init(tag: "a002", state: .ok(ResponseText(code: .readWrite, text: "SELECT completed")))) ``` -There’s more going on here than this example shows. But this gives a general idea of how the types look and feel. +This gives a general feel for how the types look. See the DocC documentation for `NIOIMAPCore` for the full command and response grammar. -### Integration with SwiftNIO +## Adding the dependency -SwiftNIO IMAP provides a pair of ChannelHandler objects that can be integrated into a SwiftNIO ChannelPipeline. This allows sending IMAP commands using NIO Channels. +Add the package to your `Package.swift`: -The two handlers SwiftNIO IMAP provides are IMAPClientHandler and IMAPServerHandler. Each of these can be inserted into the ChannelPipeline. They can then be used to encode and decode messages. For example: ```swift -let group = MultiThreadedEventLoopGroup(numberOfThreads: 1) -let channel = try await ClientBootstrap(group).channelInitializer { channel in - channel.pipeline.addHandler(IMAPClientHandler()) -}.connect(host: example.com, port: 143).get() - -try await channel.writeAndFlush(.part(CommandStreamPart.tagged(TaggedCommand(tag: "a001", command: .login(username: "mrc", password: "secret")))), promise: nil) +dependencies: [ + .package(url: "https://github.com/apple/swift-nio-imap.git", from: "0.4.0"), +], ``` + +Then depend on the module for the interface you chose: + +```swift +.target( + name: "MyMailClient", + dependencies: [ + // Command-centric interface (also pulls in NIOIMAP and NIOIMAPCore): + .product(name: "IMAPCommands", package: "swift-nio-imap"), + // ...or the event-stream interface on its own: + .product(name: "NIOIMAP", package: "swift-nio-imap"), + ] +) +``` + +The package requires Swift 6.2, supports macOS 15 and iOS 18 (or later), and is built on SwiftNIO 2.x. + +## Examples + +The [`Examples`](Examples) directory contains standalone packages that build on this library, including a command-line IMAP debugging tool (`imap-tool`), a smaller CLI, a logging proxy, a parser fuzzer, and performance benchmarks. Each is its own Swift package with a local path dependency on the repository root, so the library's own dependency graph stays minimal. + +See [`Examples/README.md`](Examples/README.md) for details on building and running them. + +## Supported extensions + +`swift-nio-imap` supports a wide range of IMAP extensions. For the full list, see [`SupportedExtensions`](Sources/NIOIMAPCore/NIOIMAPCore.docc/SupportedExtensions.md) in the `NIOIMAPCore` DocC documentation. + +## Contributing + +Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before opening a pull request. Security issues should be reported as described in [SECURITY.md](SECURITY.md). + +## License + +`swift-nio-imap` is released under the Apache 2.0 license. See [LICENSE.txt](LICENSE.txt) for details. diff --git a/Sources/IMAPCommands/AppendWriter.swift b/Sources/IMAPCommands/AppendWriter.swift new file mode 100644 index 00000000..6b9ce938 --- /dev/null +++ b/Sources/IMAPCommands/AppendWriter.swift @@ -0,0 +1,302 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP + +extension IMAPConnection { + /// Writes message data to the server as part of an `APPEND` command. + /// + /// Create an append writer using ``IMAPConnection/append(to:writing:reading:)`` or + /// ``IMAPConnection/append(to:_:)``. + public struct AppendWriter: ~Copyable, Sendable { + var underlying: OutboundQueue.AppendQueueWriter + var state: State + + /// Tracks how far along the `APPEND` command is. + /// + /// Only some sequences of append data are valid IMAP, and the writer must not emit an + /// invalid one — the client state machine treats that as a programming error and traps. + enum State: Hashable { + /// Nothing written yet: `APPEND` needs at least one message. + case empty + /// At least one complete message, and no partial one: the command can be finished. + case complete + /// A message was begun but never completed. Nothing more can be written, and the + /// command cannot be finished. + case incomplete + /// The command has been written in full. Nothing more can be written, and the + /// server's `TaggedResponse` can now arrive. + case finished + } + + fileprivate init( + underlying: consuming OutboundQueue.AppendQueueWriter, + state: State + ) { + self.underlying = underlying + self.state = state + } + + static func withAppendWriter( + tag: String, + appendingTo mailbox: MailboxName, + underlying: consuming OutboundQueue.AppendQueueWriter, + didCompleteCommand: inout Bool, + closure: nonisolated(nonsending) (inout AppendWriter) async throws -> R + ) async throws -> R { + try await underlying.write([.start(tag: tag, appendingTo: mailbox)]) + var writer = AppendWriter(underlying: underlying, state: .empty) + do { + let r = try await closure(&writer) + // Completing the command is idempotent, so this is a no-op if the closure + // already did it in order to read the command's responses. + try await writer.finish() + didCompleteCommand = true + return r + } catch { + // Report whether the command made it out in full: if it didn't, the server is + // left waiting for the rest of it and the connection cannot be reused. + didCompleteCommand = (writer.state == .finished) + throw error + } + } + + /// Completes the `APPEND` command. + /// + /// The server only sends the command's `TaggedResponse` once the command has been + /// written in full, so call this before waiting for the command to complete: + /// + /// ```swift + /// try await connection.append(to: mailbox) { tag, responses, writer in + /// try await writer.write(message: message) { messageWriter in + /// try await messageWriter.write(messageBytes: bytes) + /// } + /// try await writer.finish() + /// return try await responses.waitForCompletion() + /// } + /// ``` + /// + /// Calling this is optional and idempotent: ``IMAPConnection/append(to:_:)`` + /// completes the command when its closure returns. + /// + /// - Throws: ``IMAPConnection/IncompleteAppend`` if no message was written, or if a + /// message was begun but never finished. Neither can be completed. + /// ``IMAPConnection/Error`` if the connection fails or is closed while the final + /// part of the command is going out. + /// - Important: The command is over once this returns, so writing any further message + /// throws ``IMAPConnection/AppendAlreadyFinished``. Write everything you mean to append + /// before finishing. + public mutating func finish() async throws { + guard + state != .finished + else { return } + try state.checkIsComplete() + try await underlying.write([.finish]) + state = .finished + } + } + + /// An error indicating that an `APPEND` command cannot be completed. + /// + /// The partially written command cannot be taken back, so the connection is closed. + public struct IncompleteAppend: Swift.Error, Hashable, Sendable { + /// Why the command cannot be completed. + public enum Reason: Hashable, Sendable { + /// No message was written. `APPEND` requires at least one message — or one + /// catenated message. + case noMessage + /// A message was begun but never completed, typically because writing it failed + /// and the error was not propagated. + case unfinishedMessage + } + + public var reason: Reason + + public init(reason: Reason) { + self.reason = reason + } + } + + /// An error indicating that append data was written after the `APPEND` command was + /// completed by ``AppendWriter/finish()``. + public struct AppendAlreadyFinished: Swift.Error, Hashable, Sendable { + public init() {} + } +} + +extension IMAPConnection.AppendWriter.State { + /// Throws if the command is in a state that nothing more can be written in. + func checkCanWrite() throws { + switch self { + case .empty, .complete: + break + case .incomplete: + throw IMAPConnection.IncompleteAppend(reason: .unfinishedMessage) + case .finished: + throw IMAPConnection.AppendAlreadyFinished() + } + } + + /// Throws unless at least one complete message has been written. + func checkIsComplete() throws { + switch self { + case .complete, .finished: + break + case .empty: + throw IMAPConnection.IncompleteAppend(reason: .noMessage) + case .incomplete: + throw IMAPConnection.IncompleteAppend(reason: .unfinishedMessage) + } + } +} + +extension IMAPConnection.AppendWriter { + /// Writes a message to be appended. + /// + /// The closure must write exactly as many bytes as the `byteCount` of `message`'s + /// `AppendData` declares: that count goes out ahead of the data as the literal's length, + /// and the server reads precisely that many bytes as the message. Writing a different number + /// desynchronizes the command stream, leaving the connection unusable. + /// + /// If the closure throws, the message — and with it the whole `APPEND` command — is left + /// unfinished: nothing more can be written, and the command cannot be completed. Even if + /// the error is caught, `append` then throws ``IMAPConnection/IncompleteAppend`` and closes + /// the connection. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed, + /// ``IMAPConnection/IncompleteAppend`` if an earlier message was left unfinished, or + /// ``IMAPConnection/AppendAlreadyFinished`` if the command is already complete. + /// Rethrows whatever `closure` throws, unchanged. + public mutating func write( + message: AppendMessage, + closure: nonisolated(nonsending) (inout MessageWriter) async throws -> Void + ) async throws { + try state.checkCanWrite() + try await underlying.write([.beginMessage(message: message)]) + var w = MessageWriter(underlying: self.underlying) + do { + try await closure(&w) + } catch { + // The message was begun but not ended, so `self` stays `.incomplete`. + self = Self(underlying: w.underlying, state: .incomplete) + throw error + } + self = Self(underlying: w.underlying, state: .incomplete) + try await underlying.write([.endMessage]) + state = .complete + } + + public struct MessageWriter: ~Copyable, Sendable { + var underlying: OutboundQueue.AppendQueueWriter + + /// Writes message bytes to the server. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. + public mutating func write(messageBytes: ByteBuffer) async throws(IMAPConnection.Error) { + try await underlying.write([.messageBytes(messageBytes)]) + } + } +} + +extension IMAPConnection.AppendWriter { + /// Writes a catenated message — assembled from `IMAP URL`s and literal data — to be + /// appended. + /// + /// The closure must add at least one URL or one piece of data. As with + /// ``write(message:closure:)``, a failure part-way through leaves the `APPEND` + /// command unfinishable. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed, + /// ``IMAPConnection/IncompleteAppend`` if `closure` adds neither a URL nor data, or + /// ``IMAPConnection/AppendAlreadyFinished`` if the command is already complete. + /// Rethrows whatever `closure` throws, unchanged. + public mutating func catenate( + options: AppendOptions, + closure: nonisolated(nonsending) (inout CatenateWriter) async throws -> Void + ) async throws { + try state.checkCanWrite() + try await underlying.write([.beginCatenate(options: options)]) + var w = CatenateWriter(underlying: self.underlying, state: .empty) + do { + try await closure(&w) + } catch { + self = Self(underlying: w.underlying, state: .incomplete) + throw error + } + let catenateState = w.state + self = Self(underlying: w.underlying, state: .incomplete) + try catenateState.checkIsComplete() + try await underlying.write([.endCatenate]) + state = .complete + } + + public struct CatenateWriter: ~Copyable, Sendable { + var underlying: OutboundQueue.AppendQueueWriter + var state: State + + /// Adds the message the given `IMAP URL` refers to. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed, or + /// ``IMAPConnection/AppendAlreadyFinished`` if the command is already complete. + public mutating func writeURL( + _ bytes: ByteBuffer + ) async throws { + try state.checkCanWrite() + try await underlying.write([.catenateURL(bytes)]) + state = .complete + } + + /// Adds a message given as literal data. + /// + /// The closure must write exactly `byteCount` bytes, for the same reason + /// ``IMAPConnection/AppendWriter/write(message:closure:)`` requires: the count + /// goes out ahead of the data as the literal's length. Writing a different number + /// desynchronizes the command stream, leaving the connection unusable. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed, or + /// ``IMAPConnection/AppendAlreadyFinished`` if the command is already complete. + /// Rethrows whatever `closure` throws, unchanged. + public mutating func writeData( + byteCount: Int, + closure: nonisolated(nonsending) (inout CatenateDataWriter) async throws -> Void + ) async throws { + try state.checkCanWrite() + try await underlying.write([.catenateData(.begin(size: byteCount))]) + var w = CatenateDataWriter(underlying: self.underlying) + do { + try await closure(&w) + } catch { + self = CatenateWriter(underlying: w.underlying, state: .incomplete) + throw error + } + self = CatenateWriter(underlying: w.underlying, state: .incomplete) + try await underlying.write([.catenateData(.end)]) + state = .complete + } + } + + public struct CatenateDataWriter: ~Copyable, Sendable { + var underlying: OutboundQueue.AppendQueueWriter + + /// Writes message bytes to the server. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. + public mutating func write( + _ bytes: ByteBuffer + ) async throws(IMAPConnection.Error) { + try await underlying.write([.catenateData(.bytes(bytes))]) + } + } +} diff --git a/Sources/IMAPCommands/CommandStreamPartQueue.swift b/Sources/IMAPCommands/CommandStreamPartQueue.swift new file mode 100644 index 00000000..09bf6eec --- /dev/null +++ b/Sources/IMAPCommands/CommandStreamPartQueue.swift @@ -0,0 +1,307 @@ +//===----------------------------------------------------------------------===// +// +// 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 DequeModule +import NIO +import NIOIMAP + +/// A back-pressured queue of command stream parts flowing toward the channel’s outbound writer. +/// +/// Writers push parts into this queue, and the outbound runner pops them for writing to the channel. +struct CommandStreamPartQueue: Sendable { + var writeState: WriteState = .writing([]) + var readState: ReadState = .idle + + enum WriteState { + case closed + case failed + case writing(Deque) + } + + /// The `run(outbound:)` / `next()` method uses this to mark that it is waiting for more + /// data in the `InboundState`. + enum ReadState: Sendable { + case idle + /// When adding items to `pending`, if we’re in this state, run the continuation. + case waitingForItem(CheckedContinuation) + } +} + +extension CommandStreamPartQueue { + /// An item waiting to be written to the outbound writer. + struct PendingItem: Sendable { + var payload: [IMAPClientHandler.OutboundIn] + var completion: CheckedContinuation + } + + /// An item popped from the queue, ready to be written to the outbound writer. + /// + /// Run the `completions` after the write finishes. + struct Next: Sendable { + var payload: [IMAPClientHandler.OutboundIn] + var completions: [CheckedContinuation] + } +} + +// MARK: Close + +extension CommandStreamPartQueue { + struct CloseAction { + var writeCompletions: [CheckedContinuation] + var pendingRead: CheckedContinuation? + + func run() { + for c in writeCompletions { + c.resume(throwing: DidClose()) + } + pendingRead?.resume(returning: nil) + } + } + + struct DidClose: Swift.Error {} + + mutating func close() -> CloseAction { + let pendingWrites: Deque? + + switch writeState { + case .closed: + pendingWrites = nil + case .failed: + writeState = .closed + pendingWrites = nil + case .writing(let p): + // Must end up `.closed`: the pending items' completions are failed below, so + // leaving them in a `.writing` deque would let `next()` pop them and resume + // the same continuations a second time. It also makes any later `write()` + // park in a queue nobody drains instead of failing fast. + writeState = .closed + pendingWrites = p + } + + let pendingRead: CheckedContinuation? + switch readState { + case .idle: + pendingRead = nil + case .waitingForItem(let p): + pendingRead = p + } + readState = .idle + + return CloseAction( + writeCompletions: pendingWrites?.reduce(into: []) { + $0.append($1.completion) + } ?? [], + pendingRead: pendingRead + ) + } +} + +// MARK: - Pop & Merge + +extension Deque { + /// Pops pending items from the deque, merging small items up to a target write weight. + /// + /// Always pops at least one complete item. Continues merging while + /// the total weight stays below the target. + mutating func popAndMerge( + weightTarget: WriteWeight = WriteWeight(2 * 1_400) + ) -> CommandStreamPartQueue.Next? { + // We will always pop the complete, first item: + guard + let item = popFirst() + else { return nil } + var result = CommandStreamPartQueue.Next( + payload: item.payload, + completions: [item.completion] + ) + var totalWeight: WriteWeight = result.payload.reduce(into: WriteWeight(0)) { + $0 += $1.writeWeight + } + // We’ll then continue appending `parts` until we’ve + // reached the desired weight. + while var next = self.popFirst() { + result.moveParts( + from: &next.payload, + totalWeight: &totalWeight, + weightTarget: weightTarget + ) + // If there’s nothing left in `next`, add the + // completion continuation. Otherwise, write it back. + guard + next.payload.isEmpty + else { + self.prepend(next) + break + } + result.completions.append(next.completion) + } + return result + } +} + +extension CommandStreamPartQueue.Next { + mutating func moveParts( + from payload: inout [IMAPClientHandler.OutboundIn], + totalWeight: inout WriteWeight, + weightTarget: WriteWeight + ) { + Self.merge( + next: &self, + payload: &payload, + totalWeight: &totalWeight, + weightTarget: weightTarget + ) + } + + /// Moves parts from the given payload into `next` while the total weight stays below the target. + static func merge( + next: inout CommandStreamPartQueue.Next, + payload: inout [IMAPClientHandler.OutboundIn], + totalWeight: inout WriteWeight, + weightTarget: WriteWeight + ) { + var remaining = payload[...] + + while let part = remaining.first { + let weight = part.writeWeight + guard + totalWeight + weight < weightTarget + else { break } + _ = remaining.removeFirst() + totalWeight += weight + } + + // Now move the payload from `payload` to `next`: + next.payload.append(contentsOf: payload[payload.startIndex.., Result) + + func run() { + switch self { + case .none: + break + case .resumeContinuation(let continuation, let result): + continuation.resume(with: result) + } + } + } + + mutating func next( + _ continuation: CheckedContinuation + ) -> NextAction { + guard + case .idle = readState + else { + // `run(outbound:)` calls this serially, so we should always be + // `.idle` here. Fail the continuation rather than trapping if that + // invariant is ever violated. + return .resumeContinuation(continuation, .failure(.calledNextRecursively)) + } + + switch writeState { + case .closed: + return .resumeContinuation(continuation, .success(nil)) + case .failed: + return .resumeContinuation(continuation, .failure(.inFailedState)) + case .writing(var items): + // Pop the first item + guard + let item = items.popAndMerge() + else { + readState = .waitingForItem(continuation) + return .none + } + // Copy-on-write exclusivity dance: assigning the payload-free `.failed` + // case first drops `self`'s reference to the deque, so `items` is uniquely + // referenced when it is stored back and no copy-on-write copy is made. + writeState = .failed + writeState = .writing(items) + return .resumeContinuation(continuation, .success(.some(item))) + } + } +} + +// MARK: `write()` + +extension CommandStreamPartQueue { + enum WriteAction { + case none + case failWrite(CheckedContinuation, OutboundQueue.Error) + /// The `next()` function is waiting. Complete its continuation with the new data. + case resumeNext(CheckedContinuation, CommandStreamPartQueue.Next) + + func run() { + switch self { + case .none: + break + case .failWrite(let completion, let error): + completion.resume(throwing: error) + case .resumeNext(let nextContinuation, let next): + nextContinuation.resume(returning: next) + } + } + } + + mutating func write( + payload: [IMAPClientHandler.OutboundIn], + continuation: CheckedContinuation + ) -> WriteAction { + write( + item: PendingItem( + payload: payload, + completion: continuation + ) + ) + } + + mutating func write( + item: PendingItem + ) -> WriteAction { + switch writeState { + case .failed, .closed: + return .failWrite(item.completion, .inFailedState) + case .writing(var pending): + pending.append(item) + + // Check if `nextOutboundOut` is currently waiting for more items: + let action: WriteAction + switch readState { + case .idle: + action = .none + case .waitingForItem(let readContinuation): + if let next = pending.popAndMerge() { + readState = .idle + action = .resumeNext(readContinuation, next) + } else { + // Unreachable: we just appended an item, so `popAndMerge` + // always yields something. Leave the reader parked rather + // than trapping; a later write or `close()` will resume it. + action = .none + } + } + + writeState = .writing(pending) + + return action + } + } +} diff --git a/Sources/IMAPCommands/CompletedCommand.swift b/Sources/IMAPCommands/CompletedCommand.swift new file mode 100644 index 00000000..38def364 --- /dev/null +++ b/Sources/IMAPCommands/CompletedCommand.swift @@ -0,0 +1,81 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +/// A command that has completed with a tagged response from the server. +public struct CompletedCommand: Equatable, Sendable { + /// The tag identifying this command. + public var tag: IMAPConnection.Tag + /// The completion status from the server. + public var status: TaggedResponse.State + /// The time span from sending to completion. + public var duration: Duration +} + +/// A command that completed with an `OK` response. +public struct SuccessfulCommand: Equatable, Sendable { + /// The tag identifying this command. + public var tag: IMAPConnection.Tag + /// The response text from the server. + public var text: ResponseText + /// The time span from sending to completion. + public var duration: Duration +} + +// MARK: - + +extension SuccessfulCommand { + init(_ completed: CompletedCommand) throws { + guard case .ok(let text) = completed.status else { + throw CommandFailed(completedCommand: completed) + } + self.init( + tag: completed.tag, + text: text, + duration: completed.duration + ) + } +} + +private struct CommandFailed: Swift.Error { + var completedCommand: CompletedCommand +} + +extension CommandFailed: CustomStringConvertible { + var description: String { + let s: String + let text: ResponseText + switch self.completedCommand.status { + case .ok(let t): + s = "OK" + text = t + case .no(let t): + s = "NO" + text = t + case .bad(let t): + s = "BAD" + text = t + } + guard let code = text.code else { + return "Command \(self.completedCommand.tag) failed: \(s) \(text.text)" + } + return "Command \(self.completedCommand.tag) failed: \(s) \(String(reflecting: code)) \(text.text)" + } +} diff --git a/Sources/IMAPCommands/Configuration.swift b/Sources/IMAPCommands/Configuration.swift new file mode 100644 index 00000000..bbc6b0bb --- /dev/null +++ b/Sources/IMAPCommands/Configuration.swift @@ -0,0 +1,200 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +extension IMAPConnection { + /// Configuration for an IMAP server connection. + public struct Configuration: Equatable, Sendable { + /// The server endpoint to connect to. + public var endpoint: Endpoint + + /// The network endpoint for an IMAP server. + public enum Endpoint: Equatable, Sendable { + case hostname(String, port: UInt16) + case unixDomainSocket(path: String) + } + + /// Whether to use TLS for the connection. + public var useTLS: Bool + + /// Controls connection-level debug logging. + public enum Logging: Hashable, Sendable { + /// Does not trace channel events. + case noLogging + /// Traces every channel event to the task-local logger at the `.trace` level. + /// + /// - Warning: The traces include the data read and written, so they carry message + /// content and the commands sent to the server — including credentials. This is + /// for local debugging; do not enable it where the log stream is collected or + /// shipped off the device. + case logging + } + + /// The logging mode for the connection. + /// + /// This only controls the low-level channel-event tracing described by ``Logging``. It is + /// independent of the connection's own lifecycle diagnostics, which are always emitted to + /// the task-local logger at `.debug` and `.trace`. + public var logging: Logging + + public init( + endpoint: Endpoint, + useTLS: Bool, + logging: Logging + ) { + self.endpoint = endpoint + self.useTLS = useTLS + self.logging = logging + } + } +} + +extension IMAPConnection.Configuration { + public init( + hostname: String, + port: UInt16, + useTLS: Bool, + logging: Logging + ) { + self.init( + endpoint: .hostname(hostname, port: port), + useTLS: useTLS, + logging: logging + ) + } +} + +extension IMAPConnection.Configuration.Endpoint { + /// The hostname if this endpoint uses a hostname connection, or `nil` for UNIX domain sockets. + public var hostname: String? { + switch self { + case .hostname(let host, port: _): host + case .unixDomainSocket: nil + } + } +} + +extension IMAPConnection.Configuration { + init( + hostname: String, + port: UInt16, + logging: Logging + ) { + self.init( + hostname: hostname, + port: port, + useTLS: port == 993, + logging: logging + ) + } + + /// Creates a configuration by parsing an RFC 5092 IMAP URL or a hostname with optional port. + /// + /// - Throws: ``ParseServerTextError`` if `serverText` is neither a hostname with an optional + /// `:port` suffix nor a valid `imap:` URL. + public init( + serverText: String, + logging: Logging + ) throws(ParseServerTextError) { + if let c = Self(hostnameAndPortText: serverText, logging: logging) { + self = c + return + } + guard let url = URL(string: serverText), let scheme = url.scheme else { + throw ParseServerTextError(description: "Unable to parse server '\(serverText)'.") + } + guard scheme == "imap" else { + throw ParseServerTextError(description: "Server is invalid or URL is not an IMAP URL '\(serverText)'.") + } + guard let hostname = url.host else { + throw ParseServerTextError(description: "Invalid hostname in IMAP URL '\(serverText)'.") + } + if let p = url.port { + guard let port = UInt16(exactly: p) else { + throw ParseServerTextError(description: "Invalid port '\(p)' in IMAP URL.") + } + self.init(hostname: hostname, port: port, logging: logging) + } else { + self.init(hostname: hostname, port: 993, logging: logging) + } + } + + /// Creates a configuration from a hostname with an optional `:port` suffix. + /// + /// Returns `nil` if the text is not a hostname (optionally followed by a port), in which + /// case ``init(serverText:logging:)`` falls back to parsing the text as an IMAP URL. + private init?(hostnameAndPortText text: String, logging: Logging) { + if let colon = text.firstIndex(of: ":") { + let hostname = text[.. Bool { + guard !text.isEmpty else { return false } + return text.split(separator: ".", omittingEmptySubsequences: false) + .allSatisfy { isValidHostnameLabel($0) } + } + + /// Whether the text is a valid hostname label, i.e. non-empty, made up of ASCII letters, + /// digits, and hyphens, and neither starting nor ending with a hyphen. + private static func isValidHostnameLabel(_ label: some StringProtocol) -> Bool { + guard + !label.isEmpty, + label.utf8.allSatisfy({ $0.isHostnameLabelByte }) + else { return false } + return (label.first != "-") && (label.last != "-") + } + + /// An error indicating the server text could not be parsed into a valid configuration. + public struct ParseServerTextError: Swift.Error, Sendable, CustomStringConvertible { + /// Which part of the server text could not be parsed. + public var description: String + + /// Creates an error with the given message. + public init(description: String) { + self.description = description + } + } +} + +// MARK: - + +extension UInt8 { + /// Whether this is an ASCII letter, digit, or hyphen. + fileprivate var isHostnameLabelByte: Bool { + switch self { + case UInt8(ascii: "0")...UInt8(ascii: "9"): true + case UInt8(ascii: "A")...UInt8(ascii: "Z"): true + case UInt8(ascii: "a")...UInt8(ascii: "z"): true + case UInt8(ascii: "-"): true + default: false + } + } +} diff --git a/Sources/IMAPCommands/ContinuationWriter.swift b/Sources/IMAPCommands/ContinuationWriter.swift new file mode 100644 index 00000000..3042ee2c --- /dev/null +++ b/Sources/IMAPCommands/ContinuationWriter.swift @@ -0,0 +1,41 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP + +extension IMAPConnection { + /// Sends continuation data to the server during authentication. + public struct ContinuationWriter: ~Copyable, Sendable { + var underlying: OutboundQueue + + /// Sends the given bytes as a continuation response. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. + public func writeContinuation( + _ bytes: ByteBuffer + ) async throws(IMAPConnection.Error) { + try await underlying.writeContinuationResponse(bytes) + } + + /// Sends the given byte sequence as a continuation response. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. + public func writeContinuation( + _ bytes: some Sequence + ) async throws(IMAPConnection.Error) { + try await writeContinuation(ByteBuffer(bytes: bytes)) + } + } +} diff --git a/Sources/IMAPCommands/Debug.swift b/Sources/IMAPCommands/Debug.swift new file mode 100644 index 00000000..61d2f779 --- /dev/null +++ b/Sources/IMAPCommands/Debug.swift @@ -0,0 +1,89 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import NIO +import NIOExtras + +/// Creates a channel handler that logs inbound channel events to `logger` at the `.trace` level. +/// +/// The event description includes the data that was read, so these lines carry message content +/// and anything else the server sends. See ``IMAPConnection/Configuration/Logging/logging``. +/// +/// - Parameter logger: The logger to write to. Channel handlers run on the event loop, outside +/// any task, so `Logger.current` is not meaningful there and the logger has to be passed in. +public func makeInboundDebugHandler( + logger: Logger +) -> some ChannelHandler { + DebugInboundEventsHandler( + logger: { event, _ in + logger.trace( + "Inbound channel event", + metadata: ["imap.event": "\(eventDescription(event))"] + ) + } + ) +} + +/// Creates a channel handler that logs outbound channel events to `logger` at the `.trace` level. +/// +/// The event description includes the data that was written, so these lines carry the commands +/// sent to the server — including credentials. +/// See ``IMAPConnection/Configuration/Logging/logging``. +/// +/// - Parameter logger: The logger to write to. Channel handlers run on the event loop, outside +/// any task, so `Logger.current` is not meaningful there and the logger has to be passed in. +public func makeOutboundDebugHandler( + logger: Logger +) -> some ChannelHandler { + DebugOutboundEventsHandler( + logger: { event, _ in + logger.trace( + "Outbound channel event", + metadata: ["imap.event": "\(eventDescription(event))"] + ) + } + ) +} + +private func eventDescription( + _ event: DebugInboundEventsHandler.Event +) -> String { + switch event { + case .registered: "registered" + case .unregistered: "unregistered" + case .active: "active" + case .inactive: "inactive" + case .read(data: let data): "read(\(String(reflecting: data)))" + case .readComplete: "readComplete" + case .writabilityChanged(isWritable: let isWritable): "writabilityChanged(\(isWritable ? "true" : "false"))" + case .userInboundEventTriggered: "userInboundEventTriggered" + case .errorCaught(let error): "errorCaught(\(error))" + } +} + +private func eventDescription( + _ event: DebugOutboundEventsHandler.Event +) -> String { + switch event { + case .register: "register" + case .bind: "bind" + case .connect: "connect" + case .write(data: let data): "write(\(String(reflecting: data)))" + case .flush: "flush" + case .read: "read" + case .close(mode: let mode): "close(\(mode))" + case .triggerUserOutboundEvent: "triggerUserOutboundEvent" + } +} diff --git a/Sources/IMAPCommands/EventLoopGroup.swift b/Sources/IMAPCommands/EventLoopGroup.swift new file mode 100644 index 00000000..a64ed9a1 --- /dev/null +++ b/Sources/IMAPCommands/EventLoopGroup.swift @@ -0,0 +1,32 @@ +//===----------------------------------------------------------------------===// +// +// 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 + +extension MultiThreadedEventLoopGroup { + /// A shared event loop group with a low thread count for IMAP connections. + public static var sharedEventLoopGroup: MultiThreadedEventLoopGroup { + _singleton + } +} + +private let _singleton: MultiThreadedEventLoopGroup = { + // A dedicated, never-shut-down group for IMAP connections. `_makePerpetualGroup` + // returns a group whose event loops run for the lifetime of the process, and this + // global holds the reference to it — so no extra manual `retain()` is needed. + MultiThreadedEventLoopGroup._makePerpetualGroup( + threadNamePrefix: "nio-imap-tool-", + numberOfThreads: 2 + ) +}() diff --git a/Sources/IMAPCommands/IMAPCommands.docc/GettingStarted.md b/Sources/IMAPCommands/IMAPCommands.docc/GettingStarted.md new file mode 100644 index 00000000..de178c24 --- /dev/null +++ b/Sources/IMAPCommands/IMAPCommands.docc/GettingStarted.md @@ -0,0 +1,159 @@ +# Getting Started with IMAPCommands + +Open a connection, log in, and issue commands as awaitable calls. + +## Overview + +IMAPCommands is centered on ``IMAPConnection``. You open a connection with ``IMAPConnection/withConnection(configuration:_:)``, then send commands and `await` their responses inside the closure. The connection closes automatically when the closure returns. + +### Configuring a connection + +Describe the server with an ``IMAPConnection/Configuration``: + +```swift +import IMAPCommands + +let configuration = IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 993, + useTLS: true, + logging: .noLogging +) +``` + +### Opening a connection and sending commands + +``IMAPConnection/withConnection(configuration:_:)`` hands you the server ``IMAPConnection/Greeting`` and a connection. Send a command with ``IMAPConnection/send(_:_:)``: the closure receives the command’s ``IMAPConnection/Tag`` and a stream of the `Response` values the server produces while the command runs, up to and including its final `TaggedResponse`. + +```swift +try await IMAPConnection.withConnection(configuration: configuration) { greeting, connection in + // Log in. Wait for the tagged completion response. + try await connection.send(.login(username: "mrc", password: "secret")) { tag, responses in + try await responses.waitForCompletion() + } + + // Select a mailbox and inspect the untagged responses it produces. + try await connection.send(.select(.inbox)) { tag, responses in + try await responses.forEach { response in + print(response) + } + } +} +``` + +Commands are pipelined by sending them concurrently from a task group. Each `send` awaits its own command’s final `TaggedResponse`. Note, though, that IMAP does not tag untagged responses: while commands are in flight, every untagged `Response` is delivered to *all* in-flight `send` handlers, and some untagged responses are unsolicited and belong to no command at all. This is inherent to the protocol — each handler should act only on the responses it cares about. + +### Closures, isolation, and concurrency + +None of these closures is `@Sendable` or `@escaping`, and each one is `nonisolated(nonsending)` — it runs in the isolation domain of the code that calls it. A closure can therefore capture and mutate a local variable, or touch state belonging to the actor it was written in — including `@MainActor` state — without any of it having to be `Sendable`: + +```swift +@MainActor +func refresh(model: MailboxModel) async throws { + try await IMAPConnection.withConnection(configuration: configuration) { _, connection in + try await connection.send(.select(.inbox)) { _, responses in + try await responses.forEach { response in + model.apply(response) // `model` is @MainActor, and not Sendable + } + } + } +} +``` + +Concurrency is never imposed on you: if you want commands to overlap, spawn a task group yourself — the `IMAPConnection` and its `ResponseStream`s are `Sendable`, so they can be shared between child tasks. + +The connection itself runs in a child task of `withConnection(configuration:_:)`. If it fails, your closure is *not* cancelled; the failure surfaces the next time the closure touches the connection, as an error from the response stream or from the next command. + +### Logging + +Diagnostics go to swift-log’s task-local logger. Bind one with `withLogger(_:)` around the connection, and the connection picks it up — there is no logger to configure on the ``IMAPConnection/Configuration``: + +```swift +import Logging + +var logger = Logger(label: "com.example.mail") +logger.logLevel = .trace // Connection diagnostics are `.debug` and `.trace`. + +try await withLogger(logger) { _ in + try await IMAPConnection.withConnection(configuration: configuration) { greeting, connection in + // Connection lifecycle events are logged to `logger`. + } +} +``` + +Command handlers run with the command’s tag merged into the task-local logger, so anything *you* log from a handler is attributed to the command it belongs to without your having to thread the tag through: + +```swift +try await connection.send(.select(.inbox)) { _, responses in + // Logs with metadata `imap.tag: A2, imap.connection: 1`. + Logger.current.info("Selecting mailbox") + return try await responses.waitForCompletion() +} +``` + +Two metadata keys are bound: `imap.tag` identifies the command, and `imap.connection` identifies the connection it runs on — tags restart at `A1` on each connection, so the tag alone is ambiguous once you have more than one open. `imap.connection` is an opaque counter. Nothing derived from the endpoint is logged: a hostname can identify a person, and swift-log has no redaction a library can rely on, since `Logger.MetadataValueAttributes` only takes effect in handlers that opt into inspecting it. Log the endpoint yourself if you want it, where you can judge whether that is appropriate. + +Setting ``IMAPConnection/Configuration/logging`` to `logging` adds low-level tracing of every channel event, through the same logger at the `.trace` level: + +```swift +let configuration = IMAPConnection.Configuration( + hostname: "imap.example.com", + port: 993, + useTLS: true, + logging: .logging // Traces every channel event at `.trace`. +) +``` + +> Warning: Those traces include the data read and written, so they carry message content and the commands sent to the server — including credentials. Use them for local debugging, not where the log stream is collected or shipped off the device. + +### What a command can throw + +A `NO` or `BAD` from the server is *not* a Swift error — it is the command’s `TaggedResponse`, and `waitForCompletion()` returns it. Call `checkOK()` or `getOK()` to turn it into one: + +```swift +try await connection.send(.select(.inbox)) { _, responses in + // Connection dropped → `IMAPConnection.Error`. + let tagged = try await responses.waitForCompletion() + // Server said NO or BAD → `TaggedResponse.StateNotOK`. + return try tagged.getOK() +} +``` + +Both of those are *typed* throws, so the error type is in the signature rather than in prose. The closure-taking APIs — ``IMAPConnection/send(_:_:)`` and its siblings — stay untyped, because they rethrow whatever your handler throws, unchanged and unwrapped. What they add on their own behalf is always an ``IMAPConnection/Error``: + +```swift +do { + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } +} catch IMAPConnection.Error.connectionClosed { + // Gone before the command completed. +} catch let error as IMAPConnection.Error { + // .connectionFailed(_), .missingTaggedResponse, … + print(error) +} +``` + +### Commands with a different shape + +Some commands don’t fit the simple request/response shape and have dedicated APIs: + +- ``IMAPConnection/sendIdle(_:)`` runs `IDLE`, ending it when the closure returns. +- ``IMAPConnection/sendAuthenticate(mechanism:initialResponse:_:)`` runs `AUTHENTICATE`, giving the closure a ``IMAPConnection/ContinuationWriter`` to answer the server’s challenges. +- ``IMAPConnection/append(to:writing:reading:)`` streams an `APPEND`: one closure writes the message data with an ``IMAPConnection/AppendWriter`` while the other concurrently reads the command’s responses. ``IMAPConnection/append(to:_:)`` passes the writer and the responses to a single closure instead, leaving the interleaving — and whether there is any — to you. + +### Choosing between the two interfaces + +This package offers two interface styles on purpose, and neither is preferred over the other: + +- **IMAPCommands** (this module) is command-centric. You open a connection and `await` each command as an ordinary asynchronous call. Reach for it when you’d rather treat each command as an awaitable unit of work. +- **`NIOIMAP`** is event-driven. It provides SwiftNIO `ChannelHandler`s — `IMAPClientHandler` and `IMAPServerHandler` — that you insert into a `ChannelPipeline`, writing commands and consuming decoded responses as a raw stream of protocol events. Reach for it when your code already lives in a NIO pipeline, or when you want direct control over the event stream and encoding options. + +Both talk to the same server and share the same `NIOIMAPCore` command and response types, so a client built on one can be ported to the other without changing how commands and responses are constructed. If neither obviously fits, prototype the part you care about most in each — they’re deliberately close in capability, and the better fit usually becomes clear quickly. + +## Topics + +### Connections + +- ``IMAPConnection`` +- ``IMAPConnection/Configuration`` diff --git a/Sources/IMAPCommands/IMAPCommands.docc/IMAPCommands.md b/Sources/IMAPCommands/IMAPCommands.docc/IMAPCommands.md new file mode 100644 index 00000000..3d86fb04 --- /dev/null +++ b/Sources/IMAPCommands/IMAPCommands.docc/IMAPCommands.md @@ -0,0 +1,71 @@ +# ``IMAPCommands`` + +Drive an IMAP4rev1 conversation with a command-centric `async`/`await` client. + +## Overview + +IMAPCommands is a high-level IMAP client built on top of the `NIOIMAP` module. It is centered on ``IMAPConnection``: you open a connection, send commands, and `await` their responses as ordinary asynchronous calls. + +This is an **imperative, command-centric** interface. Each command is an awaitable unit of work — `try await connection.send(.login(...)) { ... }` — and the closure you pass receives the `Response` values the server produces while that command runs, up to and including its final `TaggedResponse`. Commands are pipelined by sending them concurrently from a task group. This style fits code that wants to express an IMAP session as a straightforward sequence, or concurrent set, of “send command → handle its responses” steps. + +Alongside ``IMAPConnection/send(_:_:)``, the module provides dedicated APIs for the commands that don’t fit the simple request/response shape: ``IMAPConnection/sendIdle(_:)`` for `IDLE`, ``IMAPConnection/sendAuthenticate(mechanism:initialResponse:_:)`` for `AUTHENTICATE` challenge/response, and ``IMAPConnection/append(to:writing:reading:)`` for streaming an `APPEND`. + +- Note: This is one of **two** interface styles this package offers, and neither is preferred over the other. If you’d rather work directly with the SwiftNIO pipeline and the raw stream of protocol events, see the `NIOIMAP` module, which provides the event-driven `ChannelHandler`s this client is built on. Both interfaces talk to the same server and share the same `NIOIMAPCore` command and response types; choose based on how your own code wants to be structured. See for a side-by-side comparison. + +### How a command can fail + +Three different things are easy to conflate, and only the first is an error the connection raises: + +| What went wrong | How you see it | +| --- | --- | +| The connection — could not open, broke, or closed mid-command | ``IMAPConnection/Error``, thrown from `send`, `append`, and the response stream | +| The server refused the command with `NO` or `BAD` | Not an error. It arrives as the command's `TaggedResponse`; `checkOK()` or `getOK()` turns it into ``TaggedResponse/StateNotOK`` | +| Your own handler closure threw | Rethrown unchanged. `send` and friends never wrap a handler's error | + +Declarations whose failures are limited to one of these use typed throws, so the error type is part of the signature: ``IMAPConnection/ResponseStream/waitForCompletion()`` throws ``IMAPConnection/Error``, and `checkOK()` / `getOK()` throw ``TaggedResponse/StateNotOK``. The closure-taking APIs stay untyped, because the error a handler throws is by definition open. + +### Layering + +The package is layered so you can work at whichever level suits your needs: + +| Module | What it gives you | +| --- | --- | +| `NIOIMAPCore` | The IMAP grammar as Swift types, plus the parser and encoder. No networking. | +| `NIOIMAP` | SwiftNIO `ChannelHandler`s that plug the parser and encoder into a `ChannelPipeline`. Re-exports `NIOIMAPCore`. | +| **`IMAPCommands`** | A high-level `async`/`await` client centered on ``IMAPConnection``, built on top of NIOIMAP. | + +## Topics + +### Essentials + +- +- ``IMAPConnection`` + +### Configuration + +- ``IMAPConnection/Configuration`` +- ``IMAPCredential`` + +### Streaming an APPEND + +- ``IMAPConnection/AppendWriter`` + +### Authentication Challenges + +- ``IMAPConnection/ContinuationWriter`` + +### Command Results + +- ``CompletedCommand`` +- ``SuccessfulCommand`` + +### Errors + +- ``IMAPConnection/Error`` +- ``IMAPConnection/IncompleteAppend`` +- ``IMAPConnection/AppendAlreadyFinished`` + +### Debugging + +- ``makeInboundDebugHandler(logger:)`` +- ``makeOutboundDebugHandler(logger:)`` diff --git a/Sources/IMAPCommands/IMAPConnection.swift b/Sources/IMAPCommands/IMAPConnection.swift new file mode 100644 index 00000000..37775313 --- /dev/null +++ b/Sources/IMAPCommands/IMAPConnection.swift @@ -0,0 +1,1023 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import NIO +import NIOIMAP +import NIOSSL +import Synchronization + +/// An async connection to an IMAP server. +/// +/// Commands can be sent concurrently using IMAP pipelining. +/// +/// ```swift +/// try await IMAPConnection.withConnection(configuration: myConfig) { greeting, connection in +/// // Use connection here. +/// } +/// ``` +/// +/// Diagnostics go to the task-local `Logger.current`, so wrap the connection in `withLogger(_:)` +/// to direct them: +/// +/// ```swift +/// try await withLogger(myLogger) { _ in +/// try await IMAPConnection.withConnection(configuration: myConfig) { greeting, connection in +/// // Use connection here. +/// } +/// } +/// ``` +/// +/// - Important: IMAP does not tag untagged responses, so while commands are pipelined every +/// untagged `Response` is delivered to _all_ in-flight command handlers (see +/// ``send(_:_:)``). Handlers must act only on the responses they care about. +public final class IMAPConnection: Sendable { + private init( + configuration: Configuration + ) { + self.configuration = configuration + let id = Self.nextConnectionID.wrappingAdd(1, ordering: .relaxed).oldValue + self.connectionID = id + // Captured once, rather than read at each log site: `close(reason:)` and the response + // streams can be driven from any of the connection's tasks — or from the caller's — and + // the connection's own diagnostics should not vary with whichever `withLogger` scope + // happens to be active there. + var logger = Logger.current + // An opaque counter, so that lines from concurrent connections can be told apart. The + // endpoint deliberately does not go in here: a hostname can identify a person, and + // swift-log has no redaction a library can rely on — `Logger.MetadataValueAttributes` + // is only honoured by handlers that opt into inspecting it. + logger[metadataKey: "imap.connection"] = "\(id)" + self.logger = logger + self.outboundWriter = OutboundQueue() + } + + /// Hands out the `imap.connection` identifier that distinguishes each connection's log lines. + private static let nextConnectionID = Atomic(1) + + let configuration: Configuration + /// Identifies this connection in log metadata. Not derived from anything user-identifying. + let connectionID: UInt64 + /// The logger the connection was created in the scope of, tagged with ``connectionID``. + let logger: Logger + private let outboundWriter: OutboundQueue + private let state = Mutex(State()) + + /// Logger metadata identifying a command running on this connection. + /// + /// Both keys are needed: tags restart at `A1` on every connection, so the tag alone does not + /// identify a command in an app that has more than one connection open. + func loggerMetadata(for tag: Tag) -> Logger.Metadata { + var metadata = tag.loggerMetadata + metadata["imap.connection"] = "\(connectionID)" + return metadata + } + + struct State: Sendable { + var perCommandResponseStreams = PerCommandResponseStream() + var greeting: GreetingState = .waiting([]) + } + + /// Creates an IMAP connection and runs the given closure. + /// + /// The closure can send commands to the connection and receive responses from the server. + /// Use task groups to pipeline commands concurrently. + /// + /// The connection itself runs in a child task while `body` runs in the calling task. As a + /// result `body` needs to be neither `@Sendable` nor `@escaping`: it can capture and mutate + /// non-`Sendable` state, and it runs in the caller’s isolation domain. + /// + /// The connection closes when the `body` closure returns or throws. + /// + /// Connection diagnostics are logged to the task-local `Logger.current`, which the connection + /// captures for its lifetime. Bind one with `withLogger(_:)` around this call to observe them; + /// lifecycle and per-command diagnostics are emitted at the `.debug` and `.trace` levels, so + /// they are suppressed unless the logger's log level admits them. + /// + /// - Note: A failing connection does _not_ cancel `body`. Instead, the failure surfaces the + /// next time `body` interacts with the connection: pending and subsequent + /// ``ResponseStream``s and ``send(_:_:)`` calls fail with the underlying error. + /// A `body` that neither returns nor touches the connection again keeps + /// `withConnection(configuration:_:)` from returning. + /// - Throws: ``IMAPConnection/Error`` if the connection cannot be opened, or fails or closes + /// before the greeting arrives. Rethrows whatever `body` throws, unchanged. + /// - Parameters: + /// - configuration: Which server to connect to, and how. + /// - body: Receives the server's greeting and the open connection. The connection closes + /// when this returns or throws. + /// - Returns: The value `body` returns. + public static func withConnection( + configuration: Configuration, + _ body: nonisolated(nonsending) (Greeting, IMAPConnection) async throws -> Result + ) async throws -> Result { + let connection = IMAPConnection(configuration: configuration) + + return try await withThrowingTaskGroup( + of: Void.self, + returning: Result.self + ) { group in + // Create a child task that “runs” the connection receiving inbound and sending + // commands. Its error is never rethrown from here — the group discards the errors + // of tasks that are still running when this closure returns, and `run(logging:)` + // reports its failure through `close(reason:)` instead, so that whatever `body` + // does with the connection next fails with that error. + group.addTask { + try await connection.run(logging: configuration.logging) + } + + // Run the `body` — the caller’s code that sends commands — in _this_ task: + do { + // Wait for the greeting: + let greeting = try await connection.greeting + let result = try await body(greeting, connection) + connection.logger.debug("Closing connection after body completed") + connection.close(reason: .closed) + group.cancelAll() + return result + } catch { + connection.logger.debug( + "Closing connection after body threw", + metadata: ["error": "\(error)"] + ) + connection.close(reason: .failed(error)) + group.cancelAll() + throw error + } + } + } + + /// Sets the encoding options for commands sent to the server. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. + public func setEncodingOptions( + _ new: IMAPClientHandler.EncodingOptions + ) async throws(Error) { + try await outboundWriter.setEncodingOptions(new) + } + + /// Sends the given command to the server. + /// + /// The closure receives the `Response` values the server produces while the command + /// runs, up to and including the `TaggedResponse` for this command. + /// + /// - Important: IMAP does not associate untagged responses with a particular command. + /// Every untagged `Response` the server emits while _any_ command is in flight is + /// delivered to _all_ in-flight command handlers — and some untagged responses are + /// unsolicited and belong to no command at all. Only the final `TaggedResponse` + /// (which `waitForCompletion()` waits for) is specific to this command. This is + /// inherent to the protocol and how pipelining works; when you send commands + /// concurrently, each handler must inspect only the responses it actually cares about. + /// - Note: The handler runs with the command's tag bound to the task-local logger, so + /// anything it logs through `Logger.current` carries `imap.tag` and `imap.connection` + /// metadata keys. + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes. Rethrows whatever `handler` throws, unchanged — a handler error is + /// never wrapped. A `NO` or `BAD` from the server is not an error at all: it reaches + /// `handler` as the command's `TaggedResponse`. + /// - Parameters: + /// - command: The command to send. + /// - handler: Receives the command's ``Tag`` and the responses the server sends while it + /// runs. + /// - Returns: The value `handler` returns. + public func send( + _ command: Command, + _ handler: nonisolated(nonsending) (Tag, ResponseStream) async throws -> Result + ) async throws -> Result { + let (tag, responseStream) = try state.withLock { state in + state.perCommandResponseStreams.makeTagAndResponseStream() + }.get() + + try await outboundWriter.write( + TaggedCommand( + tag: "\(tag)", + command: command + ) + ) + + return try await withLogger(mergingMetadata: loggerMetadata(for: tag)) { _ in + try await handler(tag, ResponseStream(underlying: responseStream)) + } + } + + /// Sends an `IDLE` command to the server. + /// + /// The handler receives the `Response` values the server produces while idling. Returning + /// from the handler ends the `IDLE`: `sendIdle(_:)` then sends `DONE`. + /// + /// - Important: The command’s `TaggedResponse` only arrives _after_ `DONE`, so the handler + /// must not wait for the command to complete — use the stream to observe untagged + /// responses and return once you want to stop idling. + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed. Rethrows + /// whatever `handler` throws, unchanged; `DONE` is still sent first, on a best-effort basis. + /// - Parameter handler: Receives the command's ``Tag`` and the responses that arrive while + /// idling. Returning ends the `IDLE`. + /// - Returns: The value `handler` returns. + public func sendIdle( + _ handler: nonisolated(nonsending) (Tag, ResponseStream) async throws -> Result + ) async throws -> Result { + let (tag, responseStream) = try state.withLock { state in + state.perCommandResponseStreams.makeTagAndResponseStream() + }.get() + + try await outboundWriter.write( + TaggedCommand( + tag: "\(tag)", + command: .idleStart + ) + ) + + let result: Result + do { + result = try await withLogger(mergingMetadata: loggerMetadata(for: tag)) { _ in + try await handler(tag, ResponseStream(underlying: responseStream)) + } + } catch { + // Best-effort: leave IDLE even when the handler fails, so a caller + // that catches the error and keeps using the connection doesn't + // leave the server stuck in IDLE. (If the connection is already + // torn down, this write simply fails and we still rethrow.) + try? await outboundWriter.writeIdleDone() + throw error + } + try await outboundWriter.writeIdleDone() + return result + } + + /// Sends an `AUTHENTICATE` command to the server. + /// + /// Use the ``ContinuationWriter`` to respond to authentication challenges. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes. Rethrows whatever `handler` throws, unchanged — an authentication + /// exchange cannot be aborted cleanly, so the connection is closed in that case. + /// - Parameters: + /// - mechanism: The SASL mechanism to authenticate with. + /// - initialResponse: The SASL-IR initial response, if the server supports one. + /// - handler: Receives the command's ``Tag``, its responses, and a writer for answering + /// the server's challenges. + /// - Returns: The value `handler` returns. + public func sendAuthenticate( + mechanism: AuthenticationMechanism, + initialResponse: InitialResponse?, + _ handler: nonisolated(nonsending) (Tag, ResponseStream, borrowing ContinuationWriter) async throws -> Result + ) async throws -> Result { + let (tag, responseStream) = try state.withLock { state in + state.perCommandResponseStreams.makeTagAndResponseStream() + }.get() + + try await outboundWriter.write( + TaggedCommand( + tag: "\(tag)", + command: .authenticate( + mechanism: mechanism, + initialResponse: initialResponse + ) + ) + ) + + do { + return try await withLogger(mergingMetadata: loggerMetadata(for: tag)) { _ in + try await handler( + tag, + ResponseStream(underlying: responseStream), + ContinuationWriter(underlying: outboundWriter) + ) + } + } catch { + // There is no clean way to abort an in-progress AUTHENTICATE exchange (the + // `*` cancellation cannot be expressed through a base64 continuation + // response), so if the handler fails mid-challenge we close the connection + // rather than leave it in a half-authenticated state that can't be reused. + close(reason: .failed(error)) + throw error + } + } + + /// Sends an `APPEND` command as a stream to the server. + /// + /// The closure writes the message data with the provided ``AppendWriter`` and consumes the + /// command's responses from the ``ResponseStream``. `APPEND` needs at least one message, and + /// the command is complete when the closure returns — or as soon as the closure calls + /// ``AppendWriter/finish()``. + /// + /// The server sends the command's `TaggedResponse` only once the command is complete, so a + /// closure that waits for it finishes the command first: + /// + /// ```swift + /// let tagged = try await connection.append(to: mailbox) { tag, responses, writer in + /// try await writer.write(message: message) { messageWriter in + /// try await messageWriter.write(messageBytes: bytes) + /// } + /// try await writer.finish() + /// return try await responses.waitForCompletion() + /// } + /// ``` + /// + /// To act on responses while the message data is still going out, read them from a task group + /// of your own. The ``ResponseStream`` is `Sendable` and the ``AppendWriter`` is not, so the + /// writer stays in the parent task: + /// + /// ```swift + /// try await connection.append(to: mailbox) { tag, responses, writer in + /// try await withThrowingTaskGroup(of: Void.self) { group in + /// group.addTask { + /// for try await response in responses { + /// print(response) + /// } + /// } + /// try await writer.write(message: message) { messageWriter in + /// try await messageWriter.write(messageBytes: bytes) + /// } + /// try await writer.finish() + /// } + /// } + /// ``` + /// + /// ``append(to:writing:reading:)`` is that second form written for you: it takes a + /// write closure and a `@Sendable` read closure, and runs them concurrently. + /// + /// - Warning: The `TaggedResponse` cannot arrive while the command is still open. Waiting for + /// it inside the closure without first calling ``AppendWriter/finish()`` — and without + /// another task writing concurrently — therefore never returns. + /// - Note: `APPEND` cannot be pipelined: the protocol only allows the message literals to + /// follow the command, so any other command sent on this connection while `append` runs + /// is queued and written once the append completes. As with ``send(_:_:)``, the + /// stream also delivers untagged responses that belong to other commands, or to no command + /// at all; only the `TaggedResponse` is this command's. + /// - Important: A synchronizing literal cannot be cancelled once begun. If the closure leaves + /// the command incomplete — because it throws part-way through, writes no message, or + /// begins a message it never finishes — the command cannot be completed, so this method + /// closes the connection. It rethrows the closure's error, or throws ``IncompleteAppend`` + /// if the closure itself succeeded. An error the closure throws _after_ completing the + /// command leaves the connection intact, exactly like an error from a + /// ``send(_:_:)`` handler. + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes, or ``IncompleteAppend`` if `body` returns having left the command + /// unfinished. Rethrows whatever `body` throws, unchanged. + /// - Parameters: + /// - mailbox: The mailbox to append the message to. + /// - body: Writes the message(s) with the provided ``AppendWriter`` and handles the + /// command's responses. It also receives the ``Tag`` that identifies this command in the + /// `TaggedResponse` completing it. + /// - Returns: The value `body` returns. + public func append( + to mailbox: MailboxName, + _ body: nonisolated(nonsending) (Tag, ResponseStream, inout AppendWriter) async throws -> Result + ) async throws -> Result { + let (tag, responseStream) = try state.withLock { state in + state.perCommandResponseStreams.makeTagAndResponseStream() + }.get() + + // Whether the `APPEND` command was written in full. If it wasn't, the server is still + // waiting for the rest of it, and no other command can be sent on this connection. + var didCompleteCommand = false + do { + return try await withLogger(mergingMetadata: loggerMetadata(for: tag)) { _ in + // The `consuming` ownership of the closure parameter is spelled out + // explicitly: it is otherwise inferred as `borrowing` here, which cannot be + // handed on to `AppendWriter.withAppendWriter`. + try await outboundWriter.withAppendWriter { + (writer: consuming OutboundQueue.AppendQueueWriter) in + try await AppendWriter.withAppendWriter( + tag: "\(tag)", + appendingTo: mailbox, + underlying: writer, + didCompleteCommand: &didCompleteCommand + ) { innerWriter in + try await body(tag, ResponseStream(underlying: responseStream), &innerWriter) + } + } + } + } catch { + guard + !didCompleteCommand + else { throw error } + // The command was started but never finished. There is no way to abort it — sending + // anything but the remaining append data would be a protocol violation — so the + // connection is unusable. + logger.debug( + "Closing connection after APPEND was left incomplete", + metadata: ["error": "\(error)"] + ) + close(reason: .failed(error)) + throw error + } + } + + /// Sends an `APPEND` command as a stream to the server, reading its responses as it writes. + /// + /// This is ``append(to:_:)`` with the task group written for you: `write` writes the + /// message data while `read` concurrently consumes the responses the server sends — including + /// any that arrive while the message data is still in flight. `read` receives the command's + /// ``Tag`` and ``ResponseStream`` and returns the result, the same shape + /// ``send(_:_:)``'s handler has. + /// + /// ```swift + /// let tagged = try await connection.append( + /// to: mailbox, + /// writing: { tag, writer in + /// try await writer.write(message: message) { messageWriter in + /// for try await bytes in file { + /// try await messageWriter.write(messageBytes: bytes) + /// } + /// } + /// }, + /// reading: { tag, responses in + /// try await responses.waitForCompletion() + /// } + /// ) + /// ``` + /// + /// `write` has to write at least one message, and the command completes once it returns — so + /// `read` can wait for the command's `TaggedResponse`, which arrives after the message data + /// has gone out in full. + /// + /// - Note: `read` runs in a child task, which is why — alone among the closures in this API — + /// it has to be `@Sendable`, and `Result` has to be `Sendable`. `write` holds the + /// ``AppendWriter``, which cannot leave the task that owns it, so `write` runs in the + /// calling task and needs neither. Use ``append(to:_:)`` to keep everything in + /// one task. + /// - Note: As with ``send(_:_:)``, `read` also sees untagged responses that belong + /// to other commands, or to no command at all; only the `TaggedResponse` is this command's. + /// - Important: If `read` throws, `write` still writes the message in full before this method + /// rethrows the error: abandoning a synchronizing literal part-way would leave the + /// connection unusable. If `write` throws, or leaves the command incomplete, this method + /// cancels `read` and closes the connection, as ``append(to:_:)`` describes. + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes, or ``IncompleteAppend`` if `write` returns having left the command + /// unfinished. Rethrows whatever `write` or `read` throws, unchanged. + /// - Parameters: + /// - mailbox: The mailbox to append the message to. + /// - write: Writes the message(s) using the provided ``AppendWriter``. + /// - read: Receives the responses the server sends for the command, concurrently with + /// `write`. + /// - Returns: The value `read` returns. + public func append( + to mailbox: MailboxName, + writing write: nonisolated(nonsending) (Tag, inout AppendWriter) async throws -> Void, + reading read: @Sendable @escaping (Tag, ResponseStream) async throws -> Result + ) async throws -> Result { + try await append(to: mailbox) { tag, responses, writer in + try await withThrowingTaskGroup(of: Result.self, returning: Result.self) { group in + group.addTask { + try await read(tag, responses) + } + // The writer cannot be sent to another task — it is non-copyable and `inout` — + // so writing happens here, in this task, while `read` runs in the child. + try await write(tag, &writer) + // The `TaggedResponse` can only arrive once the command is complete, so `read` + // would never finish if the command were left open until this closure returns. + try await writer.finish() + guard + let result = try await group.next() + else { throw AppendCompletedWithoutReadResult() } + return result + } + } + } + + /// An error indicating the `APPEND` read closure finished without producing a result. + private struct AppendCompletedWithoutReadResult: Swift.Error {} +} + +// MARK: - + +extension IMAPConnection { + private func makeChannel( + logging: Configuration.Logging + ) async throws -> NIOAsyncChannel { + let configuration = self.configuration + return try await ClientBootstrap(group: MultiThreadedEventLoopGroup.sharedEventLoopGroup) + .connect(endpoint: configuration.endpoint) + .flatMap { [configuration, logger] channel in + channel.eventLoop.makeCompletedFuture { + var handlers: [ChannelHandler] = [] + if configuration.useTLS { + handlers.append( + try NIOSSLClientHandler( + context: NIOSSLContext(configuration: .clientDefault), + serverHostname: configuration.endpoint.hostname + ) + ) + } + switch logging { + case .noLogging: + break + case .logging: + handlers.append(makeInboundDebugHandler(logger: logger)) + handlers.append(makeOutboundDebugHandler(logger: logger)) + } + handlers.append(IMAPClientHandler()) + try channel.pipeline.syncOperations.addHandlers(handlers) + return try NIOAsyncChannel( + wrappingChannelSynchronously: channel + ) + } + } + .get() + } + + private func run( + logging: Configuration.Logging + ) async throws { + do { + try await makeChannel( + logging: logging + ).executeThenClose { inbound, outbound in + let outboundWriter = self.outboundWriter + try await withThrowingTaskGroup(of: Void.self) { group in + group.addTask { + await self.runInbound(inbound) + } + group.addTask { + do { + try await outboundWriter.run(outbound: outbound) + } catch { + // Tear the connection down: the channel is gone, so anything the + // caller does next must fail with this error rather than park. + self.close(reason: .failed(error)) + throw error + } + } + + try await group.waitForAll() + } + } + close(reason: .closed) + } catch { + // Ensure any awaiting caller is unblocked no matter how this exits — in + // particular a task parked on `greeting` when the channel fails to open — and + // that it sees _why_ the connection went away. + close(reason: .failed(error)) + throw error + } + } + + /// Reads the greeting and then every subsequent response, until the stream ends. + /// + /// When the inbound stream ends — via a graceful EOF, a read error, or cancellation — this + /// tears the connection down. That finishes any in-flight command response streams (and any + /// greeting waiter) and closes the outbound queue so the outbound runner stops, instead of + /// leaving callers parked forever. + private func runInbound( + _ inbound: NIOAsyncChannelInboundStream + ) async { + do { + var iterator = inbound.makeAsyncIterator() + // Get the greeting: + guard + let first = try await iterator.next() + else { + // EOF before the greeting. + close(reason: .closed) + return + } + guard + case .untagged(.conditionalState(let s)) = first + else { + throw Error.unexpectedGreeting(first) + } + didReceive(greeting: Greeting(status: s)) + // Loop through the remaining: + while let response = try await iterator.next() { + switch response { + case .tagged(let tagged): + try commandDidComplete(response: tagged) + default: + didReceive(response: response) + } + } + close(reason: .closed) + } catch { + logger.debug( + "Closing connection after inbound error", + metadata: ["error": "\(error)"] + ) + // The error is not rethrown: `close(reason:)` hands it to the caller instead, as + // the error of every response stream that was still running, and of every + // subsequent interaction with this connection. + close(reason: .failed(error)) + } + } + + /// Why the connection was closed. + /// + /// The reason determines what anything still using — or subsequently using — this + /// connection fails with. + enum CloseReason { + /// The connection was closed in an orderly fashion: the caller is done with it, or the + /// server sent EOF. + case closed + /// The connection failed with this error. + case failed(any Swift.Error) + + var error: IMAPConnection.Error? { + switch self { + case .closed: nil + case .failed(let error): IMAPConnection.Error(wrapping: error) + } + } + } + + /// Mark the state as closed: + /// + /// Only the first call has an effect; a connection that already failed keeps the error it + /// failed with. + private func close(reason: CloseReason) { + state.withLock { state in + state.markAsClosed(reason: reason) + }.run(logger: logger) + outboundWriter.close() + } + + private func commandDidComplete(response: TaggedResponse) throws { + logger.trace("Command did complete", metadata: ["imap.tag": "\(response.tag)"]) + try state.withLock { state in + state.perCommandResponseStreams.popCompletedCommand(response: response) + }.run() + } + + private func didReceive(response: Response) { + let all = state.withLock { state in + state.perCommandResponseStreams.allContinuations + } + for c in all { + c.yield(response) + } + } +} + +extension ClientBootstrap { + /// Connects to the given configuration endpoint. + public func connect(endpoint: IMAPConnection.Configuration.Endpoint) -> EventLoopFuture { + switch endpoint { + case .hostname(let host, port: let port): + connect(host: host, port: Int(port)) + case .unixDomainSocket(path: let path): + connect(unixDomainSocketPath: path) + } + } +} + +extension IMAPConnection { + /// A stream of responses from the server received while a specific command runs. + public struct ResponseStream: AsyncSequence, Sendable { + public struct AsyncIterator: AsyncIteratorProtocol { + public typealias Element = Response + public typealias Failure = IMAPConnection.Error + + var underlying: AsyncThrowingStream.AsyncIterator + + public mutating func next() async throws(IMAPConnection.Error) -> Response? { + try await next(isolation: #isolation) + } + + /// Both `next` overloads are implemented, and the isolation is forwarded to the + /// underlying iterator, because the iterator is not `Sendable`: were this to fall + /// back to `AsyncIteratorProtocol`’s default implementation of + /// `next(isolation:)` — which calls the `@concurrent` `next()` — the iterator + /// would be sent out of the caller’s isolation domain on every element. + /// `Error(wrapping:)` is a pass-through: `AsyncThrowingStream` only builds with an + /// untyped failure, so the narrowing happens here. + public mutating func next( + isolation actor: isolated (any Actor)? + ) async throws(IMAPConnection.Error) -> Response? { + do { + return try await underlying.next(isolation: actor) + } catch { + throw IMAPConnection.Error(wrapping: error) + } + } + } + + public typealias Element = Response + public typealias Failure = IMAPConnection.Error + + let underlying: AsyncThrowingStream + + public func makeAsyncIterator() -> AsyncIterator { + AsyncIterator(underlying: underlying.makeAsyncIterator()) + } + } +} + +// The iterator wraps `AsyncThrowingStream.AsyncIterator`, which is not `Sendable`. +@available(*, unavailable) +extension IMAPConnection.ResponseStream.AsyncIterator: Sendable {} + +extension IMAPConnection.ResponseStream { + /// Iterates over all responses and returns the command’s `TaggedResponse` on completion. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes. Rethrows whatever `closure` throws, unchanged. + public func forEach( + _ closure: nonisolated(nonsending) (AsyncIterator.Element) async throws -> Void + ) async throws -> TaggedResponse { + var t: TaggedResponse? + for try await r in self { + if case .tagged(let tagged) = r { + t = tagged + } + try await closure(r) + } + guard + let t + else { throw IMAPConnection.Error.missingTaggedResponse } + return t + } + + /// Waits for the command to complete, discarding intermediate responses; returns its + /// `TaggedResponse`. + /// + /// - Throws: ``IMAPConnection/Error`` if the connection fails or is closed before the + /// command completes. A `NO` or `BAD` from the server is *not* an error — it is returned + /// as the `TaggedResponse`. Use `checkOK()` or `getOK()` on the result to turn it into one. + public func waitForCompletion() async throws(IMAPConnection.Error) -> TaggedResponse { + // Not `forEach { _ in }`: that takes a caller closure, so it can't be typed. + var t: TaggedResponse? + for try await r in self { + if case .tagged(let tagged) = r { + t = tagged + } + } + guard + let t + else { throw .missingTaggedResponse } + return t + } +} + +// MARK: - Mark as Closed + +extension IMAPConnection.State { + mutating func markAsClosed(reason: IMAPConnection.CloseReason) -> CloseAction { + return CloseAction( + perCommandResponseStreams: perCommandResponseStreams.markAsClosed(reason: reason), + greeting: greeting.markAsClosed(reason: reason) + ) + } + + struct CloseAction { + var perCommandResponseStreams: IMAPConnection.PerCommandResponseStream.CloseAction + var greeting: GreetingState.StoreAction + + func run(logger: Logger) { + perCommandResponseStreams.run(logger: logger) + greeting.run() + } + } +} + +// MARK: - Per Command Response Stream + +extension IMAPConnection { + enum PerCommandResponseStream { + case streams(Tag, [Tag: AsyncThrowingStream.Continuation]) + /// The connection is gone. Anything that interacts with it fails with this error. + case connectionClosed(IMAPConnection.Error) + + init() { + self = .streams(Tag.first, [:]) + } + } +} + +extension IMAPConnection.PerCommandResponseStream { + mutating func makeTagAndResponseStream() -> Result< + (IMAPConnection.Tag, AsyncThrowingStream), IMAPConnection.Error + > { + switch self { + case .streams(var nextTag, var continuations): + let tag = nextTag + nextTag = tag.makeNext() + + // `AsyncThrowingStream` only builds with an untyped failure; `ResponseStream` + // narrows it back. + let (stream, continuation) = AsyncThrowingStream.makeStream(of: Response.self) + + // Copy-on-write exclusivity dance: assigning the payload-free + // `.connectionClosed` case first drops `self`'s reference to + // `continuations`, so the dictionary is uniquely referenced when we insert + // into it below and no copy-on-write copy is made. We immediately restore + // the real `.streams` state. + self = .connectionClosed(.connectionClosed) + continuations[tag] = continuation + self = .streams(nextTag, continuations) + return .success((tag, stream)) + + case .connectionClosed(let error): + return .failure(error) + } + } + + var allContinuations: [IMAPConnection.Tag: AsyncThrowingStream.Continuation].Values { + switch self { + case .streams(_, let c): c.values + case .connectionClosed: [:].values + } + } + + mutating func popCompletedCommand( + response: TaggedResponse + ) -> PopAction { + switch self { + case .streams(let nextTag, var continuations): + guard + let tag = IMAPConnection.Tag(response.tag), + let continuation = continuations.removeValue(forKey: tag) + else { return .unknownTag(response.tag) } + self = .streams(nextTag, continuations) + return .finishContinuation(continuation, response) + case .connectionClosed: + return .none + } + } + + enum PopAction { + case none + case unknownTag(String) + case finishContinuation(AsyncThrowingStream.Continuation, TaggedResponse) + + func run() throws(IMAPConnection.Error) { + switch self { + case .none: + break + case .unknownTag(let tag): + throw .unknownTag(tag) + case .finishContinuation(let c, let response): + c.yield(.tagged(response)) + c.finish() + } + } + } + + mutating func markAsClosed(reason: IMAPConnection.CloseReason) -> CloseAction { + // Keep the error the connection first failed with: a later, orderly close must not + // overwrite the reason the caller is waiting to hear about. + switch self { + case .streams(_, let continuations): + let error = reason.error ?? .connectionClosed + self = .connectionClosed(error) + return .finishContinuations(continuations, error) + case .connectionClosed: + return .none + } + } + + enum CloseAction { + case none + case finishContinuations( + [IMAPConnection.Tag: AsyncThrowingStream.Continuation], + IMAPConnection.Error + ) + + func run(logger: Logger) { + switch self { + case .none: + break + case .finishContinuations(let continuations, let error): + for (tag, c) in continuations { + logger.debug( + "Command was still running when connection was closed", + metadata: ["imap.tag": "\(tag)"] + ) + c.finish(throwing: error) + } + } + } + } +} + +// MARK: - Greeting + +extension IMAPConnection { + /// The server's initial greeting received when the connection opens. + public struct Greeting: Hashable, Sendable { + public var status: UntaggedStatus + + public init( + status: UntaggedStatus + ) { + self.status = status + } + } + + private func didReceive(greeting: Greeting) { + state.withLock { state in + state.greeting.store(greeting) + }.run() + } + + var greeting: IMAPConnection.Greeting { + get async throws { + try await withCheckedThrowingContinuation { c in + state.withLock { state in + state.greeting.get(continuation: c) + }.run() + } + } + } +} + +extension IMAPConnection.State { + enum GreetingState: Sendable { + case greeting(IMAPConnection.Greeting) + case waiting([CheckedContinuation]) + /// The connection is gone. Anything waiting for the greeting fails with this error. + case connectionClosed(any Swift.Error) + } +} + +extension IMAPConnection.State.GreetingState { + mutating func store(_ new: IMAPConnection.Greeting) -> StoreAction { + switch self { + case .greeting: + return .none + case .waiting(let waiting): + self = .greeting(new) + return .resume(waiting, new) + case .connectionClosed: + // The connection is already gone: keep the failure, don't resurrect the state. + return .none + } + } + + enum StoreAction: Sendable { + case none + case resume([CheckedContinuation], IMAPConnection.Greeting) + case fail([CheckedContinuation], any Swift.Error) + + func run() { + switch self { + case .none: + break + case .resume(let continuations, let result): + for c in continuations { + c.resume(returning: result) + } + case .fail(let continuations, let error): + for c in continuations { + c.resume(throwing: error) + } + } + } + } + + mutating func markAsClosed(reason: IMAPConnection.CloseReason) -> StoreAction { + switch self { + case .greeting: + // The greeting arrived; nothing is waiting and later commands report the closure. + return .none + case .waiting(let waiting): + let error = reason.error ?? .connectionClosed + self = .connectionClosed(error) + return .fail(waiting, error) + case .connectionClosed: + // Keep the error the connection first failed with. + return .none + } + } + + mutating func get( + continuation: CheckedContinuation + ) -> GetAction { + switch self { + case .greeting(let g): + return .resume(continuation, g) + case .waiting(var w): + w.append(continuation) + self = .waiting(w) + return .none + case .connectionClosed(let error): + return .fail(continuation, error) + } + } + + enum GetAction: Sendable { + case none + case resume(CheckedContinuation, IMAPConnection.Greeting) + case fail(CheckedContinuation, any Swift.Error) + + func run() { + switch self { + case .none: + break + case .resume(let continuation, let result): + continuation.resume(returning: result) + case .fail(let continuation, let error): + continuation.resume(throwing: error) + } + } + } +} diff --git a/Sources/IMAPCommands/IMAPConnectionError.swift b/Sources/IMAPCommands/IMAPConnectionError.swift new file mode 100644 index 00000000..e0409a04 --- /dev/null +++ b/Sources/IMAPCommands/IMAPConnectionError.swift @@ -0,0 +1,93 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +extension IMAPConnection { + /// An error the connection throws on its own behalf. + /// + /// Everything a command can fail with falls into one of three groups, and only this one is + /// an `IMAPConnection.Error`: + /// + /// - The *connection* failed — it could not be opened, the channel broke, a response could + /// not be parsed, or it was closed while a command was still running. That is this type. + /// - The *server* refused the command with a `NO` or `BAD` tagged response. That is not an + /// error: it arrives as a `TaggedResponse`, and only becomes one — + /// ``TaggedResponse/StateNotOK`` — if you ask for it with `checkOK()` or `getOK()`. + /// - *Your own* handler closure threw. ``IMAPConnection/send(_:_:)`` and its siblings + /// rethrow that error unchanged; they never wrap it in this type. + public enum Error: Swift.Error, Sendable { + /// The connection was closed in an orderly fashion before the operation completed. + /// + /// Either the ``IMAPConnection/withConnection(configuration:_:)`` closure returned, or + /// the server sent EOF. + case connectionClosed + + /// The connection failed. + /// + /// The associated value is what caused the failure — a `NIOCore`, `NIOSSL`, or + /// `NIOIMAPCore` error, depending on whether the connection could not be opened, the + /// TLS handshake failed, the channel broke, or a response could not be parsed. The set + /// of errors that can appear here is open, which is why it is carried as `any Error` + /// rather than enumerated. + case connectionFailed(any Swift.Error) + + /// The server's first response was something other than a greeting. + case unexpectedGreeting(Response) + + /// The command's response stream ended without the `TaggedResponse` that completes it. + case missingTaggedResponse + + /// The server sent a tagged response for a tag that no in-flight command owns. + /// + /// The associated value is the tag the server used. + case unknownTag(String) + } +} + +extension IMAPConnection.Error: CustomStringConvertible { + public var description: String { + switch self { + case .connectionClosed: + "The connection was closed." + case .connectionFailed(let underlying): + "The connection failed: \(underlying)" + case .unexpectedGreeting(let response): + "The server sent \(response) instead of a greeting." + case .missingTaggedResponse: + "The command ended without a tagged response." + case .unknownTag(let tag): + "The server sent a response for the unknown tag '\(tag)'." + } + } +} + +extension IMAPConnection.Error { + /// Maps the plumbing's errors — which a caller cannot name — onto this one. + init(wrapping error: any Swift.Error) { + if let error = error as? IMAPConnection.Error { + self = error + return + } + if error is CommandStreamPartQueue.DidClose { + self = .connectionClosed + return + } + if let error = error as? OutboundQueue.Error, case .inFailedState = error { + self = .connectionClosed + return + } + self = .connectionFailed(error) + } +} diff --git a/Sources/IMAPCommands/IMAPCredential.swift b/Sources/IMAPCommands/IMAPCredential.swift new file mode 100644 index 00000000..01dbef43 --- /dev/null +++ b/Sources/IMAPCommands/IMAPCredential.swift @@ -0,0 +1,180 @@ +//===----------------------------------------------------------------------===// +// +// 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 +// +//===----------------------------------------------------------------------===// + +#if canImport(FoundationEssentials) +import FoundationEssentials +#else +import Foundation +#endif +import NIOIMAP + +/// A credential used to authenticate an IMAP connection. +public enum IMAPCredential: Equatable, Sendable { + case username(String, password: String) + case sasl(mechanism: AuthenticationMechanism, response: Data) +} + +extension IMAPCredential: CustomStringConvertible { + /// A description with the secret redacted. + /// + /// The password (and SASL response) is replaced with a `[N bytes]` placeholder, + /// matching the _personally identifiable information_ redaction convention used by + /// `NIOIMAPCore` when encoding commands in logging mode. This keeps credentials + /// out of logs even when a credential is interpolated into a string. + public var description: String { + switch self { + case .username(let u, password: let p): + return "\(u):[\(p.utf8.count) bytes]" + case .sasl(mechanism: let mechanism, response: let response): + return "SASL \(String(mechanism)) [\(response.count) bytes]" + } + } +} + +extension IMAPCredential { + /// Creates a credential by extracting authentication information from URL, SASL, or username text. + /// + /// Exactly one of the parameters must be non-`nil`. If a URL is provided, the initializer + /// extracts the username and password from the URL's user info component. + /// + /// - Throws: ``ParseError`` if none or more than one of the parameters is non-`nil`, or if + /// the one that is cannot be parsed. + public init( + url urlText: String?, + sasl saslText: String?, + username userText: String? + ) throws(ParseError) { + // The `urlText` may or may not be an actual URL. That’s ok. + // Only _if_ it’s a URL, try to get credentials from it. + // And we also want to support a valid URL without credentials. + let url = urlText.flatMap { URL(string: $0) } + switch (url?.user, url?.password, saslText, userText) { + case (let u?, let p?, nil, nil): + self = .username(u, password: p) + case (nil, nil, let s?, nil): + let name = s.prefix { $0 != ":" } + let remainder = s[name.endIndex...] + // `AuthenticationMechanism` normalizes the name to uppercase, and rejects a name that + // RFC 4422 doesn’t allow — which subsumes checking for an empty name. + guard + let mechanism = AuthenticationMechanism(String(name)), + remainder.first == ":", + let response = Self.parseSASLResponse(remainder.dropFirst()) + else { throw .unableToParseSASL } + self = .sasl(mechanism: mechanism, response: response) + case (nil, nil, nil, let text?): + let parts = text.split(separator: ":", omittingEmptySubsequences: false) + guard + parts.count == 2, + !parts[0].isEmpty, + !parts[1].isEmpty + else { throw .unableToParseUsernamePassword } + self = .username(String(parts[0]), password: String(parts[1])) + case (nil, nil, nil, nil): + throw .noCredentials + default: + throw .conflictingCredentials + } + } + + /// An error indicating that a credential could not be derived from the given text. + public enum ParseError: Swift.Error, Hashable, Sendable { + /// The SASL text could not be parsed. + /// + /// Either it is not of the form `mechanism:response`, the mechanism is not a name + /// RFC 4422 allows, or the response is neither base64 nor whitespace separated parts. + case unableToParseSASL + /// The username text is not `username:password`. + case unableToParseUsernamePassword + /// More than one of the URL, SASL, and username parameters was given. + case conflictingCredentials + /// None of the URL, SASL, and username parameters was given. + case noCredentials + } +} + +extension IMAPCredential.ParseError: CustomStringConvertible { + public var description: String { + switch self { + case .unableToParseSASL: + "Unable to parse SASL input." + case .unableToParseUsernamePassword: + "Unable to parse username + password. Use username:password pattern." + case .conflictingCredentials: + "Found multiple (conflicting) credentials." + case .noCredentials: + "No credentials specified." + } + } +} + +// MARK: - + +extension IMAPCredential { + /// Parses the part of the SASL text that follows the `mechanism:` prefix. + /// + /// A response that is a single base64 encoded value is decoded as-is. Anything else is + /// treated as a list of whitespace separated parts, which are joined with a `NUL` + /// separator — the wire format used by mechanisms such as `PLAIN`. + /// + /// Returns `nil` if the text is neither. + private static func parseSASLResponse(_ text: Substring) -> Data? { + singleBase64SASLResponse(text) ?? whitespaceSeparatedSASLResponse(text) + } + + private static func singleBase64SASLResponse(_ text: Substring) -> Data? { + guard + !text.isEmpty, + text.utf8.allSatisfy({ $0.isBase64Byte }) + else { return nil } + return Data(base64Encoded: String(text)) + } + + private static func whitespaceSeparatedSASLResponse(_ text: Substring) -> Data? { + // A response must not start with whitespace. An empty response is allowed, and + // results in an empty (zero byte) response. + guard !(text.first?.isSASLWhitespace ?? false) else { return nil } + return + text + .split(whereSeparator: { $0.isSASLWhitespace }) + .reduce(into: Data()) { + if !$0.isEmpty { + $0.append(0) + } + $0.append(contentsOf: $1.utf8) + } + } +} + +extension Character { + /// Whether this is a space or tab. + /// + /// SASL responses are separated by ASCII whitespace only. + fileprivate var isSASLWhitespace: Bool { + (self == " ") || (self == "\t") + } +} + +extension UInt8 { + /// Whether this is a byte that can appear in base64 encoded data, including its padding. + fileprivate var isBase64Byte: Bool { + switch self { + case UInt8(ascii: "0")...UInt8(ascii: "9"): true + case UInt8(ascii: "A")...UInt8(ascii: "Z"): true + case UInt8(ascii: "a")...UInt8(ascii: "z"): true + case UInt8(ascii: "/"), UInt8(ascii: "+"), UInt8(ascii: "="): true + default: false + } + } +} diff --git a/Sources/IMAPCommands/OutboundQueue.swift b/Sources/IMAPCommands/OutboundQueue.swift new file mode 100644 index 00000000..16a246c3 --- /dev/null +++ b/Sources/IMAPCommands/OutboundQueue.swift @@ -0,0 +1,515 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP +import Synchronization + +/// Manages the outbound part of the connection. +/// +/// Coordinates sending commands to the server via a ``CommandStreamPartQueue``. +/// During an `APPEND` operation, all other writes are paused until the append completes. +final class OutboundQueue: Sendable { + fileprivate let state = Mutex(State.normal(CommandStreamPartQueue())) + + init() {} + + fileprivate enum State { + case normal(CommandStreamPartQueue) + case runningAppend(Append) + + /// The state during an active `APPEND` operation. + /// + /// Only the ``IMAPConnection/AppendWriter`` can write to the queue. All other writes + /// are held in the `pending` list until the append completes. + struct Append { + var queue: CommandStreamPartQueue + var pending: [Pending] + + enum Pending { + case write(CommandStreamPartQueue.PendingItem) + case append(CheckedContinuation<_AppendWriter, any Swift.Error>) + } + } + } +} + +// MARK: - Run + +extension OutboundQueue { + func run(outbound: NIOAsyncChannelOutboundWriter) async throws { + while let next = try await nextOutboundOut() { + do { + try await outbound.write(contentsOf: next.payload) + } catch { + // The items are already popped off the queue, so `close()` will not fail + // them. Fail them here — otherwise the writers stay parked forever when + // the channel goes away (or this task is cancelled) mid-write. + for c in next.completions { + c.resume(throwing: error) + } + throw error + } + for c in next.completions { + c.resume() + } + } + } +} + +// MARK: - Close + +extension OutboundQueue { + func close() { + state.withLock { state in + state.close() + }.run() + } +} + +extension OutboundQueue.State { + /// Closes the underlying queue and, when an `APPEND` is in flight, also fails every + /// operation parked in `pending` (regular writes and queued appends). + /// + /// Otherwise those continuations would be orphaned: `finishAppend()` only drains + /// `pending` when the in-flight append completes, which never happens once the + /// connection is torn down. + mutating func close() -> CloseAction { + switch self { + case .normal(var queue): + let queueAction = queue.close() + self = .normal(queue) + return CloseAction(queue: queueAction, pending: []) + case .runningAppend(var append): + let queueAction = append.queue.close() + let pending = append.pending + append.pending = [] + // Drop back to `.normal` (with the now-closed queue) so any later writes + // fail fast rather than parking in a `pending` list nobody drains. + self = .normal(append.queue) + return CloseAction(queue: queueAction, pending: pending) + } + } + + struct CloseAction { + var queue: CommandStreamPartQueue.CloseAction + var pending: [OutboundQueue.State.Append.Pending] + + func run() { + queue.run() + for item in pending { + switch item { + case .write(let pendingItem): + pendingItem.completion.resume(throwing: CommandStreamPartQueue.DidClose()) + case .append(let continuation): + continuation.resume(throwing: OutboundQueue.Error.inFailedState) + } + } + } + } +} + +// MARK: - Next `OutboundOut` + +extension OutboundQueue { + func nextOutboundOut() async throws -> CommandStreamPartQueue.Next? { + let next = try await withCheckedThrowingContinuation { continuation in + state.withLock { + $0.nextOutboundOut(continuation) + }.run() + } + return next + } +} + +extension OutboundQueue.State { + mutating func nextOutboundOut( + _ continuation: CheckedContinuation + ) -> CommandStreamPartQueue.NextAction { + withQueue { queue in + return queue.next(continuation) + } + } + + mutating func withQueue( + _ closure: (inout CommandStreamPartQueue) -> R + ) -> R { + switch self { + case .normal(var queue): + let r = closure(&queue) + self = .normal(queue) + return r + case .runningAppend(var append): + let r = closure(&append.queue) + self = .runningAppend(append) + return r + } + } +} + +// MARK: - Encoding Options + +extension OutboundQueue { + /// Suspends on a queue operation, mapping its failure onto ``IMAPConnection/Error``. + /// + /// The continuation is resumed from the channel, from ``close()``, or from a state-machine + /// guard, so the raw failure can be anything. + fileprivate func withQueueContinuation( + _ body: (CheckedContinuation) -> Void + ) async throws(IMAPConnection.Error) { + do { + try await withCheckedThrowingContinuation(body) + } catch { + throw IMAPConnection.Error(wrapping: error) + } + } + + func setEncodingOptions( + _ new: IMAPClientHandler.EncodingOptions + ) async throws(IMAPConnection.Error) { + try await withQueueContinuation { continuation in + state.withLock { + $0.setEncodingOptions(new, completion: continuation) + }.run() + } + } +} + +extension OutboundQueue.State { + mutating func setEncodingOptions( + _ new: IMAPClientHandler.EncodingOptions, + completion: CheckedContinuation + ) -> CommandStreamPartQueue.WriteAction { + write( + [.setEncodingOptions(new)], + completion: completion + ) + } +} + +// MARK: - Write (regular) Command + +extension OutboundQueue { + func write( + _ command: TaggedCommand + ) async throws(IMAPConnection.Error) { + try await write(CollectionOfOne(command)) + } + + func write( + _ commands: some Sequence + ) async throws(IMAPConnection.Error) { + try await withQueueContinuation { continuation in + state.withLock { + $0.write(commands, completion: continuation) + }.run() + } + } + + func writeIdleDone() async throws(IMAPConnection.Error) { + try await withQueueContinuation { continuation in + state.withLock { + $0.writeIdleDone(completion: continuation) + }.run() + } + } +} + +extension OutboundQueue.State { + mutating func writeIdleDone( + completion: CheckedContinuation + ) -> CommandStreamPartQueue.WriteAction { + write( + [IMAPClientHandler.OutboundIn.part(.idleDone)], + completion: completion + ) + } + + mutating func write( + _ commands: some Sequence, + completion: CheckedContinuation + ) -> CommandStreamPartQueue.WriteAction { + write( + commands.map { + .part(.tagged($0)) + }, + completion: completion + ) + } + + mutating func write( + _ parts: [IMAPClientHandler.OutboundIn], + completion: CheckedContinuation + ) -> CommandStreamPartQueue.WriteAction { + switch self { + case .normal(var queue): + let action = queue.write( + payload: parts, + continuation: completion + ) + self = .normal(queue) + return action + case .runningAppend(var append): + append.pending.append( + .write( + .init( + payload: parts, + completion: completion + ) + ) + ) + self = .runningAppend(append) + return .none + } + } +} + +// MARK: - Write Continuation Data (during authentication) + +extension OutboundQueue { + func writeContinuationResponse( + _ bytes: ByteBuffer + ) async throws(IMAPConnection.Error) { + try await withQueueContinuation { continuation in + state.withLock { + $0.write([.part(.continuationResponse(bytes))], completion: continuation) + }.run() + } + } +} + +// MARK: - APPEND + +extension OutboundQueue { + fileprivate struct _AppendWriter {} + + /// A writer for sending ``AppendCommand`` values during an `APPEND` operation. + /// + /// Writes append command parts into the ``OutboundQueue``. + struct AppendQueueWriter: ~Copyable { + fileprivate let queue: OutboundQueue + + fileprivate init( + writer: _AppendWriter, + queue: OutboundQueue + ) { + self.queue = queue + } + + func write( + _ parts: [AppendCommand] + ) async throws(IMAPConnection.Error) { + try await queue.withQueueContinuation { continuation in + queue.state.withLock { + $0.writeAppend( + parts: parts, + continuation: continuation + ) + }.run() + } + } + } + + func withAppendWriter( + _ closure: nonisolated(nonsending) (consuming AppendQueueWriter) async throws -> R + ) async throws -> R { + // Try to create a writer: + let writer = try await AppendQueueWriter( + writer: makeAppendWriter(), + queue: self + ) + let result: Result + do { + result = .success(try await closure(writer)) + } catch { + result = .failure(error) + } + await finishAppend() + return try result.get() + } +} + +extension OutboundQueue.State { + mutating func writeAppend( + parts: [AppendCommand], + continuation: CheckedContinuation + ) -> CommandStreamPartQueue.WriteAction { + switch self { + case .normal: + // We _must_ be in the `.runningAppend` state + // at this point since the lifetime of the + // AppendQueueWriter is managed as such. + return .failWrite(continuation, .tryingToAppendButNotInWritingAppendState) + case .runningAppend(var append): + defer { + self = .runningAppend(append) + } + return append.queue.write( + payload: parts.map { .part(.append($0)) }, + continuation: continuation + ) + } + } +} + +extension OutboundQueue { + fileprivate func makeAppendWriter() async throws(IMAPConnection.Error) -> _AppendWriter { + do { + return try await withCheckedThrowingContinuation { continuation in + let action = state.withLock { + $0.makeAppendWriter(continuation) + } + switch action { + case .none: + break + case .resumeContinuation: + continuation.resume(with: .success(_AppendWriter())) + case .failContinuation: + continuation.resume(throwing: OutboundQueue.Error.inFailedState) + } + } + } catch { + throw IMAPConnection.Error(wrapping: error) + } + } + + fileprivate func finishAppend() async { + state.withLock { + $0.finishAppend() + }.run() + } +} + +extension OutboundQueue.State { + enum MakeAppendWriterAction { + case none + case resumeContinuation + case failContinuation + } + + mutating func makeAppendWriter( + _ continuation: CheckedContinuation + ) -> MakeAppendWriterAction { + switch self { + case .normal(let queue): + switch queue.writeState { + case .failed, .closed: + return .failContinuation + case .writing: + self = .runningAppend( + Append( + queue: queue, + pending: [] + ) + ) + return .resumeContinuation + } + case .runningAppend(var append): + append.pending.append(.append(continuation)) + self = .runningAppend(append) + return .none + } + } + + enum FinishAppendAction { + case drainActions([OutboundQueue.State.Append.DrainAction]) + + func run() { + switch self { + case .drainActions(let actions): + for a in actions { + a.run() + } + } + } + } + + mutating func finishAppend() -> FinishAppendAction { + switch self { + case .normal: + // Defensive: the `AppendQueueWriter` lifetime should guarantee we're + // in `.runningAppend` here. If not, there's nothing to drain. + return .drainActions([]) + case .runningAppend(let append): + // We now attempt to drain the pending queue + let (new, actions) = append.drainPending() + self = new + return .drainActions(actions) + } + } +} + +extension OutboundQueue.State.Append { + fileprivate enum DrainAction { + case none + case resumeNewAppend(CheckedContinuation) + case writeAction(CommandStreamPartQueue.WriteAction) + + func run() { + switch self { + case .none: + break + case .resumeNewAppend(let continuation): + continuation.resume(returning: .init()) + case .writeAction(let writeAction): + writeAction.run() + } + } + } + + /// Moves pending items into the ``CommandStreamPartQueue``. + /// + /// Returns a `.normal` state if all items are writes. + /// Stops and returns a new `.runningAppend` state upon encountering a pending append. + fileprivate func drainPending() -> (OutboundQueue.State, [DrainAction]) { + var actions: [DrainAction] = [] + var queue = self.queue + var remaining = pending[...] + while let r = remaining.popFirst() { + switch r { + case .write(let item): + actions.append(.writeAction(queue.write(item: item))) + case .append(let appendContinuation): + // There’a a pending append. We'll return this and stop + // moving items into the queue. + actions.append(.resumeNewAppend(appendContinuation)) + return ( + .runningAppend( + .init( + queue: queue, + pending: Array(remaining) + ) + ), + actions + ) + } + } + // We’ve (completely) drained the pending queue. + // Go back into `.normal` state: + return ( + .normal(queue), + actions + ) + } +} + +// MARK: - Error + +extension OutboundQueue { + enum Error: Swift.Error { + case inFailedState + case tryingToAppendButNotInWritingAppendState + case calledNextRecursively + } +} diff --git a/Sources/IMAPCommands/Response.swift b/Sources/IMAPCommands/Response.swift new file mode 100644 index 00000000..93b61133 --- /dev/null +++ b/Sources/IMAPCommands/Response.swift @@ -0,0 +1,118 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP + +extension UntaggedStatus { + /// Throws an error if the status is not `OK`. + /// + /// - Throws: ``StatusNotOK`` if the status is `NO`, `BAD`, `PREAUTH`, or `BYE`. + public func checkOK() throws(StatusNotOK) { + switch self { + case .ok: + return + case .no, .bad, .preauth, .bye: + throw StatusNotOK(status: self) + } + } + + /// An error indicating a non-`OK` status. + public struct StatusNotOK: Swift.Error, Sendable { + /// The status the server sent. + public var status: UntaggedStatus + + /// Creates an error reporting the given non-`OK` status. + public init(status: UntaggedStatus) { + self.status = status + } + } + + /// Returns the response text if the status is `OK`, or throws an error. + /// + /// - Throws: ``StatusNotOK`` if the status is `NO`, `BAD`, `PREAUTH`, or `BYE`. + public func getOK() throws(StatusNotOK) -> ResponseText { + switch self { + case .ok(let text): + return text + case .no, .bad, .preauth, .bye: + throw StatusNotOK(status: self) + } + } +} + +extension TaggedResponse { + /// Throws an error if the response state is not `OK`. + /// + /// - Throws: ``StateNotOK`` if the server answered `NO` or `BAD`. + public func checkOK() throws(StateNotOK) { + try state.checkOK() + } + + /// Returns the response text if the state is `OK`, or throws an error. + /// + /// - Throws: ``StateNotOK`` if the server answered `NO` or `BAD`. + public func getOK() throws(StateNotOK) -> ResponseText { + try state.getOK() + } + + /// An error indicating a non-`OK` tagged response state. + public struct StateNotOK: Swift.Error, Sendable { + /// The state the server sent. + public var state: TaggedResponse.State + + /// Creates an error reporting the given non-`OK` state. + public init(state: TaggedResponse.State) { + self.state = state + } + } +} + +extension TaggedResponse.State { + /// Throws an error if the state is not `OK`. + /// + /// - Throws: ``TaggedResponse/StateNotOK`` if the server answered `NO` or `BAD`. + public func checkOK() throws(TaggedResponse.StateNotOK) { + switch self { + case .ok: + return + case .no, .bad: + throw TaggedResponse.StateNotOK(state: self) + } + } + + /// Returns the response text if the state is `OK`, or throws an error. + /// + /// - Throws: ``TaggedResponse/StateNotOK`` if the server answered `NO` or `BAD`. + public func getOK() throws(TaggedResponse.StateNotOK) -> ResponseText { + switch self { + case .ok(let text): + return text + case .no, .bad: + throw TaggedResponse.StateNotOK(state: self) + } + } +} + +extension UntaggedStatus.StatusNotOK: CustomStringConvertible { + public var description: String { + "The server responded with \(status) rather than OK." + } +} + +extension TaggedResponse.StateNotOK: CustomStringConvertible { + public var description: String { + "The server responded with \(state) rather than OK." + } +} diff --git a/Sources/IMAPCommands/Tag.swift b/Sources/IMAPCommands/Tag.swift new file mode 100644 index 00000000..8d1a8f72 --- /dev/null +++ b/Sources/IMAPCommands/Tag.swift @@ -0,0 +1,79 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging + +extension IMAPConnection { + /// A command tag that uniquely identifies an in-flight IMAP command. + public struct Tag: Hashable, Sendable { + var rawValue: UInt64 + } +} + +extension IMAPConnection.Tag: CustomStringConvertible { + public var description: String { String(self) } +} + +extension IMAPConnection.Tag { + /// The first tag in a sequence. + public static let first = IMAPConnection.Tag(rawValue: 1) + + /// Returns the next tag in the sequence. + public func makeNext() -> IMAPConnection.Tag { + IMAPConnection.Tag(rawValue: self.rawValue &+ 1) + } +} + +extension IMAPConnection.Tag: Encodable {} + +extension IMAPConnection.Tag { + /// Logger metadata identifying the command this tag belongs to. + /// + /// Bound around every command handler — together with `imap.connection`, see + /// ``IMAPConnection/loggerMetadata(for:)`` — so that anything the handler logs through + /// `Logger.current` is attributed to the command it belongs to. The key is namespaced + /// because the metadata is merged into the caller's own logger. + var loggerMetadata: Logger.Metadata { + ["imap.tag": "\(self)"] + } +} + +extension String { + public init(_ tag: IMAPConnection.Tag) { + self = "A\(tag.rawValue)" + } +} + +extension IMAPConnection.Tag { + public init?(_ text: String) { + guard + text.count < 25, + text.allSatisfy({ $0.isASCII }), + text.first == "A" + else { return nil } + let remainder = text[text.index(after: text.startIndex)...] + guard + remainder.allSatisfy({ + guard + let v = $0.asciiValue, + 0x30 <= v, + v <= 0x39 + else { return false } + return true + }), + let value = UInt64(remainder) + else { return nil } + self.init(rawValue: value) + } +} diff --git a/Sources/IMAPCommands/WriteWeight.swift b/Sources/IMAPCommands/WriteWeight.swift new file mode 100644 index 00000000..83284b2d --- /dev/null +++ b/Sources/IMAPCommands/WriteWeight.swift @@ -0,0 +1,69 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIOIMAP + +/// A rough estimate of the number of bytes a write sends to the network. +struct WriteWeight: Hashable, Sendable, Comparable { + static func < (lhs: WriteWeight, rhs: WriteWeight) -> Bool { + lhs.underlying < rhs.underlying + } + + static func > (lhs: WriteWeight, rhs: WriteWeight) -> Bool { + lhs.underlying > rhs.underlying + } + + static func + (lhs: WriteWeight, rhs: WriteWeight) -> WriteWeight { + Self(lhs.underlying + rhs.underlying) + } + + static func += (lhs: inout WriteWeight, rhs: WriteWeight) { + lhs.underlying += rhs.underlying + } + + init(_ underlying: Int) { + self.underlying = underlying + } + + private var underlying: Int +} + +extension IMAPClientHandler.OutboundIn { + var writeWeight: WriteWeight { + switch self { + case .part(let part): + switch part { + case .idleDone, + .tagged, + .append(.start), + .append(.beginMessage), + .append(.endMessage), + .append(.beginCatenate), + .append(.catenateData(.begin)), + .append(.catenateData(.end)), + .append(.endCatenate), + .append(.finish): + WriteWeight(100) + case .append(.messageBytes(let buffer)), + .append(.catenateData(.bytes(let buffer))), + .append(.catenateURL(let buffer)): + WriteWeight(100 + buffer.readableBytes) + case .continuationResponse(let b): + WriteWeight(b.readableBytes * 2) + } + case .setEncodingOptions: + WriteWeight(0) + } + } +} diff --git a/Sources/NIOIMAP/NIOIMAP.docc/GettingStarted.md b/Sources/NIOIMAP/NIOIMAP.docc/GettingStarted.md new file mode 100644 index 00000000..3603907b --- /dev/null +++ b/Sources/NIOIMAP/NIOIMAP.docc/GettingStarted.md @@ -0,0 +1,65 @@ +# Getting Started with NIOIMAP + +Open a connection, insert the client handler, and exchange commands and responses as a stream of events. + +## Overview + +NIOIMAP gives you a SwiftNIO `ChannelHandler` — ``IMAPClientHandler`` — that decodes the inbound byte stream into `Response` values and encodes the `CommandStreamPart` values you write into IMAP wire format. To drive a session with `async`/`await`, add the handler to a `ChannelPipeline` and wrap the channel in a `NIOAsyncChannel`. + +### Connecting + +Connect to the server, add ``IMAPClientHandler`` to the pipeline, and wrap the channel so that decoded responses and the commands you write flow through async sequences: + +```swift +import NIOIMAP + +let channel = try await ClientBootstrap(group: MultiThreadedEventLoopGroup.singleton) + .connect(host: "mail.example.com", port: 143) + .flatMap { channel in + channel.eventLoop.makeCompletedFuture { + try channel.pipeline.syncOperations.addHandler(IMAPClientHandler()) + return try NIOAsyncChannel( + wrappingChannelSynchronously: channel + ) + } + } + .get() +``` + +For a TLS connection (typically port 993), insert an `NIOSSLClientHandler` ahead of ``IMAPClientHandler`` in the pipeline. + +### Sending commands and consuming responses + +Each command is written as a `CommandStreamPart`. Decoded responses — including untagged responses and the final `TaggedResponse` — arrive on the inbound async sequence: + +```swift +try await channel.executeThenClose { inbound, outbound in + // Send a command. + try await outbound.write( + .part(.tagged(TaggedCommand(tag: "a001", command: .login(username: "mrc", password: "secret")))) + ) + + // Consume the stream of decoded responses. + for try await response in inbound { + print(response) + } +} +``` + +Because this is an event stream, correlating responses with the commands that produced them — matching on the command tag — is your responsibility. Commands are pipelined simply by writing several before reading their responses. + +### Choosing between the two interfaces + +This package offers two interface styles on purpose, and neither is preferred over the other: + +- **NIOIMAP** (this module) is event-driven. You work directly with the SwiftNIO pipeline and the raw stream of protocol events. Reach for it when your code already lives in a NIO pipeline, or when you want direct control over the event stream and encoding options. +- **`IMAPCommands`** is command-centric. You open a connection and `await` each command as an ordinary asynchronous call — `try await connection.send(.login(...)) { ... }`. Reach for it when you'd rather treat each command as an awaitable unit of work. + +Both talk to the same server and share the same `NIOIMAPCore` command and response types, so a client built on one can be ported to the other without changing how commands and responses are constructed. If neither obviously fits, prototype the part you care about most in each — they're deliberately close in capability, and the better fit usually becomes clear quickly. + +## Topics + +### Channel Handlers + +- ``IMAPClientHandler`` +- ``IMAPServerHandler`` diff --git a/Sources/NIOIMAP/NIOIMAP.docc/NIOIMAP.md b/Sources/NIOIMAP/NIOIMAP.docc/NIOIMAP.md new file mode 100644 index 00000000..f2dd8c05 --- /dev/null +++ b/Sources/NIOIMAP/NIOIMAP.docc/NIOIMAP.md @@ -0,0 +1,56 @@ +# ``NIOIMAP`` + +Drive an IMAP4rev1 conversation as a stream of protocol events on a SwiftNIO `ChannelPipeline`. + +## Overview + +NIOIMAP connects the parser and encoder from `NIOIMAPCore` to [SwiftNIO](https://github.com/apple/swift-nio). It provides a pair of `ChannelHandler`s — ``IMAPClientHandler`` and ``IMAPServerHandler`` — that you insert into a `ChannelPipeline`. The client handler turns the inbound byte stream into decoded `Response` values and encodes the `CommandStreamPart` values you write back into IMAP wire format. + +This is an **event-driven** interface. You work directly with the stream of protocol events: you write commands to the pipeline and consume decoded responses as they arrive, typically by wrapping the channel in a `NIOAsyncChannel`. This style fits code that already lives in a SwiftNIO pipeline, or that wants direct control over the flow of protocol events and over encoding options. + +NIOIMAP re-exports `NIOIMAPCore`, so the strongly-typed command and response values are available without a separate import. + +- Note: This is one of **two** interface styles this package offers, and neither is preferred over the other. If you'd rather treat each command as an awaitable unit of work — `let result = try await connection.send(...)` — see the `IMAPCommands` module, which provides a command-centric `async`/`await` client built on top of NIOIMAP. Both interfaces talk to the same server and share the same `NIOIMAPCore` command and response types; choose based on how your own code wants to be structured. See for a side-by-side comparison. + +### Layering + +The package is layered so you can work at whichever level suits your needs: + +| Module | What it gives you | +| --- | --- | +| `NIOIMAPCore` | The IMAP grammar as Swift types, plus the parser and encoder. No networking. | +| **`NIOIMAP`** | SwiftNIO `ChannelHandler`s that plug the parser and encoder into a `ChannelPipeline`. Re-exports `NIOIMAPCore`. | +| `IMAPCommands` | A high-level `async`/`await` client centered on `IMAPConnection`, built on top of NIOIMAP. | + +## Topics + +### Essentials + +- + +### Channel Handlers + +- ``IMAPClientHandler`` +- ``IMAPServerHandler`` + +### Framing + +- ``FrameDecoder`` +- ``FramingParser`` +- ``FramingResult`` + +### Errors + +- ``InvalidFrame`` +- ``LiteralSizeParsingError`` +- ``ReceivedIncompleteFrame`` +- ``ReceivedInvalidFrame`` +- ``IMAPDecoderError`` +- ``UnexpectedResponse`` +- ``UnexpectedContinuationRequest`` +- ``UnexpectedAppendCommand`` +- ``UnexpectedChunk`` +- ``DuplicateCommandTag`` +- ``InvalidClientState`` +- ``InvalidCommandForState`` +- ``InvalidIdleState`` diff --git a/Sources/NIOIMAPCore/Grammar/Response/ResponsePayload.swift b/Sources/NIOIMAPCore/Grammar/Response/ResponsePayload.swift index 412a10e2..07409fa7 100644 --- a/Sources/NIOIMAPCore/Grammar/Response/ResponsePayload.swift +++ b/Sources/NIOIMAPCore/Grammar/Response/ResponsePayload.swift @@ -14,8 +14,6 @@ #if canImport(FoundationEssentials) import FoundationEssentials -#elseif swift(<6.0) -@preconcurrency import Foundation #else import Foundation #endif diff --git a/Sources/NIOIMAPCore/NIOIMAPCore.docc/NIOIMAPCore.md b/Sources/NIOIMAPCore/NIOIMAPCore.docc/NIOIMAPCore.md index 9eb7eb7b..074d4e97 100644 --- a/Sources/NIOIMAPCore/NIOIMAPCore.docc/NIOIMAPCore.md +++ b/Sources/NIOIMAPCore/NIOIMAPCore.docc/NIOIMAPCore.md @@ -40,7 +40,12 @@ buffer.writeResponse(response) ### Module Separation -NIOIMAPCore focuses purely on protocol parsing and encoding. For SwiftNIO integration (channel handlers, async/await APIs), see the NIOIMAP module, which builds on top of NIOIMAPCore. +NIOIMAPCore focuses purely on protocol parsing and encoding. For SwiftNIO integration, the package layers two client interfaces on top — offered on purpose, with neither preferred over the other: + +- The `NIOIMAP` module provides event-driven SwiftNIO `ChannelHandler`s. It re-exports NIOIMAPCore. +- The `IMAPCommands` module provides a high-level, command-centric `async`/`await` client built on top of `NIOIMAP`. + +Both share the NIOIMAPCore command and response types described here. ## Topics diff --git a/Tests/IMAPCommandsTests/AppendWriterTests.swift b/Tests/IMAPCommandsTests/AppendWriterTests.swift new file mode 100644 index 00000000..9d2b8165 --- /dev/null +++ b/Tests/IMAPCommandsTests/AppendWriterTests.swift @@ -0,0 +1,319 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIO +import NIOIMAP +import Synchronization +import Testing + +/// Tests for the command stream an `APPEND` produces. +/// +/// These drive `OutboundQueue` and `IMAPConnection.AppendWriter` against a testing writer, so +/// they need no socket and no server. +@Suite("APPEND writer", .timeLimit(.minutes(1))) +enum AppendWriterTests { + static let mailbox = MailboxName(Array("INBOX".utf8)) + + static let message = AppendMessage( + options: AppendOptions(), + data: AppendData(byteCount: 3) + ) + + /// The happy path: `.start` and `.finish` bracket the message the closure writes. + @Test + static func appendBracketsTheMessageWithStartAndFinish() async throws { + let result = await runAppend(expectedPartCount: 5) { writer in + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + } + + #expect(result.error == nil) + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginMessage(message: message))), + .part(.append(.messageBytes(ByteBuffer(string: "abc")))), + .part(.append(.endMessage)), + .part(.append(.finish)), + ] + ) + } + + /// A closure that writes no message can not produce a valid `APPEND`: `.finish` is only + /// legal after at least one message. Rather than writing it — which traps in the client + /// state machine — the writer throws. + @Test + static func appendWithoutAMessageThrowsInsteadOfWritingFinish() async throws { + let result = await runAppend(expectedPartCount: 1) { _ in + // Write nothing at all. + } + + #expect(result.error as? IMAPConnection.IncompleteAppend == .init(reason: .noMessage)) + // Only the command itself was written; no `.finish`. + #expect(result.parts == [.part(.append(.start(tag: "A1", appendingTo: mailbox)))]) + } + + /// A closure that throws part-way through leaves the command unfinished: `.finish` must not + /// be written, and the error is propagated. + @Test + static func appendClosureErrorPropagatesWithoutFinishing() async throws { + struct WriterError: Swift.Error {} + + let result = await runAppend(expectedPartCount: 2) { writer in + try await writer.write(message: message) { _ in + throw WriterError() + } + } + + #expect(result.error is WriterError) + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginMessage(message: message))), + ] + ) + } + + /// Swallowing a mid-message failure must not let the command be completed: `.finish` after + /// a half-written message traps in the client state machine. + @Test + static func swallowedMidMessageErrorStillFailsTheAppend() async throws { + struct WriterError: Swift.Error {} + + let result = await runAppend(expectedPartCount: 2) { writer in + try? await writer.write(message: message) { _ in + throw WriterError() + } + } + + #expect(result.error as? IMAPConnection.IncompleteAppend == .init(reason: .unfinishedMessage)) + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginMessage(message: message))), + ] + ) + } + + /// … and nothing more can be written after such a failure, either. + @Test + static func writingAfterAnUnfinishedMessageThrows() async throws { + struct WriterError: Swift.Error {} + + let secondWriteError = Mutex<(any Swift.Error)?>(nil) + let result = await runAppend(expectedPartCount: 2) { writer in + try? await writer.write(message: message) { _ in + throw WriterError() + } + do { + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + } catch { + secondWriteError.withLock { $0 = error } + } + } + + #expect( + secondWriteError.withLock { $0 } as? IMAPConnection.IncompleteAppend + == .init(reason: .unfinishedMessage), + "Writing another message after an unfinished one must fail rather than emit invalid data." + ) + #expect(result.error as? IMAPConnection.IncompleteAppend == .init(reason: .unfinishedMessage)) + // The second message was never begun. + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginMessage(message: message))), + ] + ) + } + + /// `CATENATE` needs at least one URL or one piece of data. + @Test + static func emptyCatenateThrows() async throws { + let result = await runAppend(expectedPartCount: 2) { writer in + try await writer.catenate(options: AppendOptions()) { _ in + // Add nothing. + } + } + + #expect(result.error as? IMAPConnection.IncompleteAppend == .init(reason: .noMessage)) + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginCatenate(options: AppendOptions()))), + ] + ) + } + + /// A catenated message of a URL and some data is bracketed just like a plain message. + @Test + static func catenateWritesURLsAndData() async throws { + let result = await runAppend(expectedPartCount: 8) { writer in + try await writer.catenate(options: AppendOptions()) { catenateWriter in + try await catenateWriter.writeURL(ByteBuffer(string: "/INBOX;UID=1")) + try await catenateWriter.writeData(byteCount: 3) { dataWriter in + try await dataWriter.write(ByteBuffer(string: "abc")) + } + } + } + + #expect(result.error == nil) + #expect( + result.parts == [ + .part(.append(.start(tag: "A1", appendingTo: mailbox))), + .part(.append(.beginCatenate(options: AppendOptions()))), + .part(.append(.catenateURL(ByteBuffer(string: "/INBOX;UID=1")))), + .part(.append(.catenateData(.begin(size: 3)))), + .part(.append(.catenateData(.bytes(ByteBuffer(string: "abc"))))), + .part(.append(.catenateData(.end))), + .part(.append(.endCatenate)), + .part(.append(.finish)), + ] + ) + } + + // MARK: - `finish()` + + /// Finishing explicitly — which is what a closure has to do before it can wait for the + /// command's tagged response — writes `.finish` there, and the implicit finish afterwards + /// is a no-op rather than a second `.finish`. + @Test + static func explicitFinishIsIdempotent() async throws { + let result = await runAppend(expectedPartCount: 5) { writer in + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + try await writer.finish() + try await writer.finish() + } + + #expect(result.error == nil) + #expect(result.didComplete) + #expect(result.parts.filter { $0 == .part(.append(.finish)) }.count == 1) + } + + /// Writing more data after finishing would be a protocol violation. + @Test + static func writingAfterFinishThrows() async throws { + let secondWriteError = Mutex<(any Swift.Error)?>(nil) + let result = await runAppend(expectedPartCount: 5) { writer in + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + try await writer.finish() + do { + try await writer.write(message: message) { _ in } + } catch { + secondWriteError.withLock { $0 = error } + } + } + + #expect(secondWriteError.withLock { $0 } is IMAPConnection.AppendAlreadyFinished) + #expect(result.error == nil) + #expect(result.didComplete) + #expect(result.parts.last == .part(.append(.finish))) + } + + /// An error thrown _after_ the command was completed reports the command as complete, so + /// that `append` rethrows it without closing the connection. + @Test + static func errorAfterFinishStillCompletesTheCommand() async throws { + struct HandlerError: Swift.Error {} + + let result = await runAppend(expectedPartCount: 5) { writer in + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + try await writer.finish() + throw HandlerError() + } + + #expect(result.error is HandlerError) + #expect(result.didComplete, "The command was written in full, so the connection stays usable.") + } + + /// … whereas an error before that reports it as incomplete. + @Test + static func errorBeforeFinishLeavesTheCommandIncomplete() async throws { + struct WriterError: Swift.Error {} + + let result = await runAppend(expectedPartCount: 4) { writer in + try await writer.write(message: message) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + throw WriterError() + } + + #expect(result.error is WriterError) + #expect(!result.didComplete) + #expect(result.parts.contains(.part(.append(.finish))) == false) + } + + // MARK: - Helper + + /// Runs `body` as the closure of an `APPEND` on a queue backed by a testing writer, and + /// returns the parts that reached the writer along with the error `body` produced, if any. + /// + /// `expectedPartCount` is how many parts the collector waits for before it stops; the + /// queue's writes only complete once the runner has handed them to the writer, so all + /// parts have been produced by the time `body` returns. + private static func runAppend( + expectedPartCount: Int, + _ body: (inout IMAPConnection.AppendWriter) async throws -> Void + ) async -> (parts: [IMAPClientHandler.OutboundIn], error: (any Swift.Error)?, didComplete: Bool) { + let (outbound, sink) = NIOAsyncChannelOutboundWriter.makeTestingWriter() + let queue = OutboundQueue() + let parts = LockedBox<[IMAPClientHandler.OutboundIn]>([]) + let thrownError = LockedBox<(any Swift.Error)?>(nil) + var didCompleteCommand = false + + await withTaskGroup(of: Void.self) { group in + group.addTask { + try? await queue.run(outbound: outbound) + } + + group.addTask { + var collected = 0 + for await part in sink { + parts.withLock { $0.append(part) } + collected += 1 + guard collected < expectedPartCount else { break } + } + } + + // The append itself runs here, in the parent task: `body` is non-escaping. + do { + try await queue.withAppendWriter { (writer: consuming OutboundQueue.AppendQueueWriter) in + try await IMAPConnection.AppendWriter.withAppendWriter( + tag: "A1", + appendingTo: mailbox, + underlying: writer, + didCompleteCommand: &didCompleteCommand + ) { appendWriter in + try await body(&appendWriter) + } + } + } catch { + thrownError.withLock { $0 = error } + } + queue.close() + } + + return (parts.withLock { $0 }, thrownError.withLock { $0 }, didCompleteCommand) + } +} diff --git a/Tests/IMAPCommandsTests/CommandStreamPartQueueTests.swift b/Tests/IMAPCommandsTests/CommandStreamPartQueueTests.swift new file mode 100644 index 00000000..51583402 --- /dev/null +++ b/Tests/IMAPCommandsTests/CommandStreamPartQueueTests.swift @@ -0,0 +1,200 @@ +//===----------------------------------------------------------------------===// +// +// 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 DequeModule +import Testing +import NIO +import NIOIMAP +import Synchronization + +private typealias PendingItem = CommandStreamPartQueue.PendingItem +private typealias Next = CommandStreamPartQueue.Next + +@Suite("CommandStreamPartQueue Tests") +private enum CommandStreamPartQueueTests { + @Test + static func closeWithPendingWrites() async throws { + // If we append a write, and then close + // the queue, the pending write completions + // should get run. + var sut = CommandStreamPartQueue() + do { + try await withCheckedThrowingContinuation { completion in + sut.writeState = .writing([ + PendingItem( + payload: [.part(.tagged(.init(tag: "A1", command: .noop)))], + completion: completion + ) + ]) + sut.close().run() + } + Issue.record("Should have thrown an error.") + } catch { + // Ignore. + } + } + + @Test + static func closeWithPendingRead() async throws { + // If we’re waiting for items to be output, + // That closure should return `nil`. + var sut = CommandStreamPartQueue() + do { + let next: Next? = try await withCheckedThrowingContinuation { completion in + sut.readState = .waitingForItem(completion) + sut.close().run() + } + #expect(next == nil) + } catch { + Issue.record(error, "Should not have thrown an error.") + } + } + + @Test + static func closeWithoutPending() async throws { + var sut = CommandStreamPartQueue() + sut.close().run() + } + + struct PopAndMergeFixture: CustomTestStringConvertible, CustomTestArgumentEncodable { + var original: [[IMAPClientHandler.OutboundIn]] + var popped: [IMAPClientHandler.OutboundIn]? + var remainder: [[IMAPClientHandler.OutboundIn]] + + var testDescription: String { + "[" + + original + .map { + $0 + .map { String(reflecting: $0) } + .joined(separator: ",") + } + .map { + #""\#($0)""# + } + .joined(separator: "; ") + "]" + } + + func encodeTestArgument(to encoder: some Encoder) throws { + try testDescription.encode(to: encoder) + } + } + + @Test(arguments: [ + PopAndMergeFixture( + original: [], + popped: nil, + remainder: [] + ), + PopAndMergeFixture( + original: [ + [] + ], + popped: [], + remainder: [] + ), + PopAndMergeFixture( + original: [ + [.part(.tagged(.init(tag: "A1", command: .noop)))], + [.part(.tagged(.init(tag: "A2", command: .noop)))], + ], + popped: [ + .part(.tagged(.init(tag: "A1", command: .noop))), + .part(.tagged(.init(tag: "A2", command: .noop))), + ], + remainder: [] + ), + ]) + static func popAndMergePendingItems( + fixture: PopAndMergeFixture + ) async throws { + try await withPendingItems( + original: fixture.original + ) { pendingItems in + var sut = Deque(pendingItems) + let next = sut.popAndMerge() + #expect(next?.payload == fixture.popped) + next?.completions.forEach { c in + c.resume() + } + #expect(sut.map { $0.payload } == fixture.remainder) + sut.map { $0.completion }.forEach { c in + c.resume() + } + } + } + + @Test + static func nextWaitsForItems() async throws { + // If we try to get the next item, that should + // record the closure. + var sut = CommandStreamPartQueue() + do { + let next: Next? = try await withCheckedThrowingContinuation { continuation in + let action = sut.next(continuation) + switch action { + case .none: break + case .resumeContinuation: Issue.record() + } + action.run() + + switch sut.readState { + case .idle: Issue.record("Should be waiting") + case .waitingForItem(let checkedContinuation): + checkedContinuation.resume(returning: nil) + } + } + #expect(next == nil) + } catch { + Issue.record(error, "Should not have thrown an error.") + } + } +} + +/// Recursively maps `[CommandStreamPart]` to `PendingItem`, creating completion closures. +/// +/// Waits for all closures to complete. +private func withPendingItems( + original: [[IMAPClientHandler.OutboundIn]], + pendingItems: [PendingItem] = [], + do closure: @Sendable @escaping ([PendingItem]) async -> Void +) async throws { + guard + let payload = original.first + else { + return await closure(pendingItems) + } + return try await withCheckedThrowingContinuation { completion in + var p = pendingItems + p.append( + PendingItem( + payload: payload, + completion: completion + ) + ) + let o = Array(original.suffix(from: 1)) + Task { + do { + try await withPendingItems( + original: o, + pendingItems: p, + do: closure + ) + } catch { + Issue.record(error) + } + } + } +} diff --git a/Tests/IMAPCommandsTests/ConfigurationTests.swift b/Tests/IMAPCommandsTests/ConfigurationTests.swift new file mode 100644 index 00000000..2ca0c1dc --- /dev/null +++ b/Tests/IMAPCommandsTests/ConfigurationTests.swift @@ -0,0 +1,101 @@ +//===----------------------------------------------------------------------===// +// +// 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 Testing + +private enum ConfigurationTests { + @Test + static func parseNameOnly() throws { + #expect( + try IMAPConnection.Configuration(serverText: "mail.example.com", logging: .noLogging) + == IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 993, + useTLS: true, + logging: .noLogging + ) + ) + + #expect( + try IMAPConnection.Configuration(serverText: "mail.example.com:993", logging: .noLogging) + == IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 993, + useTLS: true, + logging: .noLogging + ) + ) + + #expect( + try IMAPConnection.Configuration(serverText: "mail.example.com:143", logging: .noLogging) + == IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 143, + useTLS: false, + logging: .noLogging + ) + ) + + #expect( + try IMAPConnection.Configuration(serverText: "mail.example.com:1000", logging: .noLogging) + == IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 1000, + useTLS: false, + logging: .noLogging + ) + ) + } + + // https://tools.ietf.org/html/rfc5092 + @Test + static func testParsingURL() throws { + #expect( + try IMAPConnection.Configuration(serverText: "imap://mail.example.com", logging: .noLogging) + == IMAPConnection.Configuration( + hostname: "mail.example.com", + port: 993, + useTLS: true, + logging: .noLogging + ) + ) + } + + /// Text that is neither a hostname (with optional port) nor an IMAP URL is rejected. + /// + /// Anything following the port is _not_ ignored: such text falls through to URL parsing, + /// which then fails because the scheme is not `imap`. + @Test( + arguments: [ + "", + "mail.example.com:143abc", + "mail.example.com:143:144", + "mail.example.com:65536", + "mail.example.com:", + "mail..example.com", + ".mail.example.com", + "mail.example.com.", + "-mail.example.com", + "mail.example.com-", + "mail.example.com/inbox", + "http://mail.example.com", + ] + ) + static func parsingInvalidServerText(_ text: String) throws { + #expect(throws: (any Error).self) { + try IMAPConnection.Configuration(serverText: text, logging: .noLogging) + } + } +} diff --git a/Tests/IMAPCommandsTests/ConnectionTestSupport.swift b/Tests/IMAPCommandsTests/ConnectionTestSupport.swift new file mode 100644 index 00000000..beaac3e3 --- /dev/null +++ b/Tests/IMAPCommandsTests/ConnectionTestSupport.swift @@ -0,0 +1,277 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import NIO +import Synchronization + +// MARK: - Shared state + +/// A `Sendable` reference wrapper around a `Mutex`. +/// +/// A `Mutex` is non-copyable, so a closure that uses one captures the *enclosing scope's* +/// binding by reference. Swift 6.4 accepts that for the `sending` closures +/// `TaskGroup.addTask` takes, but earlier compilers reject it as a potential data race — +/// even though the mutex is what makes the access safe in the first place. Boxing the mutex +/// in a class gives such a closure a copyable reference to capture instead. +final class LockedBox: Sendable { + private let storage: Mutex + + init(_ initialValue: Value) { + self.storage = Mutex(initialValue) + } + + @discardableResult + func withLock(_ body: (inout Value) throws -> Result) rethrows -> Result { + try self.storage.withLock { try body(&$0) } + } +} + +// MARK: - Timeout support + +/// A one-shot async gate. +/// +/// Used to race an operation against a timeout *without* structured `await`-ing the +/// operation task. If the operation stalls on a non-cancellable continuation (which is +/// exactly what the connection-lifecycle bugs cause), a structured `withTaskGroup` +/// timeout would itself stall on scope exit while awaiting the stuck child. This gate +/// lets a stalled operation surface as a deterministic test failure instead of freezing +/// the whole suite. +actor CompletionGate { + private var resolved: Bool? + private var waiters: [CheckedContinuation] = [] + + func resolve(_ value: Bool) { + guard resolved == nil else { return } + resolved = value + for w in waiters { + w.resume(returning: value) + } + waiters = [] + } + + func wait() async -> Bool { + if let resolved { return resolved } + // Waiting is cancellation-aware so that a caller which is itself timed out (e.g. + // by swift-testing's `.timeLimit`) can never be left parked here forever, which + // would stall the whole test process rather than fail a single test. + return await withTaskCancellationHandler { + await withCheckedContinuation { c in + // `onCancel` may have resolved the gate before the continuation was + // installed, so re-check instead of parking unconditionally. + if let resolved { + c.resume(returning: resolved) + } else { + waiters.append(c) + } + } + } onCancel: { + Task { await self.resolve(false) } + } + } +} + +/// Runs `operation` and returns `true` if it finished within `seconds`, `false` if it +/// timed out (i.e. stalled). +/// +/// The operation runs in an unstructured task. On timeout that task is cancelled and +/// abandoned — if it is stuck on a non-cancellable continuation it will leak, which is +/// acceptable for a bug-reproduction test that would otherwise stall forever. +/// +/// - Important: `seconds` is a *wall-clock* budget for detecting a deadlock, not a +/// performance assertion. The rest of the test suite runs in parallel on the same +/// cooperative thread pool, so on a busy or CPU-starved machine (a CI container with +/// few cores) these tasks can be left unscheduled for many seconds at a time. The +/// clock therefore only starts once `operation` actually begins running, and the +/// budget is deliberately generous: the operations under test need milliseconds of +/// work, so anything close to the budget is a stall, whereas a tight budget only +/// produces spurious failures. Keep the budget well below the enclosing `.timeLimit` +/// so this gate — and not the test harness — is what reports a stall. +func finishesWithoutStalling( + within seconds: Double = 60, + _ operation: @escaping @Sendable () async -> Void +) async -> Bool { + let gate = CompletionGate() + let started = CompletionGate() + let work = Task { + await started.resolve(true) + await operation() + await gate.resolve(true) + } + let timer = Task { + _ = await started.wait() + try? await Task.sleep(for: .seconds(seconds)) + await gate.resolve(false) + } + let finished = await gate.wait() + work.cancel() + timer.cancel() + return finished +} + +// MARK: - Loopback server + +/// A minimal TCP server on `127.0.0.1` used to exercise `IMAPConnection`'s lifecycle +/// without a real IMAP server. +/// +/// - Note: Binding a socket fails in sandboxed environments. These tests are intended +/// to be run manually where sockets are available. +final class LoopbackServer { + let channel: Channel + private let group: MultiThreadedEventLoopGroup + + private init(channel: Channel, group: MultiThreadedEventLoopGroup) { + self.channel = channel + self.group = group + } + + var port: UInt16 { + UInt16(channel.localAddress?.port ?? 0) + } + + /// Starts a server that sends an IMAP greeting on connect and then closes the + /// connection (a graceful EOF) as soon as the client sends its first command — + /// without ever sending a tagged response. + static func greetThenCloseOnFirstCommand() async throws -> LoopbackServer { + try await start { GreetThenCloseHandler() } + } + + /// Starts a server that sends an IMAP greeting on connect and then stays open, + /// ignoring anything the client sends and never replying. The connection only + /// closes when the client closes it. + static func greetThenStayOpen() async throws -> LoopbackServer { + try await start { GreetAndStayOpenHandler() } + } + + private static func start( + _ makeHandler: @escaping @Sendable () -> any ChannelInboundHandler + ) async throws -> LoopbackServer { + let group = MultiThreadedEventLoopGroup(numberOfThreads: 1) + let channel = try await ServerBootstrap(group: group) + .serverChannelOption(ChannelOptions.backlog, value: 16) + .serverChannelOption(ChannelOptions.socketOption(.so_reuseaddr), value: 1) + .childChannelInitializer { channel in + channel.eventLoop.makeCompletedFuture { + try channel.pipeline.syncOperations.addHandler(makeHandler()) + } + } + .bind(host: "127.0.0.1", port: 0) + .get() + return LoopbackServer(channel: channel, group: group) + } + + /// Synchronously tears the server down. Safe to call from a test's `defer`. + func shutdown() { + try? channel.close().wait() + try? group.syncShutdownGracefully() + } +} + +/// Writes an IMAP greeting on `channelActive`, then closes the connection on the first +/// inbound read (the client's first command), producing a graceful EOF for the client. +private final class GreetThenCloseHandler: ChannelInboundHandler { + typealias InboundIn = ByteBuffer + typealias OutboundOut = ByteBuffer + + func channelActive(context: ChannelHandlerContext) { + var buffer = context.channel.allocator.buffer(capacity: 64) + buffer.writeString("* OK [CAPABILITY IMAP4rev1] Loopback test server ready\r\n") + context.writeAndFlush(self.wrapOutboundOut(buffer), promise: nil) + context.fireChannelActive() + } + + func channelRead(context: ChannelHandlerContext, data: NIOAny) { + // The client has sent its first command. Close without replying so the client + // observes an end-of-stream while it is still awaiting the tagged response. + context.close(promise: nil) + } +} + +/// Writes an IMAP greeting on `channelActive`, then stays open, ignoring all inbound +/// data and never replying. +private final class GreetAndStayOpenHandler: ChannelInboundHandler { + typealias InboundIn = ByteBuffer + typealias OutboundOut = ByteBuffer + + func channelActive(context: ChannelHandlerContext) { + var buffer = context.channel.allocator.buffer(capacity: 64) + buffer.writeString("* OK [CAPABILITY IMAP4rev1] Loopback test server ready\r\n") + context.writeAndFlush(self.wrapOutboundOut(buffer), promise: nil) + context.fireChannelActive() + } + + func channelRead(context: ChannelHandlerContext, data: NIOAny) { + // Ignore everything the client sends; stay open until the client disconnects. + } +} + +// MARK: - Log capture + +/// Collects the log records written through the `RecordingLogHandler` it hands out. +/// +/// Log handlers are value types that get copied as a `Logger` is passed around and mutated, so +/// the records have to accumulate in shared storage behind a reference. +final class LogRecorder: Sendable { + struct Record: Sendable { + var level: Logger.Level + var message: String + /// The handler's own metadata merged with the metadata passed at the log site — that is, + /// what a real handler would render. + var metadata: Logger.Metadata + } + + private let storage = Mutex<[Record]>([]) + + /// A handler that appends everything it is given to this recorder. + var handler: RecordingLogHandler { + RecordingLogHandler(recorder: self) + } + + var records: [Record] { + storage.withLock { $0 } + } + + /// The records whose message is exactly `message`. + func records(message: String) -> [Record] { + records.filter { $0.message == message } + } + + func append(_ record: Record) { + storage.withLock { $0.append(record) } + } +} + +/// A `LogHandler` that records into a ``LogRecorder`` instead of writing anywhere. +struct RecordingLogHandler: LogHandler { + let recorder: LogRecorder + var metadata: Logger.Metadata = [:] + var logLevel: Logger.Level = .trace + + subscript(metadataKey key: String) -> Logger.Metadata.Value? { + get { metadata[key] } + set { metadata[key] = newValue } + } + + func log(event: LogEvent) { + // Merging is the handler's job in swift-log, so do it here: it is the only way the + // metadata bound onto the logger (`imap.connection`) shows up in a record. + var merged = self.metadata + for (key, value) in event.metadata ?? [:] { + merged[key] = value + } + recorder.append( + LogRecorder.Record(level: event.level, message: "\(event.message)", metadata: merged) + ) + } +} diff --git a/Tests/IMAPCommandsTests/CredentialTests.swift b/Tests/IMAPCommandsTests/CredentialTests.swift new file mode 100644 index 00000000..c11c96d5 --- /dev/null +++ b/Tests/IMAPCommandsTests/CredentialTests.swift @@ -0,0 +1,177 @@ +//===----------------------------------------------------------------------===// +// +// 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 Foundation +import NIOIMAP +import Testing + +@Suite private enum CredentialTests { + @Test static func parsingURL() throws { + #expect( + try IMAPCredential(url: "imap://foo:bar@mail.example.com", sasl: nil, username: nil) + == IMAPCredential.username("foo", password: "bar") + ) + } + + @Test static func parsingUsername() throws { + #expect( + try IMAPCredential(url: nil, sasl: nil, username: "foo:bar") + == IMAPCredential.username("foo", password: "bar") + ) + + #expect( + try IMAPCredential(url: "imap://mail.example.com", sasl: nil, username: "foo:bar") + == IMAPCredential.username("foo", password: "bar") + ) + } + + @Test static func parsingSASL_stringsSeparatedBySpace() throws { + #expect( + try IMAPCredential(url: nil, sasl: "EXTERNAL:11485857054 18570541485 asbbc/asdfa", username: nil) + == IMAPCredential.sasl( + mechanism: AuthenticationMechanism("EXTERNAL")!, + response: Data(base64Encoded: "MTE0ODU4NTcwNTQAMTg1NzA1NDE0ODUAYXNiYmMvYXNkZmE=")! + ) + ) + + #expect( + try IMAPCredential(url: nil, sasl: "external:11485857054 18570541485 asbbc/asdfa", username: nil) + == IMAPCredential.sasl( + mechanism: AuthenticationMechanism("EXTERNAL")!, + response: Data(base64Encoded: "MTE0ODU4NTcwNTQAMTg1NzA1NDE0ODUAYXNiYmMvYXNkZmE=")! + ) + ) + + #expect( + try IMAPCredential(url: nil, sasl: "plain:foo bar", username: nil) + == IMAPCredential.sasl(mechanism: .plain, response: Data(base64Encoded: "Zm9vAGJhcg==")!) + ) + + #expect( + try IMAPCredential(url: "imap://mail.example.com", sasl: "plain:foo bar", username: nil) + == IMAPCredential.sasl(mechanism: .plain, response: Data(base64Encoded: "Zm9vAGJhcg==")!) + ) + } + + @Test static func parsingSASL_singleBase64() throws { + #expect( + try IMAPCredential(url: nil, sasl: "PLAIN:dGVzdAB0ZXN0AHRlc3Q=", username: nil) + == IMAPCredential.sasl(mechanism: .plain, response: Data(base64Encoded: "dGVzdAB0ZXN0AHRlc3Q=")!) + ) + + // Not valid base64 (the length is not a multiple of 4), and hence a single part: + #expect( + try IMAPCredential(url: nil, sasl: "PLAIN:foo", username: nil) + == IMAPCredential.sasl(mechanism: .plain, response: Data("foo".utf8)) + ) + } + + /// An empty response is valid and results in a zero byte response. + @Test static func parsingSASL_emptyResponse() throws { + #expect( + try IMAPCredential(url: nil, sasl: "PLAIN:", username: nil) + == IMAPCredential.sasl(mechanism: .plain, response: Data()) + ) + } + + /// Mechanism names may contain digits, `-` and `_`, not just letters. + /// + /// See [RFC 4422 section 3.1](https://datatracker.ietf.org/doc/html/rfc4422#section-3.1). + @Test( + arguments: [ + "XOAUTH2", + "SCRAM-SHA-256", + "CRAM-MD5", + "DIGEST-MD5", + "X_SOMETHING", + ] + ) + static func parsingSASL_mechanismName(_ name: String) throws { + #expect( + try IMAPCredential(url: nil, sasl: "\(name):foo bar", username: nil) + == IMAPCredential.sasl( + mechanism: AuthenticationMechanism(name)!, + response: Data(base64Encoded: "Zm9vAGJhcg==")! + ) + ) + + // The name is normalized to uppercase. + #expect( + try IMAPCredential(url: nil, sasl: "\(name.lowercased()):foo bar", username: nil) + == IMAPCredential.sasl( + mechanism: AuthenticationMechanism(name)!, + response: Data(base64Encoded: "Zm9vAGJhcg==")! + ) + ) + } + + @Test( + arguments: [ + "", + "PLAIN", + ":foo bar", + "PL.AIN:foo bar", + "PLAIN: foo bar", + "PLAIN:\tfoo bar", + ] + ) + static func parsingInvalidSASL(_ text: String) throws { + #expect(throws: (any Error).self) { + try IMAPCredential(url: nil, sasl: text, username: nil) + } + } + + @Test( + arguments: [ + "", + "foo", + "foo:", + ":bar", + "foo:bar:baz", + ] + ) + static func parsingInvalidUsername(_ text: String) throws { + #expect(throws: (any Error).self) { + try IMAPCredential(url: nil, sasl: nil, username: text) + } + } + + @Test static func multipleUsername() throws { + #expect(throws: (any Error).self) { + try IMAPCredential(url: "imap://foo:bar@mail.example.com", sasl: nil, username: "foo:bar") + } + } + + @Test static func saslAndUsername() throws { + #expect(throws: (any Error).self) { + try IMAPCredential(url: "imap://foo:bar@mail.example.com", sasl: "plain:foo bar", username: nil) + } + #expect(throws: (any Error).self) { + try IMAPCredential(url: nil, sasl: "plain:foo bar", username: "foo:bar") + } + } + + @Test static func descriptionRedactsSecret() throws { + // The password must not appear in the description. + let userCredential = IMAPCredential.username("foo", password: "s3cr3t") + #expect(!userCredential.description.contains("s3cr3t")) + #expect(userCredential.description == "foo:[6 bytes]") + + // The SASL response must not be leaked (not even base64-encoded). + let sasl = IMAPCredential.sasl(mechanism: .plain, response: Data(base64Encoded: "Zm9vAGJhcg==")!) + #expect(!sasl.description.contains("Zm9vAGJhcg==")) + #expect(sasl.description == "SASL PLAIN [7 bytes]") + } +} diff --git a/Tests/IMAPCommandsTests/ErrorSurfaceTests.swift b/Tests/IMAPCommandsTests/ErrorSurfaceTests.swift new file mode 100644 index 00000000..c36ed08a --- /dev/null +++ b/Tests/IMAPCommandsTests/ErrorSurfaceTests.swift @@ -0,0 +1,128 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIOIMAP +import Testing + +/// The public error surface. +/// +/// Imports `IMAPCommands` without `@testable` on purpose: an error a caller cannot name is the +/// defect these tests prevent. +@Suite private enum ErrorSurfaceTests { + + // MARK: - Typed throws + + /// Binding `.state` with no cast only compiles under typed throws. + @Test static func taggedResponseFailureIsTyped() { + let response = TaggedResponse(tag: "A1", state: .no(ResponseText(text: "nope"))) + do { + try response.checkOK() + Issue.record("NO should not pass checkOK()") + } catch { + #expect(error.state == .no(ResponseText(text: "nope"))) + } + } + + @Test static func untaggedStatusFailureIsTyped() { + let status = UntaggedStatus.bad(ResponseText(text: "bad")) + do { + _ = try status.getOK() + Issue.record("BAD should not pass getOK()") + } catch { + #expect(error.status == .bad(ResponseText(text: "bad"))) + } + } + + @Test static func configurationParseFailureIsTyped() { + do { + _ = try IMAPConnection.Configuration(serverText: "not a server", logging: .noLogging) + Issue.record("'not a server' should not parse") + } catch { + #expect(error.description.contains("not a server")) + } + } + + @Test( + arguments: [ + (nil, nil, nil, IMAPCredential.ParseError.noCredentials), + ("imap://u:p@example.com", nil, "u:p", .conflictingCredentials), + (nil, "PLAIN", nil, .unableToParseSASL), + (nil, nil, "no-colon", .unableToParseUsernamePassword), + ] as [(String?, String?, String?, IMAPCredential.ParseError)] + ) + static func credentialParseFailureIsTyped( + url: String?, + sasl: String?, + username: String?, + expected: IMAPCredential.ParseError + ) { + do { + _ = try IMAPCredential(url: url, sasl: sasl, username: username) + Issue.record("Expected \(expected)") + } catch { + #expect(error == expected) + } + } + + // MARK: - Nameability + + /// Every case constructible and matchable from outside the module. + @Test static func everyCaseIsPubliclyMatchable() { + let errors: [IMAPConnection.Error] = [ + .connectionClosed, + .connectionFailed(TestFailure()), + .unexpectedGreeting(.untagged(.id([:]))), + .missingTaggedResponse, + .unknownTag("A7"), + ] + + for error in errors { + switch error { + case .connectionClosed, .missingTaggedResponse: + break + case .connectionFailed(let underlying): + #expect(underlying is TestFailure) + case .unexpectedGreeting(let response): + #expect(response == .untagged(.id([:]))) + case .unknownTag(let tag): + #expect(tag == "A7") + } + } + } + + @Test static func descriptionsAreHumanReadable() { + #expect("\(IMAPConnection.Error.connectionClosed)" == "The connection was closed.") + #expect("\(IMAPConnection.Error.unknownTag("A7"))".contains("A7")) + #expect("\(IMAPConnection.Error.connectionFailed(TestFailure()))".contains("TestFailure")) + } + + /// Catching one case out of an untyped `throws` — the idiom the docs promise. + @Test static func aSingleCaseCanBeCaughtFromUntypedThrows() { + func failsUntyped() throws { + throw IMAPConnection.Error.connectionClosed + } + + do { + try failsUntyped() + Issue.record("Expected a throw") + } catch IMAPConnection.Error.connectionClosed { + // Expected. + } catch { + Issue.record("Expected .connectionClosed, got \(error)") + } + } + + private struct TestFailure: Swift.Error {} +} diff --git a/Tests/IMAPCommandsTests/IMAPConnectionCompositionTests.swift b/Tests/IMAPCommandsTests/IMAPConnectionCompositionTests.swift new file mode 100644 index 00000000..4762bc98 --- /dev/null +++ b/Tests/IMAPCommandsTests/IMAPConnectionCompositionTests.swift @@ -0,0 +1,263 @@ +//===----------------------------------------------------------------------===// +// +// 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 +import NIO +import NIOIMAP +import Testing + +/// Pins the composability contract of `IMAPConnection`'s closure-based API: none of the +/// closures are `@Sendable` or `@escaping`, and they are all `nonisolated(nonsending)`, so they +/// run in the caller's isolation domain. +/// +/// These are primarily _compile-time_ tests. Each one passes a closure that captures and +/// mutates non-`Sendable` state — a plain local `var`, or a class instance isolated to the +/// caller's actor — which only type-checks if the closure is neither `@Sendable` nor +/// `@escaping` and runs in the caller's isolation domain. +/// +/// They connect to port 1, which is closed, so the connection always fails and the bodies +/// never run: the assertion is that the API surface compiles and that the connection +/// failure surfaces as a thrown error. +@Suite("IMAPConnection API composition") +struct IMAPConnectionCompositionTests { + + /// Not `Sendable`, and only usable from the isolation domain it was created in. + final class Recorder { + var lines: [String] = [] + + func record(_ line: String) { + lines.append(line) + } + } + + static var unreachableConfiguration: IMAPConnection.Configuration { + // Port 1 is (essentially) always closed on loopback, so the connect is refused. + IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: 1, + useTLS: false, + logging: .noLogging + ) + } + + static let mailbox = MailboxName(Array("INBOX".utf8)) + + /// The whole API surface, exercised from a `@MainActor` context with a non-`Sendable` + /// `Recorder` shared between every closure. + @MainActor + @Test(.timeLimit(.minutes(1))) + func mainActorIsolatedClosuresCanUseNonSendableState() async throws { + let recorder = Recorder() + + await #expect(throws: (any Swift.Error).self) { + try await IMAPConnection.withConnection( + configuration: Self.unreachableConfiguration + ) { greeting, connection in + recorder.record("greeting: \(greeting.status)") + + try await connection.send(.noop) { tag, responses in + recorder.record("noop: \(tag)") + _ = try await responses.forEach { response in + recorder.record("response: \(response)") + } + } + + try await connection.sendIdle { tag, responses in + recorder.record("idle: \(tag)") + for try await response in responses { + recorder.record("idle response: \(response)") + } + } + + try await connection.sendAuthenticate( + mechanism: .plain, + initialResponse: nil + ) { tag, _, writer in + recorder.record("authenticate: \(tag)") + try await writer.writeContinuation(ByteBuffer(string: "secret")) + } + + _ = try await connection.append(to: Self.mailbox) { tag, responses, writer in + recorder.record("append: \(tag)") + try await writer.write( + message: AppendMessage( + options: AppendOptions(), + data: AppendData(byteCount: 3) + ) + ) { messageWriter in + recorder.record("message bytes") + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + try await writer.catenate(options: AppendOptions()) { catenateWriter in + recorder.record("catenate") + try await catenateWriter.writeURL(ByteBuffer(string: "/INBOX;UID=1")) + } + // Completing the command explicitly is what makes waiting for its tagged + // response inside the closure possible. + try await writer.finish() + return try await responses.waitForCompletion() + } + + // The two-closure convenience, with the same non-`Sendable` recorder. + _ = try await connection.append( + to: Self.mailbox, + writing: { tag, writer in + recorder.record("append: \(tag)") + try await writer.write( + message: AppendMessage( + options: AppendOptions(), + data: AppendData(byteCount: 3) + ) + ) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + }, + reading: { _, responses in + try await responses.waitForCompletion() + } + ) + } + } + + // The connection never came up, so nothing was recorded — the point of the test is + // that all of the above type-checks against `Recorder`, which is not `Sendable`. + #expect(recorder.lines.isEmpty) + } + + /// The same, from a nonisolated context, capturing a mutable local instead. + @Test(.timeLimit(.minutes(1))) + func nonisolatedClosuresCanMutateCapturedLocals() async throws { + var steps: [String] = [] + + await #expect(throws: (any Swift.Error).self) { + try await IMAPConnection.withConnection( + configuration: Self.unreachableConfiguration + ) { _, connection in + steps.append("body") + try await connection.send(.noop) { _, responses in + steps.append("noop") + _ = try await responses.waitForCompletion() + } + } + } + + #expect(steps.isEmpty) + } + + /// Closures return their results into the caller's isolation domain, so a non-`Sendable` + /// result is fine. + @Test(.timeLimit(.minutes(1))) + func closuresCanReturnNonSendableResults() async throws { + await #expect(throws: (any Swift.Error).self) { + let recorder = try await IMAPConnection.withConnection( + configuration: Self.unreachableConfiguration + ) { _, connection in + try await connection.send(.noop) { _, responses in + let recorder = Recorder() + _ = try await responses.waitForCompletion() + return recorder + } + } + // Never reached: the connection always fails. + #expect(recorder.lines.isEmpty) + } + } + + /// And from a custom actor, whose isolation the closures pick up. + @Test(.timeLimit(.minutes(1))) + func actorIsolatedClosuresCanUseActorState() async throws { + actor Session { + let recorder = Recorder() + + func run() async throws { + try await IMAPConnection.withConnection( + configuration: IMAPConnectionCompositionTests.unreachableConfiguration + ) { _, connection in + // `recorder` is isolated to `self`, and so is this closure. + recorder.record("body") + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + } + } + } + + let session = Session() + await #expect(throws: (any Swift.Error).self) { + try await session.run() + } + } + + /// A `body` that wants concurrency asks for it explicitly — the API doesn't impose it. + @Test(.timeLimit(.minutes(1))) + func bodyCanPipelineCommandsInATaskGroup() async throws { + await #expect(throws: (any Swift.Error).self) { + try await IMAPConnection.withConnection( + configuration: Self.unreachableConfiguration + ) { _, connection in + try await withThrowingTaskGroup(of: TaggedResponse.self) { group in + for command in [Command.noop, .capability] { + group.addTask { + try await connection.send(command) { _, responses in + try await responses.waitForCompletion() + } + } + } + return try await group.reduce(into: []) { $0.append($1) } + } + } + } + } + + /// The same for `append`: reading the command's responses _while_ writing it is the caller's + /// own task group, with the writer staying in the parent task. The `ResponseStream` is + /// `Sendable`, the `AppendWriter` is not — and being `inout` it can only be captured by a + /// non-escaping closure, so this is the one shape that compiles. + @Test(.timeLimit(.minutes(1))) + func appendBodyCanReadResponsesWhileWriting() async throws { + // What crosses into a child task still has to be `Sendable` — only the closures the + // connection itself calls are relieved of that. + let responseCount = LockedBox(0) + + await #expect(throws: (any Swift.Error).self) { + try await IMAPConnection.withConnection( + configuration: Self.unreachableConfiguration + ) { _, connection in + try await connection.append(to: Self.mailbox) { _, responses, writer in + try await withThrowingTaskGroup(of: Void.self) { group in + group.addTask { + for try await _ in responses { + responseCount.withLock { $0 += 1 } + } + } + try await writer.write( + message: AppendMessage( + options: AppendOptions(), + data: AppendData(byteCount: 3) + ) + ) { messageWriter in + try await messageWriter.write(messageBytes: ByteBuffer(string: "abc")) + } + // Completing the command lets the reader see the tagged response and + // finish, so the group can be awaited here. + try await writer.finish() + try await group.waitForAll() + } + } + } + } + + #expect(responseCount.withLock { $0 } == 0) + } +} diff --git a/Tests/IMAPCommandsTests/IMAPConnectionLifecycleTests.swift b/Tests/IMAPCommandsTests/IMAPConnectionLifecycleTests.swift new file mode 100644 index 00000000..68695dcd --- /dev/null +++ b/Tests/IMAPCommandsTests/IMAPConnectionLifecycleTests.swift @@ -0,0 +1,395 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import NIO +import NIOIMAP +import Synchronization +import Testing + +/// Regression tests for `IMAPConnection`'s connection lifecycle. +/// +/// - Important: These open real sockets, so they cannot run in a sandboxed +/// environment (socket `bind`/`connect` fail with errno 1). Run them manually. +@Suite("IMAPConnection lifecycle") +enum IMAPConnectionLifecycleTests { + + /// Bug #1: When the server closes the connection gracefully (EOF) while a command + /// is in flight, the inbound read loop exits without calling `close()`, so the + /// outbound task stays parked and the in-flight command's response stream is never + /// finished. `withConnection` then stalls forever instead of failing the command. + @Test(.timeLimit(.minutes(3))) + static func gracefulEOFWhileAwaitingResponseDoesNotStall() async throws { + let server = try await LoopbackServer.greetThenCloseOnFirstCommand() + defer { server.shutdown() } + + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: server.port, + useTLS: false, + logging: .noLogging + ) + + let outcome = Mutex("did-not-run") + let thrown = Mutex(nil) + let finished = await finishesWithoutStalling { + do { + try await IMAPConnection.withConnection(configuration: configuration) { _, connection in + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + } + outcome.withLock { $0 = "returned" } + } catch { + outcome.withLock { $0 = "threw" } + thrown.withLock { $0 = error as? IMAPConnection.Error } + } + } + + #expect( + finished, + "withConnection stalled after the server closed the connection (graceful EOF) while a command was awaiting its tagged response." + ) + // Once fixed, the in-flight command fails with a connection-closed error, so + // `withConnection` propagates that error rather than completing successfully. + #expect( + outcome.withLock { $0 } == "threw", + "The in-flight command should fail with a connection-closed error." + ) + // And nameable: a public case, not an internal struct you can only print. + let error = thrown.withLock { $0 } + guard case .connectionClosed = error else { + Issue.record("Expected IMAPConnection.Error.connectionClosed, got \(error as Any).") + return + } + } + + /// Bug #2: When the channel fails to open (e.g. connection refused), `run()` + /// propagates the error before `close()` is ever called, so the greeting + /// continuation the `body` task is parked on is never resumed. Because the greeting + /// getter is not cancellation-aware, the structured task group can never finish and + /// `withConnection` stalls instead of throwing the connection error. + @Test(.timeLimit(.minutes(3))) + static func connectFailureThrowsInsteadOfStalling() async throws { + // Port 1 is (essentially) always closed on loopback, so the connect is refused. + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: 1, + useTLS: false, + logging: .noLogging + ) + + let outcome = Mutex("did-not-run") + let thrown = Mutex(nil) + let finished = await finishesWithoutStalling { + do { + try await IMAPConnection.withConnection(configuration: configuration) { _, _ in + // Should never get here — the connection can't be established. + } + outcome.withLock { $0 = "returned" } + } catch { + outcome.withLock { $0 = "threw" } + thrown.withLock { $0 = error as? IMAPConnection.Error } + } + } + + #expect( + finished, + "withConnection stalled when the connection could not be established, instead of throwing the connection error." + ) + #expect( + outcome.withLock { $0 } == "threw", + "Failing to connect should surface as a thrown error from withConnection." + ) + // A refused connect is a failure, not an orderly close; the NIO error stays reachable. + let error = thrown.withLock { $0 } + guard case .connectionFailed = error else { + Issue.record("Expected IMAPConnection.Error.connectionFailed, got \(error as Any).") + return + } + } + + /// When the `AUTHENTICATE` handler throws mid-exchange there is no way to cleanly + /// abort the exchange, so `sendAuthenticate` closes the connection. A subsequent + /// command must then fail fast rather than write on a half-authenticated connection. + @Test(.timeLimit(.minutes(3))) + static func authenticateHandlerThrowClosesConnection() async throws { + let server = try await LoopbackServer.greetThenStayOpen() + defer { server.shutdown() } + + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: server.port, + useTLS: false, + logging: .noLogging + ) + + struct HandlerError: Swift.Error {} + + let handlerThrew = Mutex(false) + let secondCommandFailed = Mutex(false) + + let finished = await finishesWithoutStalling { + do { + try await IMAPConnection.withConnection(configuration: configuration) { _, connection in + do { + try await connection.sendAuthenticate( + mechanism: .plain, + initialResponse: nil + ) { _, _, _ -> Void in + throw HandlerError() + } + } catch is HandlerError { + handlerThrew.withLock { $0 = true } + } + // sendAuthenticate should have closed the connection, so a follow-up + // command must fail fast rather than run on a half-authenticated + // connection. + do { + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + } catch { + secondCommandFailed.withLock { $0 = true } + } + } + } catch { + // withConnection may also rethrow once the connection is closed. + } + } + + #expect(finished, "withConnection stalled after the AUTHENTICATE handler threw.") + #expect(handlerThrew.withLock { $0 }, "The AUTHENTICATE handler error should propagate.") + #expect( + secondCommandFailed.withLock { $0 }, + "After the AUTHENTICATE handler threw, sendAuthenticate should have closed the connection so a subsequent command fails." + ) + } + + /// A failing connection must not cancel the `body`. The failure has to surface through + /// the connection instead: the in-flight command fails, and so does every command after + /// it — but `body` keeps running and its result is what `withConnection` returns. + @Test(.timeLimit(.minutes(3))) + static func connectionFailureSurfacesThroughTheConnectionRatherThanCancellingTheBody() async throws { + let server = try await LoopbackServer.greetThenCloseOnFirstCommand() + defer { server.shutdown() } + + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: server.port, + useTLS: false, + logging: .noLogging + ) + + let outcome = Mutex("did-not-run") + let finished = await finishesWithoutStalling { + do { + // Note that `steps` is a plain, mutable local: the body is neither + // `@Sendable` nor `@escaping`, so it can capture non-`Sendable` state. + var steps: [String] = [] + let result = try await IMAPConnection.withConnection(configuration: configuration) { _, connection in + do { + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + steps.append("first-succeeded") + } catch { + steps.append("first-failed") + } + // The connection failed, but this task was not cancelled by it. + steps.append(Task.isCancelled ? "cancelled" : "still-running") + // Interacting with the failed connection keeps failing. + do { + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + steps.append("second-succeeded") + } catch { + steps.append("second-failed") + } + return steps.joined(separator: ",") + } + outcome.withLock { $0 = result } + } catch { + outcome.withLock { $0 = "threw: \(error)" } + } + } + + #expect(finished, "withConnection stalled after the server closed the connection.") + #expect( + outcome.withLock { $0 } == "first-failed,still-running,second-failed", + "The connection failure should surface through the connection, not as cancellation of the body." + ) + } + + /// A closure that throws part-way through an `APPEND` leaves the command unfinished, and + /// the protocol offers no way to abort it. `append` therefore closes the connection, so + /// that a subsequent command fails instead of being written into the middle of the + /// half-sent `APPEND`. + @Test(.timeLimit(.minutes(3))) + static func appendClosureThrowClosesConnection() async throws { + let server = try await LoopbackServer.greetThenStayOpen() + defer { server.shutdown() } + + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: server.port, + useTLS: false, + logging: .noLogging + ) + + struct WriterError: Swift.Error {} + + let outcome = Mutex("did-not-run") + let finished = await finishesWithoutStalling { + do { + var steps: [String] = [] + let result = try await IMAPConnection.withConnection(configuration: configuration) { _, connection in + do { + _ = try await connection.append(to: MailboxName(Array("INBOX".utf8))) { _, _, _ in + throw WriterError() + } + steps.append("append-succeeded") + } catch is WriterError { + steps.append("append-threw") + } + do { + try await connection.send(.noop) { _, responses in + _ = try await responses.waitForCompletion() + } + steps.append("noop-succeeded") + } catch { + steps.append("noop-failed") + } + return steps.joined(separator: ",") + } + outcome.withLock { $0 = result } + } catch { + outcome.withLock { $0 = "threw: \(error)" } + } + } + + #expect(finished, "withConnection stalled after the APPEND closure threw.") + #expect( + outcome.withLock { $0 } == "append-threw,noop-failed", + "An aborted APPEND should propagate its error and close the connection." + ) + } + + /// Command handlers run with the command's tag merged into the task-local logger, so a + /// handler can log through `Logger.current` and have its lines attributed to the command + /// without the tag being threaded through by hand. The logger the connection was created + /// in the scope of has to be the base that tag is merged onto. + @Test(.timeLimit(.minutes(3))) + static func commandHandlersSeeTheCommandTagInTheTaskLocalLogger() async throws { + let server = try await LoopbackServer.greetThenStayOpen() + defer { server.shutdown() } + + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: server.port, + useTLS: false, + logging: .noLogging + ) + + /// What the handler saw of the logger that was current while it ran. + struct Observation: Sendable { + var tag: String + var tagMetadata: String? + var connectionMetadata: String? + var label: String + var enclosingMetadata: String? + } + + let observed = Mutex(nil) + + let finished = await finishesWithoutStalling { + var outer = Logger(label: "test.outer") + outer[metadataKey: "test.scope"] = "outer" + + _ = await withLogger(outer) { _ in + // The connection fails once the body returns; the handler has already run. + try? await IMAPConnection.withConnection(configuration: configuration) { _, connection in + // The server never replies, so the handler must not wait for completion. + try await connection.send(.noop) { tag, _ in + let current = Logger.current + observed.withLock { + $0 = Observation( + tag: "\(tag)", + tagMetadata: current[metadataKey: "imap.tag"].map { "\($0)" }, + connectionMetadata: current[metadataKey: "imap.connection"].map { "\($0)" }, + label: current.label, + enclosingMetadata: current[metadataKey: "test.scope"].map { "\($0)" } + ) + } + } + } + } + } + + #expect(finished, "The command handler stalled.") + guard let seen = observed.withLock({ $0 }) else { + Issue.record("The command handler did not run.") + return + } + // The tag the handler was handed is the one bound as metadata. + #expect( + seen.tagMetadata == seen.tag, + "The handler's `imap.tag` metadata should be the tag it was given." + ) + // A tag only identifies a command together with the connection it belongs to. + #expect(seen.connectionMetadata != nil, "The handler should also see `imap.connection`.") + // The tag is *merged onto* the enclosing logger rather than replacing it. + #expect(seen.label == "test.outer", "The enclosing logger should be the base.") + #expect(seen.enclosingMetadata == "outer", "Enclosing metadata should be preserved.") + } + + /// The connection logs its own diagnostics to the logger that was current when it was + /// created — not to whatever `withLogger` scope happens to be active at the log site — and + /// tags them so that lines from concurrent connections can be told apart. + @Test(.timeLimit(.minutes(3))) + static func connectionDiagnosticsGoToTheLoggerCapturedAtCreation() async throws { + // Port 1 is (essentially) always closed on loopback, so this needs no server: the + // connect is refused, the greeting fails, and `withConnection` logs on its way out. + let configuration = IMAPConnection.Configuration( + hostname: "127.0.0.1", + port: 1, + useTLS: false, + logging: .noLogging + ) + + let recorder = LogRecorder() + let finished = await finishesWithoutStalling { + // Replaces the handler and level of the current logger, which needs no + // `LoggingSystem.bootstrap` — that is global state a test cannot own. + _ = await withLogger(logLevel: .trace, handler: recorder.handler) { _ in + try? await IMAPConnection.withConnection(configuration: configuration) { _, _ in + Issue.record("The body should not run: the connection cannot be established.") + } + } + } + + #expect(finished, "withConnection stalled.") + let closing = recorder.records(message: "Closing connection after body threw") + #expect(closing.count == 1, "Expected one closing diagnostic, got: \(recorder.records)") + guard let record = closing.first else { return } + #expect(record.level == .debug, "Lifecycle diagnostics belong at `.debug`.") + #expect(record.metadata["error"] != nil, "The diagnostic should say what went wrong.") + #expect( + record.metadata["imap.connection"] != nil, + "Connection diagnostics should identify their connection: \(record.metadata)" + ) + } +} diff --git a/Tests/IMAPCommandsTests/LoggerMetadataTests.swift b/Tests/IMAPCommandsTests/LoggerMetadataTests.swift new file mode 100644 index 00000000..92b906be --- /dev/null +++ b/Tests/IMAPCommandsTests/LoggerMetadataTests.swift @@ -0,0 +1,86 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import Testing + +/// Pins the logger metadata `IMAPConnection` binds around command handlers. +/// +/// These need no socket. The end-to-end wiring — that a command handler really does run inside +/// this scope — is covered for `send` only, by +/// `IMAPConnectionLifecycleTests.commandHandlersSeeTheCommandTagInTheTaskLocalLogger()`, which +/// needs a real socket. `sendIdle`, `sendAuthenticate` and `append` bind the same metadata at +/// their handler call sites, but that is not covered by a test. +@Suite("Logger metadata") +struct LoggerMetadataTests { + + /// The key is part of what users see in their own logs, so it is namespaced and stable. + @Test + func tagMetadataUsesANamespacedKey() { + #expect(IMAPConnection.Tag.first.loggerMetadata == ["imap.tag": "A1"]) + #expect( + IMAPConnection.Tag.first.makeNext().loggerMetadata == ["imap.tag": "A2"], + "The metadata has to carry the tag as it goes over the wire." + ) + } + + /// The tag is *merged onto* whatever logger the caller has bound: the handler keeps the + /// caller's log level, handler, and metadata, and just gains `imap.tag`. + @Test + func tagMetadataIsLayeredOntoTheCallersLogger() async { + var outer = Logger(label: "test.outer") + outer.logLevel = .trace + outer[metadataKey: "test.scope"] = "outer" + + let observed: (label: String, tag: String?, scope: String?, level: Logger.Level) = + await withLogger(outer) { _ in + await withLogger(mergingMetadata: IMAPConnection.Tag.first.loggerMetadata) { _ in + // Suspend inside the scope, as a real handler does: this both selects the + // async `withLogger` overload the library uses and checks that the binding + // survives a suspension point. + await Task.yield() + let current = Logger.current + return ( + current.label, + current[metadataKey: "imap.tag"].map { "\($0)" }, + current[metadataKey: "test.scope"].map { "\($0)" }, + current.logLevel + ) + } + } + + #expect(observed.tag == "A1") + #expect(observed.label == "test.outer", "Merging must not replace the caller's logger.") + #expect(observed.scope == "outer", "The caller's metadata must survive the merge.") + #expect(observed.level == .trace, "The caller's log level must survive the merge.") + } + + /// Nothing leaks out of the scope: the tag is gone once the handler returns, so a second + /// command cannot inherit the first one's tag. + @Test + func tagMetadataDoesNotOutliveItsScope() async { + let outer = Logger(label: "test.outer") + + let after = await withLogger(outer) { _ in + await withLogger(mergingMetadata: IMAPConnection.Tag.first.loggerMetadata) { _ in + await Task.yield() + #expect(Logger.current[metadataKey: "imap.tag"] != nil) + } + return Logger.current[metadataKey: "imap.tag"] + } + + #expect(after == nil) + } +} diff --git a/Tests/IMAPCommandsTests/OutboundQueueCloseDuringAppendTests.swift b/Tests/IMAPCommandsTests/OutboundQueueCloseDuringAppendTests.swift new file mode 100644 index 00000000..285cdc37 --- /dev/null +++ b/Tests/IMAPCommandsTests/OutboundQueueCloseDuringAppendTests.swift @@ -0,0 +1,78 @@ +//===----------------------------------------------------------------------===// +// +// 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 NIO +import NIOIMAP +import Testing + +@Suite("Outbound Queue — close during APPEND") +enum OutboundQueueCloseDuringAppendTests { + + /// Bug #3: While an `APPEND` is in flight, regular writes are held in + /// `Append.pending`. `close()` only closes the append's inner queue and leaves + /// `pending` untouched, so any continuation parked there is orphaned. If the + /// in-flight append never returns (so `finishAppend()` never drains `pending`), the + /// parked write stalls forever instead of failing when the connection is closed. + @Test(.timeLimit(.minutes(3))) + static func closeResumesWritesParkedDuringAppend() async throws { + let sut = OutboundQueue() + + let enteredAppend = CompletionGate() // resolves once we're in `.runningAppend` + let holdAppend = CompletionGate() // never resolved until cleanup: holds the append open + let writeFinished = CompletionGate() // resolves when the parked write returns/throws + + // Hold an APPEND open. This keeps the queue in `.runningAppend`, so + // `finishAppend()` (which would drain `pending`) never runs until we release it. + let holder = Task { + try? await sut.withAppendWriter { _ in + await enteredAppend.resolve(true) + _ = await holdAppend.wait() + } + } + _ = await enteredAppend.wait() + + // Issue a regular write. Since we're in `.runningAppend`, it parks in `pending`. + let writer = Task { + _ = try? await sut.write([TaggedCommand(tag: "A", command: .noop)]) + await writeFinished.resolve(true) + } + + // Give the write a moment to park in `pending` before we close. + try await Task.sleep(for: .milliseconds(200)) + + // Tear the connection down. A correct `close()` must resume everything parked + // in `pending`, not wait for the (possibly stuck) in-flight append to finish. + sut.close() + + // The parked write must now complete; if it stalls, the timer resolves `false`. + // The budget is generous on purpose — see `finishesWithoutStalling(within:_:)`. + let timer = Task { + try? await Task.sleep(for: .seconds(60)) + await writeFinished.resolve(false) + } + let finished = await writeFinished.wait() + timer.cancel() + + // Cleanup: release the holder so no tasks leak once the assertion is recorded. + await holdAppend.resolve(true) + _ = await holder.value + writer.cancel() + + #expect( + finished, + "close() during an in-flight APPEND must resume writes parked in `pending`, not orphan them." + ) + } +} diff --git a/Tests/IMAPCommandsTests/OutboundQueueTests.swift b/Tests/IMAPCommandsTests/OutboundQueueTests.swift new file mode 100644 index 00000000..244c703f --- /dev/null +++ b/Tests/IMAPCommandsTests/OutboundQueueTests.swift @@ -0,0 +1,70 @@ +//===----------------------------------------------------------------------===// +// +// 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 Testing +import NIO +import NIOIMAP +import Synchronization + +@Suite("Outbound Queue") +enum OutboundQueueTests { + @Test(.timeLimit(.minutes(1))) + static func simpleRoundTrip() async throws { + let (outbound, sink) = NIOAsyncChannelOutboundWriter.makeTestingWriter() + + let sut = OutboundQueue() + + await withTaskGroup(of: Void.self) { group in + group.addTask { + try? await sut.run(outbound: outbound) + } + + group.addTask { + var s = sink.makeAsyncIterator() + let a = await s.next() + sut.close() + #expect(a == .part(.tagged(.init(tag: "A", command: .noop)))) + } + + group.addTask { + await #expect(throws: Never.self) { + try await sut.write([.init(tag: "A", command: .noop)]) + } + } + } + } + + /// `close()` must leave the queue closed, so a write issued afterwards fails + /// immediately. If the queue stays in its writing state, the write is appended to a + /// deque that nobody drains any more (the outbound runner has stopped), and its + /// continuation is parked forever. + @Test(.timeLimit(.minutes(3))) + static func writeAfterCloseFailsInsteadOfStalling() async throws { + let sut = OutboundQueue() + sut.close() + + let threw = Mutex(false) + let finished = await finishesWithoutStalling { + do { + try await sut.write([TaggedCommand(tag: "A", command: .noop)]) + } catch { + threw.withLock { $0 = true } + } + } + + #expect(finished, "A write issued after close() must not park in a queue nobody drains.") + #expect(threw.withLock { $0 }, "A write issued after close() must fail.") + } +} diff --git a/Tests/IMAPCommandsTests/WireTracingTests.swift b/Tests/IMAPCommandsTests/WireTracingTests.swift new file mode 100644 index 00000000..d8669b48 --- /dev/null +++ b/Tests/IMAPCommandsTests/WireTracingTests.swift @@ -0,0 +1,92 @@ +//===----------------------------------------------------------------------===// +// +// 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 Logging +import NIO +import Testing + +/// `IMAPConnection.Configuration.Logging.logging` traces channel events through the logger rather +/// than to standard error, so the traces land in the same stream as everything else. +/// +/// These drive the handlers through an `EmbeddedChannel`, so they need no socket. +@Suite("Wire tracing") +struct WireTracingTests { + + /// Channel handlers run on the event loop, outside any task, so the task-local logger is not + /// available to them: the logger has to be passed in and captured. + @Test + func inboundEventsAreTracedThroughThePassedLogger() throws { + let recorder = LogRecorder() + let channel = EmbeddedChannel() + try channel.pipeline.syncOperations.addHandler( + makeInboundDebugHandler(logger: recorder.logger) + ) + + try channel.writeInbound(ByteBuffer(string: "* OK ready\r\n")) + + let traces = recorder.records(message: "Inbound channel event") + #expect(!traces.isEmpty, "The inbound event should have been traced: \(recorder.records)") + #expect( + traces.allSatisfy { $0.level == .trace }, + "Wire tracing is noisy, so it belongs at `.trace`: \(traces.map(\.level))" + ) + #expect( + traces.contains { "\($0.metadata["imap.event"] ?? "")".contains("read(") }, + "The traced event should describe the read: \(traces.map(\.metadata))" + ) + _ = try channel.finish() + } + + @Test + func outboundEventsAreTracedThroughThePassedLogger() throws { + let recorder = LogRecorder() + let channel = EmbeddedChannel() + try channel.pipeline.syncOperations.addHandler( + makeOutboundDebugHandler(logger: recorder.logger) + ) + + try channel.writeOutbound(ByteBuffer(string: "A1 NOOP\r\n")) + + let traces = recorder.records(message: "Outbound channel event") + #expect(!traces.isEmpty, "The outbound event should have been traced: \(recorder.records)") + #expect(traces.allSatisfy { $0.level == .trace }) + _ = try channel.finish() + } + + /// Nothing is traced when the logger does not admit `.trace`, which is what keeps the + /// tracing free for a caller who leaves `logging: .logging` on with a production logger. + @Test + func tracingIsSuppressedWhenTheLoggerDoesNotAdmitTrace() throws { + let recorder = LogRecorder() + var logger = recorder.logger + logger.logLevel = .info + let channel = EmbeddedChannel() + try channel.pipeline.syncOperations.addHandler(makeInboundDebugHandler(logger: logger)) + + try channel.writeInbound(ByteBuffer(string: "* OK ready\r\n")) + + #expect(recorder.records.isEmpty, "Expected no records: \(recorder.records)") + _ = try channel.finish() + } +} + +extension LogRecorder { + /// A `.trace`-level logger that writes into this recorder. + var logger: Logger { + var logger = Logger(label: "test.wire", factory: { _ in self.handler }) + logger.logLevel = .trace + return logger + } +} diff --git a/Tests/NIOIMAPCoreTests/Grammar/CommandType/SetQuota+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/CommandType/SetQuota+Tests.swift index f3e58936..5127b120 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/CommandType/SetQuota+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/CommandType/SetQuota+Tests.swift @@ -76,7 +76,7 @@ struct QuotaCommandTests { @Test( "parse GETQUOTAROOT", arguments: [ - ParseFixture.getQuotaRoot("GETQUOTAROOT INBOX", expected: .success(.getQuotaRoot(MailboxName("INBOX")))), + ParseFixture.getQuotaRoot("GETQUOTAROOT INBOX", expected: .success(.getQuotaRoot(.inbox))), ParseFixture.getQuotaRoot("GETQUOTAROOT Other", expected: .success(.getQuotaRoot(MailboxName("Other")))), ParseFixture.getQuotaRoot("GETQUOTAROOT", expected: .failure), ] diff --git a/Tests/NIOIMAPCoreTests/Grammar/Mailbox/MailboxInfo+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Mailbox/MailboxInfo+Tests.swift index 23cf298c..d9d2c269 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Mailbox/MailboxInfo+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Mailbox/MailboxInfo+Tests.swift @@ -95,7 +95,7 @@ struct MailboxInfoTests { EncodeFixture.mailboxInfo( MailboxInfo( attributes: [.marked, .hasChildren], - path: try! .init(name: MailboxName("INBOX"), pathSeparator: "/"), + path: try! .init(name: .inbox, pathSeparator: "/"), extensions: [:] ), #"(\Marked \HasChildren) "/" "INBOX""# diff --git a/Tests/NIOIMAPCoreTests/Grammar/Quota/QuotaRootResponse+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Quota/QuotaRootResponse+Tests.swift index d8678dd2..aa7d9944 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Quota/QuotaRootResponse+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Quota/QuotaRootResponse+Tests.swift @@ -20,12 +20,12 @@ import Testing struct QuotaRootResponseTests { @Test(arguments: [ EncodeFixture.quotaRootResponse( - MailboxName("INBOX"), + .inbox, QuotaRoot("Root"), #"QUOTAROOT "INBOX" "Root""# ), EncodeFixture.quotaRootResponse( - MailboxName("INBOX"), + .inbox, QuotaRoot("#user/alice"), ##"QUOTAROOT "INBOX" "#user/alice""## ),