From f537c1aa54a5ded446d61e3bcde78abda91e254a Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Sat, 28 Dec 2024 16:03:26 -0800 Subject: [PATCH] cleanup docs, align API --- .../Formic/Documentation.docc/Documentation.md | 8 ++------ .../Engine/CommandExecutionResult.md | 1 - .../Formic/Documentation.docc/Engine/Engine.md | 18 ++++++------------ .../Documentation.docc/Engine/PlaybookState.md | 11 ----------- .../Engine/PlaybookStatus.md | 9 --------- Sources/Formic/Documentation.docc/Playbook.md | 15 --------------- .../Formic/Engine/CommandExecutionResult.swift | 1 - Sources/Formic/Engine/Engine.swift | 9 ++++----- Sources/Formic/ResourceTypes/Dpkg.swift | 2 ++ Tests/formicTests/EngineTests.swift | 6 +++--- 10 files changed, 17 insertions(+), 63 deletions(-) delete mode 100644 Sources/Formic/Documentation.docc/Engine/PlaybookState.md delete mode 100644 Sources/Formic/Documentation.docc/Engine/PlaybookStatus.md delete mode 100644 Sources/Formic/Documentation.docc/Playbook.md diff --git a/Sources/Formic/Documentation.docc/Documentation.md b/Sources/Formic/Documentation.docc/Documentation.md index 5be09af..4ed42cf 100644 --- a/Sources/Formic/Documentation.docc/Documentation.md +++ b/Sources/Formic/Documentation.docc/Documentation.md @@ -17,10 +17,7 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa ### Running Playbooks -- ``Playbook`` - ``Engine`` -- ``PlaybookStatus`` -- ``PlaybookState`` - ``CommandExecutionResult`` - ``Verbosity`` @@ -41,7 +38,7 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa ### Resources - ``OperatingSystem`` -- ``DebianPackage`` +- ``Dpkg`` - ``Resource`` - ``StatefulResource`` @@ -52,5 +49,4 @@ Quite a is inspired by [Ansible](https://github.com/ansible/ansible), with a goa ### Collections of Resources -- ``CollectionQueryableResource`` -- ``NamedResource`` +- ``CollectionResource`` diff --git a/Sources/Formic/Documentation.docc/Engine/CommandExecutionResult.md b/Sources/Formic/Documentation.docc/Engine/CommandExecutionResult.md index e240cf0..e9562b3 100644 --- a/Sources/Formic/Documentation.docc/Engine/CommandExecutionResult.md +++ b/Sources/Formic/Documentation.docc/Engine/CommandExecutionResult.md @@ -6,7 +6,6 @@ - ``command`` - ``host`` -- ``playbookId`` - ``output`` - ``duration`` - ``retries`` diff --git a/Sources/Formic/Documentation.docc/Engine/Engine.md b/Sources/Formic/Documentation.docc/Engine/Engine.md index 61079a3..d644f28 100644 --- a/Sources/Formic/Documentation.docc/Engine/Engine.md +++ b/Sources/Formic/Documentation.docc/Engine/Engine.md @@ -8,20 +8,14 @@ ### Running Playbooks -- ``schedule(_:delay:startRunner:)`` -- ``step(for:)`` -- ``cancel(_:)`` +- ``run(host:commands:displayProgress:verbosity:)`` +- ``run(hosts:commands:displayProgress:verbosity:)`` -### Receiving Updates from the Engine - -- ``commandUpdates`` -- ``playbookUpdates`` -- ``status(_:)`` +### Running an individual command -### Inspecting the Engine +- ``run(host:command:)`` -- ``runnerOperating(for:)`` +### Receiving Updates from the Engine -### Controlling the Engine +- ``commandUpdates`` -- ``cancelRunner(for:)`` diff --git a/Sources/Formic/Documentation.docc/Engine/PlaybookState.md b/Sources/Formic/Documentation.docc/Engine/PlaybookState.md deleted file mode 100644 index 850dc90..0000000 --- a/Sources/Formic/Documentation.docc/Engine/PlaybookState.md +++ /dev/null @@ -1,11 +0,0 @@ -# ``PlaybookState`` - -## Topics - -### States - -- ``scheduled`` -- ``running`` -- ``complete`` -- ``failed`` -- ``cancelled`` diff --git a/Sources/Formic/Documentation.docc/Engine/PlaybookStatus.md b/Sources/Formic/Documentation.docc/Engine/PlaybookStatus.md deleted file mode 100644 index e82bf1f..0000000 --- a/Sources/Formic/Documentation.docc/Engine/PlaybookStatus.md +++ /dev/null @@ -1,9 +0,0 @@ -# ``PlaybookStatus`` - -## Topics - -### Inspecting Playbook Status - -- ``state`` -- ``playbook`` -- ``results`` diff --git a/Sources/Formic/Documentation.docc/Playbook.md b/Sources/Formic/Documentation.docc/Playbook.md deleted file mode 100644 index b7d7643..0000000 --- a/Sources/Formic/Documentation.docc/Playbook.md +++ /dev/null @@ -1,15 +0,0 @@ -# ``Playbook`` - -## Topics - -### Creating a Playbook - -- ``init(name:hosts:commands:)-lhyo`` -- ``init(name:hosts:commands:)-5js45`` - -### Inspecting Playbooks - -- ``id`` -- ``name`` -- ``hosts`` -- ``commands`` diff --git a/Sources/Formic/Engine/CommandExecutionResult.swift b/Sources/Formic/Engine/CommandExecutionResult.swift index 9514bf9..0dad31d 100644 --- a/Sources/Formic/Engine/CommandExecutionResult.swift +++ b/Sources/Formic/Engine/CommandExecutionResult.swift @@ -17,7 +17,6 @@ public struct CommandExecutionResult: Sendable { /// - Parameters: /// - command: The command. /// - host: The host for the command. - /// - playbookId: The ID of the playbook the command is part of, it any. /// - output: The output from the command /// - duration: The duration of execution of the command. /// - retries: The number of retries needed for the command. diff --git a/Sources/Formic/Engine/Engine.swift b/Sources/Formic/Engine/Engine.swift index 59447fe..1e40c40 100644 --- a/Sources/Formic/Engine/Engine.swift +++ b/Sources/Formic/Engine/Engine.swift @@ -30,7 +30,7 @@ public actor Engine { ) async throws -> [CommandExecutionResult] { var results: [CommandExecutionResult] = [] for command in commands { - let result = try await run(command: command, host: host) + let result = try await run(host: host, command: command) results.append(result) if displayProgress { print(result.consoleOutput(verbosity: verbosity)) @@ -67,13 +67,12 @@ public actor Engine { return hostResults } - /// Directly runs a single command against a single host. + /// Directly runs a single command against a single host, applying the retry and timeout policies of the command. /// - Parameters: - /// - command: The command to run. /// - host: The host on which to run the command. - /// - playbookId: The ID of the playbook the command is part of. + /// - command: The command to run. /// - Returns: The result of the command execution. - public nonisolated func run(command: (any Command), host: Host) async throws + public nonisolated func run(host: Host, command: (any Command)) async throws -> CommandExecutionResult { // `nonisolated` + `async` means run on a cooperative thread pool and return the result diff --git a/Sources/Formic/ResourceTypes/Dpkg.swift b/Sources/Formic/ResourceTypes/Dpkg.swift index 78fb5a2..3b6d609 100644 --- a/Sources/Formic/ResourceTypes/Dpkg.swift +++ b/Sources/Formic/ResourceTypes/Dpkg.swift @@ -113,6 +113,8 @@ public struct Dpkg: Sendable, Hashable, Resource { /// - Parameters: /// - name: The name of the package. /// - state: The desired state of the package. + /// - retry: The retry settings for resolving the resource. + /// - resolveTimeout: The execution timeout to allow the resource to resolve. public init( name: String, state: DesiredPackageState, retry: Backoff = .never, resolveTimeout: Duration = .seconds(60) ) { diff --git a/Tests/formicTests/EngineTests.swift b/Tests/formicTests/EngineTests.swift index f4805ef..38a0f46 100644 --- a/Tests/formicTests/EngineTests.swift +++ b/Tests/formicTests/EngineTests.swift @@ -18,7 +18,7 @@ func testEngineRun() async throws { dependencyValues.commandInvoker = TestCommandInvoker() .addSuccess(command: ["uname"], presentOutput: "Darwin\n") } operation: { - try await engine.run(command: cmd, host: .localhost) + try await engine.run(host: .localhost, command: cmd) } #expect(cmdExecOut.command.id == cmd.id) @@ -172,7 +172,7 @@ func testCommandTimeout() async throws { dependencyValues.localSystemAccess = TestFileSystemAccess() dependencyValues.commandInvoker = mockCmdInvoker } operation: { - return try await engine.run(command: cmd1, host: fakeHost) + return try await engine.run(host: fakeHost, command: cmd1) } }) } @@ -197,7 +197,7 @@ func testCommandRetry() async throws { dependencyValues.localSystemAccess = TestFileSystemAccess() dependencyValues.commandInvoker = mockCmdInvoker } operation: { - return try await engine.run(command: cmd1, host: fakeHost) + return try await engine.run(host: fakeHost, command: cmd1) } #expect(result.command.id == cmd1.id)