Repository Public License
1// ORIX Secure2// File: Packages/ORIXReporting/Sources/ORIXWorkflow/WorkflowHandler.swift3// Description: What a workflow step runs: the handler protocol, its output, the per-run context that carries values from one4// step to the next, and the registry that maps step kinds to handlers.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import ORIXSecureModel1011/// What a step produced.12public struct StepOutput: Sendable, Hashable, Codable {13 /// One sentence shown in the run and in its report.14 public var summary: String15 public var findings: [Finding]?16 public var section: ReportDocument.Section?17 /// Values handed to the following steps through the context.18 public var values: [String: String]1920 public init(summary: String, findings: [Finding]? = nil, section: ReportDocument.Section? = nil, values: [String: String] = [:]) {21 self.summary = summary22 self.findings = findings23 self.section = section24 self.values = values25 }26}2728/// The state of one run, shared by its steps and by nothing else: every run gets a fresh context.29public actor WorkflowContext {30 public nonisolated let runID: UUID31 private var storage: [String: String]32 private var collectedFindings: [Finding] = []33 private var collectedSections: [ReportDocument.Section] = []3435 public init(runID: UUID = UUID(), values: [String: String] = [:]) {36 self.runID = runID37 self.storage = values38 }3940 public func value(for key: String) -> String? { storage[key] }41 public func setValue(_ value: String?, for key: String) { storage[key] = value }42 public func merge(_ values: [String: String]) { storage.merge(values) { _, new in new } }43 public var values: [String: String] { storage }44 /// Findings and report sections returned by the steps that already finished.45 public var findings: [Finding] { collectedFindings }46 public var sections: [ReportDocument.Section] { collectedSections }4748 func record(_ output: StepOutput) {49 storage.merge(output.values) { _, new in new }50 collectedFindings.append(contentsOf: output.findings ?? [])51 if let section = output.section { collectedSections.append(section) }52 }53}5455public protocol WorkflowStepHandler: Sendable {56 /// Runs one step. Long work must honour task cancellation (`try Task.checkCancellation()`), and `progress` takes a57 /// fraction from 0 to 1 with an optional message.58 func run(step: WorkflowStep, context: WorkflowContext, progress: @escaping @Sendable (Double, String?) -> Void) async throws -> StepOutput59}6061/// A handler made from a closure.62public struct ClosureStepHandler: WorkflowStepHandler {63 public typealias Body = @Sendable (WorkflowStep, WorkflowContext, @escaping @Sendable (Double, String?) -> Void) async throws -> StepOutput64 private let body: Body6566 public init(_ body: @escaping Body) { self.body = body }6768 public func run(step: WorkflowStep, context: WorkflowContext, progress: @escaping @Sendable (Double, String?) -> Void) async throws -> StepOutput {69 try await body(step, context, progress)70 }71}7273/// The handlers the app provides, with the rules of its step kinds.74public struct WorkflowHandlerRegistry: Sendable {75 public var rules: WorkflowRules76 private var handlers: [WorkflowStepKind: any WorkflowStepHandler] = [:]7778 public init(rules: WorkflowRules = .standard) {79 self.rules = rules80 }8182 public mutating func register(_ kind: WorkflowStepKind, handler: any WorkflowStepHandler) {83 handlers[kind] = handler84 }8586 public mutating func register(_ kind: WorkflowStepKind, _ body: @escaping ClosureStepHandler.Body) {87 handlers[kind] = ClosureStepHandler(body)88 }8990 public func handler(for kind: WorkflowStepKind) -> (any WorkflowStepHandler)? { handlers[kind] }91 public var registeredKinds: Set<WorkflowStepKind> { Set(handlers.keys) }92}9394public enum ConfirmationDecision: String, Sendable, Codable, CaseIterable {95 case confirmed96 case declined97}9899public enum WorkflowError: Error, Sendable, Equatable, LocalizedError {100 case unknownStepKind(WorkflowStepKind)101 case timedOut(seconds: TimeInterval)102 case destructiveStepWithoutConfirmation103104 public var errorDescription: String? {105 switch self {106 case .unknownStepKind(let kind): L("This version of ORIX Secure has no action for the step kind “\(kind.rawValue)”.")107 case .timedOut(let seconds): L("The step did not finish within \(Int(seconds.rounded(.up))) seconds and was stopped.")108 case .destructiveStepWithoutConfirmation: L("The step deletes or changes data and has no confirmation; it was not run.")109 }110 }111}112