Repository Public License
1// ORIX Convert — Packages/ORIXConvertCore/Sources/ConvertCore/Jobs/JobRunner.swift2// Description: Executes one job off the queue actor: detection, planning, inspection, conversion of every plan step3// inside a private work directory, generic and engine validation, then the atomic commit. Reports to the4// queue through an ordered signal channel.5// Author: Simon-Pierre Boucher — contact@spboucher.ai6import Foundation78/// Converted output kept in its work directory while the user decides what to do about an existing destination.9struct HeldOutput: Sendable {10 let workDirectory: URL11 let items: [URL]12 let names: [String]13 let directory: URL14}1516enum JobSignal: Sendable {17 case state(JobState)18 case prepared(sourceFormat: FormatID, detection: DetectionResult?, plan: ConversionPlan, bytesBefore: Int64?)19 case progress(ProgressUpdate, step: Int, of: Int)20 case log(LogLevel, String)21 case warning(ConversionWarning)22}2324struct RunReport: Sendable {25 enum Outcome: Sendable {26 case finished27 case skipped(String)28 case cancelled29 case failed(ConversionError)30 /// Destination exists under `askUser`. `held` is `nil` when the conflict was found before converting.31 case conflict(DestinationConflict, held: HeldOutput?)32 }3334 var outcome: Outcome = .cancelled35 var checks: [ValidationCheck] = []36 var warnings: [ConversionWarning] = []37 var outputs: [CommittedOutput] = []38 var facts: [String: String] = [:]39 var bytesAfter: Int64?40}4142struct JobRunner: Sendable {43 let id: UUID44 let request: ConversionJobRequest45 /// Policy chosen through `resolveConflict`, replacing the request's.46 let policy: ConflictPolicy47 let allowReplacingSource: Bool48 let registry: FormatRegistry49 let workDirectories: WorkDirectoryManager50 let signal: @Sendable (JobSignal) -> Void5152 func run() async -> RunReport {53 var report = RunReport()54 let warnings = LockedBox<[ConversionWarning]>([])55 var workDirectory: URL?56 var keepWorkDirectory = false57 do {58 report.outcome = try await perform(&report, warnings: warnings, workDirectory: &workDirectory, keep: &keepWorkDirectory)59 } catch is CancellationError {60 report.outcome = .cancelled61 } catch let error as ConversionError {62 report.outcome = Task.isCancelled ? .cancelled : .failed(error)63 } catch {64 report.outcome = Task.isCancelled ? .cancelled : .failed(.internalError(error.localizedDescription))65 }66 if let workDirectory, !keepWorkDirectory { workDirectories.remove(workDirectory) }67 report.warnings = warnings.value68 return report69 }7071 private func perform(_ report: inout RunReport, warnings: LockedBox<[ConversionWarning]>, workDirectory: inout URL?,72 keep: inout Bool) async throws -> RunReport.Outcome {73 let fm = FileManager.default74 let warn: @Sendable (ConversionWarning) -> Void = { warning in75 var isNew = false76 warnings.mutate { if !$0.contains(warning) { $0.append(warning); isNew = true } }77 if isNew { signal(.warning(warning)) }78 }7980 // 1. Prepare: sources, format, plan.81 try Task.checkCancellation()82 guard let primary = request.sources.first else { throw ConversionError.unreadableInput("No source file was given.") }83 for source in request.sources where !fm.fileExists(atPath: source.path) {84 throw ConversionError.unreadableInput("\(source.lastPathComponent) no longer exists.")85 }86 var detection: DetectionResult?87 var sourceFormat = request.sourceFormat88 if sourceFormat == nil {89 let result = FileTypeDetector.detect(primary)90 detection = result91 sourceFormat = result.format92 signal(.log(.info, "Detected \(result.format?.rawValue ?? "unknown format") — \(result.evidence)."))93 if result.mismatch, let format = result.format {94 warn(ConversionWarning(.caution, code: "extension-mismatch",95 "The name says .\(result.fileExtension) but the content is \(format.rawValue.uppercased()); it is converted as \(format.rawValue.uppercased())."))96 }97 }98 guard let sourceFormat else {99 throw ConversionError.malformedInput("The format of \(primary.lastPathComponent) could not be recognised.")100 }101 let plan = try ConversionPlanner(registry: registry).plan(from: sourceFormat, to: request.destinationFormat, operation: request.operation,102 engine: request.engineID, allowChaining: request.allowChaining)103 if request.sources.count > 1, !plan.acceptsMultipleSources {104 throw ConversionError.invalidOption("This conversion takes one file at a time; \(request.sources.count) were given.")105 }106 var engines: [any ConversionEngine] = []107 for step in plan.steps {108 guard let engine = registry.engine(id: step.engine) else { throw ConversionError.engineUnavailable("Engine \(step.engine) is not registered.") }109 engines.append(engine)110 }111 let bytesBefore = request.sources.compactMap(FileSizer.size(of:)).reduce(Int64(0), +)112 signal(.prepared(sourceFormat: sourceFormat, detection: detection, plan: plan, bytesBefore: bytesBefore))113 let route = ([plan.source] + plan.steps.map(\.destination)).map(\.rawValue).joined(separator: " → ")114 signal(.log(.info, "Plan: \(route) (\(plan.engines.joined(separator: ", ")))\(plan.isChained ? " — chained through an intermediate file" : "")."))115 for limitation in plan.limitations { signal(.log(.info, "Limitation: \(limitation)")) }116117 var inspection: FileInspection?118 if let inspector = registry.inspector(for: sourceFormat) {119 inspection = try? await inspector.inspect(primary, format: sourceFormat)120 try Task.checkCancellation()121 }122123 // 2. Destination: name and early conflict detection (before spending time converting).124 let directory = request.destination.directory ?? primary.deletingLastPathComponent()125 var nameContext = OutputNameContext(source: primary, counter: request.counter, width: inspection?.pixelWidth, height: inspection?.pixelHeight)126 let provisionalBase = OutputNameTemplate.render(request.destination.nameTemplate, nameContext)127 let expectedExtension = FormatCatalog.format(plan.destination)?.preferredExtension ?? plan.destination.rawValue128 let predicted = directory.appendingPathComponent(OutputNameTemplate.fileName(base: provisionalBase, ext: plan.destination == .folder ? "" : expectedExtension))129 let predictedIsSource = request.sources.contains { SafeWriter.isSameFile($0, predicted) }130 if fm.fileExists(atPath: predicted.path) {131 switch policy {132 case .skip:133 return .skipped("\(predicted.lastPathComponent) already exists in the destination folder.")134 case .askUser:135 return .conflict(DestinationConflict(existing: predicted, isSource: predictedIsSource, conversionDone: false), held: nil)136 case .replace where predictedIsSource && !allowReplacingSource:137 throw ConversionError.destinationExists("\(predicted.path) is the source file. Choose another name, or allow replacing the original explicitly.")138 case .rename, .replace:139 break140 }141 }142143 let firstRequest = stepRequest(0, plan: plan, source: primary, baseName: provisionalBase)144 for warning in engines[0].preflight(firstRequest, inspection: inspection) { warn(warning) }145146 // 3. Convert every step inside the work directory.147 let work = try workDirectories.create()148 workDirectory = work149 signal(.state(.running))150 var current = primary151 var output = ConversionOutput(files: [])152 for (index, step) in plan.steps.enumerated() {153 try Task.checkCancellation()154 let isLast = index == plan.steps.count - 1155 let stepDirectory = try workDirectories.createSubdirectory("step-\(index + 1)", in: work)156 let stepRequest = stepRequest(index, plan: plan, source: current, baseName: provisionalBase)157 let count = plan.steps.count158 let context = ConversionContext(159 workDirectory: stepDirectory,160 progress: { signal(.progress($0, step: index, of: count)) },161 log: { signal(.log($0, $1)) },162 warn: warn)163 if plan.isChained {164 signal(.log(.info, "Step \(index + 1) of \(count): \(step.source.rawValue) → \(step.destination.rawValue) with \(step.engine)."))165 }166 output = try await engines[index].convert(stepRequest, context: context)167 try Task.checkCancellation()168 if isLast { signal(.state(.validating)) }169 var checks = OutputValidator.validate(output, destinationFormat: step.destination, workDirectory: stepDirectory)170 if checks.allSatisfy(\.passed) {171 checks += try await engines[index].validate(output, request: stepRequest, source: index == 0 ? inspection : nil)172 }173 try Task.checkCancellation()174 if plan.isChained { checks = checks.map { ValidationCheck("step\(index + 1).\($0.name)", passed: $0.passed, $0.detail) } }175 report.checks += checks176 if let failed = checks.first(where: { !$0.passed }) {177 throw ConversionError.outputInvalid(failed.detail.isEmpty ? "Check \(failed.name) failed." : failed.detail)178 }179 if !isLast {180 guard output.files.count == 1, let intermediate = output.files.first,181 (try? intermediate.resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) == true else {182 throw ConversionError.outputInvalid("The intermediate \(step.destination.rawValue) step produced \(output.files.count) items; a chained conversion needs exactly one file.")183 }184 current = intermediate185 }186 }187 report.facts = output.facts188 signal(.log(.info, "Output verified (\(report.checks.count) checks passed)."))189190 // 4. Commit: final names (dimensions measured on the output win over the source's), then atomic moves.191 if let width = output.facts["width"].flatMap(Int.init), let height = output.facts["height"].flatMap(Int.init) {192 nameContext.width = width; nameContext.height = height193 }194 let finalBase = OutputNameTemplate.render(request.destination.nameTemplate, nameContext)195 var items = output.files196 var names = items.map { file -> String in197 let name = file.lastPathComponent198 return name.hasPrefix(provisionalBase) ? finalBase + name.dropFirst(provisionalBase.count) : name199 }200 // Several loose files for one job: one folder named after the output, holding them under their own names.201 if items.count > 1, plan.destination != .folder, request.groupMultipleOutputs {202 let bundle = try workDirectories.createSubdirectory("bundle", in: work).appendingPathComponent(OutputNameTemplate.fileName(base: finalBase, ext: ""), isDirectory: true)203 do {204 try fm.createDirectory(at: bundle, withIntermediateDirectories: false)205 for (item, name) in zip(items, names) { try fm.moveItem(at: item, to: bundle.appendingPathComponent(name)) }206 } catch {207 throw ConversionError.writeFailed("The \(items.count) output files could not be gathered in one folder: \(error.localizedDescription)")208 }209 signal(.log(.info, "\(items.count) files were produced; they are delivered in one folder named \(bundle.lastPathComponent)."))210 report.facts["outputFiles"] = String(items.count)211 items = [bundle]212 names = [bundle.lastPathComponent]213 }214 for (index, item) in items.enumerated() {215 do {216 report.outputs += try SafeWriter.commit([item], names: [names[index]], to: directory, policy: policy, sources: request.sources,217 allowReplacingSource: allowReplacingSource)218 } catch ConversionError.destinationExists(let message) where policy == .askUser {219 signal(.log(.info, "Destination exists: \(message)"))220 let existing = directory.appendingPathComponent(names[index])221 keep = true222 let held = HeldOutput(workDirectory: work, items: Array(items[index...]), names: Array(names[index...]), directory: directory)223 return .conflict(DestinationConflict(existing: existing, isSource: request.sources.contains { SafeWriter.isSameFile($0, existing) }, conversionDone: true), held: held)224 }225 }226 let written = report.outputs.filter { $0.outcome != .skipped }227 report.bytesAfter = written.isEmpty ? nil : written.compactMap { FileSizer.size(of: $0.url) }.reduce(Int64(0), +)228 if written.isEmpty { return .skipped("Every output already exists in the destination folder.") }229 for item in written { signal(.log(.info, "Wrote \(item.url.path)\(item.outcome == .written ? "" : " (\(item.outcome.rawValue))").")) }230 return .finished231 }232233 private func stepRequest(_ index: Int, plan: ConversionPlan, source: URL, baseName: String) -> ConversionRequest {234 let step = plan.steps[index]235 let isLast = index == plan.steps.count - 1236 return ConversionRequest(source: source, sourceFormat: step.source, destinationFormat: step.destination, operation: step.operation,237 options: isLast ? request.options : .init(), additionalSources: index == 0 ? Array(request.sources.dropFirst()) : [],238 outputBaseName: baseName)239 }240}241