Close #25: Login

Author: i2h3

FetchTestResponses.sh

@@ -17,8 +17,7 @@ let package = Package(
     ],
     products: [
         .library(name: "Rainmaker", targets: ["Rainmaker"]),
-        .executable(name: "RainmakerCLI", targets: ["RainmakerCLI"]),
-        .library(name: "RainmakerMocks", targets: ["RainmakerMocks"]),
+        .executable(name: "rainmaker-cli", targets: ["RainmakerCLI"]),
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.6.2"),
@@ -30,7 +29,6 @@ let package = Package(
             .product(name: "ArgumentParser", package: "swift-argument-parser"),
             "Rainmaker",
         ]),
-        .target(name: "RainmakerMocks", dependencies: ["Rainmaker"]),
         .testTarget(name: "RainmakerTests", dependencies: ["Rainmaker"], resources: [.copy("Responses")]),
     ]
 )

Package.swift

@@ -0,0 +1,22 @@
+# Command Line Interface
+
+This package also provides a convenient executable to leverage the features of the library in a terminal environment.
+
+## Overview
+
+You can get an overview by running the command line interface itself or any subcommand with the `--help` option in the package root directory like this:
+
+```plaintext
+$ swift run rainmaker-cli --help
+USAGE: rainmaker <subcommand>
+
+OPTIONS:
+  -h, --help              Show help information.
+
+SUBCOMMANDS:
+  list                    List the content of a directory on the server by the given path.
+  login                   Fetch the login flow information from a server.
+  poll                    Poll the status of a previously initiated login flow.
+
+  See 'rainmaker help <subcommand>' for detailed help.
+```

Sources/Rainmaker/Documentation.docc/CommandLineInterface.md

@@ -6,13 +6,17 @@ A simple Swift library to interact with Nextcloud programmatically.
 
 ### Services
 
-- ``Requesting``
 - ``Server``
-- ``Serving``
 
 ### Data Models
 
 - ``Item``
 - ``Lock``
+- ``LoginFlow``
+- ``LoginResult``
 - ``Permission``
 - ``User``
+
+### Command Line Interface
+
+- <doc:CommandLineInterface>

Sources/Rainmaker/Documentation.docc/Documentation.md

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2025 Iva Horn
+// SPDX-License-Identifier: MIT
+
+import Foundation
+
+///
+/// All the necessary information to begin and monitor a client login flow.
+///
+public struct LoginFlow: Model {
+    ///
+    /// The endpoint to poll for the status.
+    ///
+    public let endpoint: URL
+
+    ///
+    /// The initial web page to present to the user for logging in.
+    ///
+    public let entry: URL
+
+    ///
+    /// The token the specific login flow is identified by.
+    ///
+    public let token: String
+}

Sources/Rainmaker/Models/LoginFlow.swift

@@ -0,0 +1,24 @@
+// SPDX-FileCopyrightText: 2025 Iva Horn
+// SPDX-License-Identifier: MIT
+
+import Foundation
+
+///
+/// The result of a successfully completed login flow.
+///
+public struct LoginResult: Model {
+    ///
+    /// The user name to log in with.
+    ///
+    public let name: String
+
+    ///
+    /// The (app) password provided by the server.
+    ///
+    public let password: String
+
+    ///
+    /// The final server address itself.
+    ///
+    public let server: URL
+}

Sources/Rainmaker/Models/LoginResult.swift

@@ -5,6 +5,11 @@
 /// HTTP request methods.
 ///
 enum Method: String, RawRepresentable {
+    ///
+    /// Sending data to a resource.
+    ///
+    case post = "POST"
+
     ///
     /// Fetch properties of remote items.
     ///

Sources/Rainmaker/Models/Method.swift

@@ -59,7 +59,7 @@ public enum Permission: Character, Model {
 
         for character in compound {
             guard let permission = Self(rawValue: character) else {
-                throw RainmakerError.responseDecodingFailed("Unknown permission character: \(character)")
+                throw RainmakerError.responseDecodingFailed(reason: "Unknown permission character: \(character)")
             }
 
             permissions.insert(permission)

Sources/Rainmaker/Models/Permission.swift

@@ -6,15 +6,28 @@ import Foundation
 ///
 /// Semantic errors specific to this library.
 ///
-enum RainmakerError: Error, CustomStringConvertible {
+public enum RainmakerError: Error, Equatable, CustomStringConvertible {
+    ///
+    /// The intended action requires credentials like user name and password but they were not given.
+    ///
+    case credentialsRequired
+
     ///
     /// The response most likely was not in the expected format or structure.
     ///
-    case responseDecodingFailed(_ reason: String)
+    /// - Parameters:
+    ///     - reason: A human readable explanation why it failed.
+    ///
+    case responseDecodingFailed(reason: String)
 
-    var description: String {
+    ///
+    /// For conformance to `CustomStringConvertible` to render an error as a human readable error description.
+    ///
+    public var description: String {
         switch self {
-            case let .responseDecodingFailed(reason):
+            case .credentialsRequired:
+                "Credentials required"
+            case let .responseDecodingFailed(reason: reason):
                 reason
         }
     }

Sources/Rainmaker/Models/RainmakerError.swift

@@ -0,0 +1,19 @@
+// SPDX-FileCopyrightText: 2025 Iva Horn
+// SPDX-License-Identifier: MIT
+
+import Foundation
+
+///
+/// This is the JSON response as returned by the server.
+///
+/// This is a data transfer object and is converted to a ``LoginFlow`` for external callers.
+///
+struct LoginFlowResponse: Decodable {
+    struct Poll: Decodable {
+        let endpoint: URL
+        let token: String
+    }
+
+    let login: URL
+    let poll: Poll
+}