Repository Public License
1// ORIX Convert — Packages/ORIXConvertCore/Sources/ConvertCore/SafeOutput.swift2// Description: Everything between "the engine wrote something in a temp directory" and "the user's file is in3// place": private per-job work directories, generic output validation, output naming templates, and the4// atomic, conflict-aware move to the destination. The source file is never overwritten by accident.5// Author: Simon-Pierre Boucher — contact@spboucher.ai6import Foundation78// MARK: - Locations910/// Standard locations of ORIX Convert's own files.11public enum AppPaths {12 /// `~/Library/Application Support/ORIX Convert` (or `ORIX_CONVERT_SUPPORT_DIR` when set, for tests and tools).13 public static var applicationSupport: URL {14 if let override = ProcessInfo.processInfo.environment["ORIX_CONVERT_SUPPORT_DIR"], !override.isEmpty {15 return URL(fileURLWithPath: override, isDirectory: true)16 }17 let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first18 ?? URL(fileURLWithPath: NSHomeDirectory()).appendingPathComponent("Library/Application Support", isDirectory: true)19 return base.appendingPathComponent("ORIX Convert", isDirectory: true)20 }2122 /// Root of the per-job work directories, inside the user's temporary directory.23 public static var temporaryRoot: URL {24 FileManager.default.temporaryDirectory.appendingPathComponent("ai.spboucher.orix.convert", isDirectory: true)25 .appendingPathComponent("work", isDirectory: true)26 }2728 public static var historyDatabase: URL { applicationSupport.appendingPathComponent("history.sqlite") }29 public static var presetsFile: URL { applicationSupport.appendingPathComponent("presets.json") }30 public static var workflowsFile: URL { applicationSupport.appendingPathComponent("workflows.json") }31 public static var watcherFile: URL { applicationSupport.appendingPathComponent("watch-rules.json") }32}3334/// Creates, removes and sweeps the private directories engines write into.35public struct WorkDirectoryManager: Sendable {36 public let root: URL3738 public init(root: URL = AppPaths.temporaryRoot) { self.root = root }3940 /// Creates `<root>/<pid>-<uuid>` with mode 0700 (the root itself is created 0700 as well).41 public func create() throws -> URL {42 let fm = FileManager.default43 do {44 try fm.createDirectory(at: root, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])45 let dir = root.appendingPathComponent("\(ProcessInfo.processInfo.processIdentifier)-\(UUID().uuidString)", isDirectory: true)46 try fm.createDirectory(at: dir, withIntermediateDirectories: false, attributes: [.posixPermissions: 0o700])47 return dir48 } catch {49 throw ConversionError.writeFailed("The temporary work folder could not be created: \(error.localizedDescription)")50 }51 }5253 /// Creates a 0700 sub-directory of a work directory (one per plan step).54 public func createSubdirectory(_ name: String, in workDirectory: URL) throws -> URL {55 let dir = workDirectory.appendingPathComponent(name, isDirectory: true)56 do {57 try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])58 } catch {59 throw ConversionError.writeFailed("The temporary work folder could not be created: \(error.localizedDescription)")60 }61 return dir62 }6364 /// Removes a work directory. Only directories directly inside `root` are removed.65 public func remove(_ directory: URL) {66 guard directory.deletingLastPathComponent().standardizedFileURL.path == root.standardizedFileURL.path else { return }67 try? FileManager.default.removeItem(at: directory)68 }6970 /// Removes work directories left behind by processes that no longer exist (crash, forced quit), and any71 /// directory older than `maxAge` whose name is not in the expected form. Returns the number removed.72 @discardableResult73 public func sweepStale(maxAge: TimeInterval = 24 * 3600) -> Int {74 let fm = FileManager.default75 guard let entries = try? fm.contentsOfDirectory(at: root, includingPropertiesForKeys: [.contentModificationDateKey]) else { return 0 }76 var removed = 077 for entry in entries {78 let name = entry.lastPathComponent79 var stale = false80 let modifiedDate = try? entry.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate81 if let pid = name.split(separator: "-").first.flatMap({ Int32($0) }), pid > 0 {82 // kill(pid, 0) only tests for existence. ESRCH = no such process. A directory untouched for83 // `maxAge` under another PID is a leftover whose PID was reused.84 let dead = kill(pid, 0) != 0 && errno == ESRCH85 let abandoned = modifiedDate.map { Date().timeIntervalSince($0) > maxAge } ?? false86 stale = pid != ProcessInfo.processInfo.processIdentifier && (dead || abandoned)87 } else if let modified = try? entry.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate {88 stale = Date().timeIntervalSince(modified) > maxAge89 }90 if stale, (try? fm.removeItem(at: entry)) != nil { removed += 1 }91 }92 return removed93 }94}9596// MARK: - Validation9798public enum OutputValidator {99 /// Largest number of items examined inside a directory output.100 public static let directoryScanLimit = 100_000101102 /// Generic checks applied to every conversion output before the engine's own `validate`:103 ///104 /// - the engine returned at least one item, and every item is inside the work directory;105 /// - every item exists, is not a symbolic link, and is not empty;106 /// - a file's detected format is the destination format or an allowed equivalent107 /// (`FormatEquivalence.accepts`); a format the detector has no signature for passes on its extension, and the108 /// check says so;109 /// - a directory output contains at least one entry of any kind (a file, a link or an empty folder: an archive110 /// of empty folders extracts to something) and no symbolic link pointing outside of it. A link whose target111 /// does not exist is judged on its path alone: it is inside when the path stays inside.112 public static func validate(_ output: ConversionOutput, destinationFormat: FormatID, workDirectory: URL) -> [ValidationCheck] {113 guard !output.files.isEmpty else { return [ValidationCheck("output.present", passed: false, "The engine reported no output.")] }114 var checks: [ValidationCheck] = []115 let fm = FileManager.default116 let root = workDirectory.resolvingSymlinksInPath().path117 for url in output.files {118 let name = url.lastPathComponent119 let resolvedParent = url.deletingLastPathComponent().resolvingSymlinksInPath().path120 guard resolvedParent == root || resolvedParent.hasPrefix(root + "/") else {121 checks.append(ValidationCheck("output.location", passed: false, "\(name) is outside the work folder."))122 continue123 }124 guard let attributes = try? fm.attributesOfItem(atPath: url.path), let type = attributes[.type] as? FileAttributeType else {125 checks.append(ValidationCheck("output.exists", passed: false, "\(name) was not written."))126 continue127 }128 if type == .typeSymbolicLink {129 checks.append(ValidationCheck("output.exists", passed: false, "\(name) is a symbolic link, not a file."))130 } else if type == .typeDirectory {131 checks.append(contentsOf: validateDirectory(url))132 } else if type == .typeRegular {133 let size = (attributes[.size] as? NSNumber)?.int64Value ?? 0134 guard size > 0 else {135 checks.append(ValidationCheck("output.not-empty", passed: false, "\(name) is empty."))136 continue137 }138 checks.append(ValidationCheck("output.not-empty", passed: true, "\(name): \(size) bytes"))139 if destinationFormat != .folder { checks.append(formatCheck(url, expected: destinationFormat)) }140 } else {141 checks.append(ValidationCheck("output.exists", passed: false, "\(name) is not a regular file or folder."))142 }143 }144 return checks145 }146147 static func formatCheck(_ url: URL, expected: FormatID) -> ValidationCheck {148 let detection = FileTypeDetector.detect(url)149 let name = url.lastPathComponent150 guard let detected = detection.format else {151 return ValidationCheck("output.format", passed: false, "\(name): content is not recognisable as \(expected.rawValue) (\(detection.evidence)).")152 }153 if detection.confidence == .extensionOnly {154 let ok = !detection.mismatch && FormatEquivalence.accepts(detected: detected, as: expected)155 return ValidationCheck("output.format", passed: ok, ok156 ? "\(name): no content signature exists for \(expected.rawValue); extension matches."157 : "\(name): \(detection.evidence).")158 }159 let ok = FormatEquivalence.accepts(detected: detected, as: expected)160 return ValidationCheck("output.format", passed: ok, ok161 ? "\(name): detected \(detected.rawValue) (\(detection.evidence))."162 : "\(name): expected \(expected.rawValue) but the content is \(detected.rawValue) (\(detection.evidence)).")163 }164165 /// `true` when the symbolic link at `link` points inside `root`. The target is first resolved **lexically**166 /// (`..` and `.` folded, no file-system access): climbing above the root, or an absolute path outside it, is an167 /// escape whether or not anything exists there. When the lexical path is inside, intermediate links that exist168 /// are followed as well, and must also stay inside; a target that does not exist (dangling link, or a path169 /// running through a regular file) cannot lead anywhere and is inside.170 static func linkStaysInside(_ link: URL, root: URL) -> Bool {171 guard let target = try? FileManager.default.destinationOfSymbolicLink(atPath: link.path) else { return false }172 func inside(_ path: String, _ base: String) -> Bool { path == base || path.hasPrefix(base + "/") }173 func lexical(_ path: String) -> String {174 var parts: [Substring] = []175 for part in path.split(separator: "/", omittingEmptySubsequences: true) {176 if part == "." { continue }177 if part == ".." { if !parts.isEmpty { parts.removeLast() }; continue }178 parts.append(part)179 }180 return "/" + parts.joined(separator: "/")181 }182 /// realpath of the longest existing prefix, the rest appended as written.183 func real(_ path: String) -> String {184 var existing = path, rest: [String] = []185 while existing != "/" {186 if let resolved = realpath(existing, nil) {187 defer { free(resolved) }188 return ([String(cString: resolved)] + rest.reversed()).joined(separator: "/")189 }190 rest.append((existing as NSString).lastPathComponent)191 existing = (existing as NSString).deletingLastPathComponent192 }193 return path194 }195 let rootPath = lexical(root.path)196 let joined = target.hasPrefix("/") ? target : link.deletingLastPathComponent().path + "/" + target197 let plain = lexical(joined)198 // Lexically outside (the root may itself sit behind a link such as /tmp → /private/tmp: compare both forms).199 let realRoot = real(rootPath)200 guard inside(plain, rootPath) || inside(plain, realRoot) else { return false }201 // The existing part of the target, with its links followed, must stay inside too.202 return inside(real(plain), realRoot)203 }204205 static func validateDirectory(_ url: URL) -> [ValidationCheck] {206 let fm = FileManager.default207 let name = url.lastPathComponent208 guard let enumerator = fm.enumerator(at: url, includingPropertiesForKeys: [.isSymbolicLinkKey, .isRegularFileKey], options: []) else {209 return [ValidationCheck("output.exists", passed: false, "\(name) could not be read.")]210 }211 var files = 0, entries = 0, examined = 0212 var escapes: [String] = []213 for case let item as URL in enumerator {214 examined += 1215 if examined > directoryScanLimit { break }216 entries += 1217 let values = try? item.resourceValues(forKeys: [.isSymbolicLinkKey, .isRegularFileKey])218 if values?.isSymbolicLink == true {219 if !linkStaysInside(item, root: url) { escapes.append(item.lastPathComponent) }220 enumerator.skipDescendants()221 } else if values?.isRegularFile == true {222 files += 1223 }224 }225 let detail = files > 0 ? "\(name): \(files) file(s)" : (entries > 0 ? "\(name): \(entries) item(s), no regular file" : "\(name) is empty.")226 var checks = [ValidationCheck("output.not-empty", passed: entries > 0, detail)]227 checks.append(ValidationCheck("output.no-symlink-escape", passed: escapes.isEmpty,228 escapes.isEmpty ? "No link leaves the folder." : "Links pointing outside the folder: \(escapes.prefix(5).joined(separator: ", "))."))229 return checks230 }231}232233// MARK: - Naming234235/// Values available to an output name template.236public struct OutputNameContext: Sendable, Hashable {237 /// Source file name without extension.238 public var name: String239 /// Source file extension, without dot.240 public var ext: String241 public var date: Date242 /// 1-based position of the file in its batch.243 public var counter: Int244 public var width: Int?245 public var height: Int?246247 public init(name: String, ext: String = "", date: Date = Date(), counter: Int = 1, width: Int? = nil, height: Int? = nil) {248 self.name = name; self.ext = ext; self.date = date; self.counter = counter; self.width = width; self.height = height249 }250251 public init(source: URL, date: Date = Date(), counter: Int = 1, width: Int? = nil, height: Int? = nil) {252 self.init(name: source.deletingPathExtension().lastPathComponent, ext: source.pathExtension.lowercased(), date: date,253 counter: counter, width: width, height: height)254 }255}256257/// Output naming templates. The template produces the base name; the destination format's extension is appended by258/// the engine. Tokens: `{name}` (source name without extension), `{ext}` (source extension), `{date}` (yyyy-MM-dd),259/// `{counter}` (position in the batch; `{counter:3}` pads to 3 digits), `{width}`, `{height}` and the usual260/// `{width}x{height}` (dropped entirely when the dimensions are not known). Unknown tokens are kept as typed.261public enum OutputNameTemplate {262 public static let `default` = "{name}"263 public static let tokens = ["{name}", "{ext}", "{date}", "{counter}", "{width}", "{height}"]264265 public static func render(_ template: String, _ context: OutputNameContext) -> String {266 var out = template.isEmpty ? Self.default : template267 if let width = context.width, let height = context.height {268 out = out.replacingOccurrences(of: "{width}", with: String(width)).replacingOccurrences(of: "{height}", with: String(height))269 } else {270 for token in ["{width}x{height}", "{width}×{height}", "{width}", "{height}"] { out = out.replacingOccurrences(of: token, with: "") }271 }272 let formatter = DateFormatter()273 formatter.locale = Locale(identifier: "en_US_POSIX")274 formatter.dateFormat = "yyyy-MM-dd"275 out = out.replacingOccurrences(of: "{date}", with: formatter.string(from: context.date))276 out = out.replacingOccurrences(of: "{name}", with: context.name).replacingOccurrences(of: "{ext}", with: context.ext)277 out = out.replacingOccurrences(of: "{counter}", with: String(context.counter))278 for digits in 1...9 {279 let token = "{counter:\(digits)}"280 if out.contains(token) {281 let number = String(context.counter)282 out = out.replacingOccurrences(of: token, with: String(repeating: "0", count: max(0, digits - number.count)) + number)283 }284 }285 return sanitize(out)286 }287288 /// Makes a string safe as a file name: `/`, `:` and control characters become `-`, leading dots and289 /// surrounding whitespace are removed, separators left dangling by an empty token are trimmed, and the result is290 /// cut to `maxBytes` UTF-8 bytes on a character boundary. An empty result becomes `untitled`.291 public static func sanitize(_ name: String, maxBytes: Int = 200) -> String {292 var cleaned = String(name.unicodeScalars.map { scalar -> Character in293 if scalar == "/" || scalar == ":" || scalar.value < 0x20 || scalar.value == 0x7F || (0x80...0x9F).contains(scalar.value) { return "-" }294 return Character(scalar)295 })296 // Characters are rebuilt from scalars above; normalise so combining sequences stay together.297 cleaned = cleaned.precomposedStringWithCanonicalMapping298 let dangling = CharacterSet(charactersIn: " -_.").union(.whitespacesAndNewlines)299 var trimmedStart = Substring(cleaned)300 while let first = trimmedStart.first, first == "." || first.isWhitespace { trimmedStart = trimmedStart.dropFirst() }301 cleaned = String(trimmedStart)302 while let last = cleaned.unicodeScalars.last, dangling.contains(last) { cleaned.unicodeScalars.removeLast() }303 while cleaned.utf8.count > maxBytes, !cleaned.isEmpty { cleaned.removeLast() }304 return cleaned.isEmpty ? "untitled" : cleaned305 }306307 /// Full file name limited to 255 UTF-8 bytes (the APFS limit), shortening the base and keeping the extension.308 public static func fileName(base: String, ext: String) -> String {309 let suffix = ext.isEmpty ? "" : "." + ext310 let room = max(1, 255 - suffix.utf8.count)311 return sanitize(base, maxBytes: room) + suffix312 }313}314315// MARK: - Writing316317/// What to do when the destination already exists.318public enum ConflictPolicy: String, Sendable, Codable, CaseIterable {319 /// Do not decide: report `ConversionError.destinationExists` so the caller can ask the user.320 case askUser321 /// Keep both: write `name 2.ext`, `name 3.ext`…322 case rename323 /// Keep the existing file and drop the new one.324 case skip325 /// Replace the existing file atomically. Only when chosen explicitly.326 case replace327}328329/// Result of committing one output item.330public struct CommittedOutput: Sendable, Hashable, Codable {331 public enum Outcome: String, Sendable, Codable { case written, renamed, replaced, skipped }332 /// Final location (for `skipped`, the existing item that was kept).333 public let url: URL334 public let outcome: Outcome335}336337public enum SafeWriter {338 /// Moves validated output items from the work directory into `directory`, each one atomically.339 ///340 /// Every item is first staged inside the destination directory under a hidden `.orix-convert-….partial` name341 /// (a rename when the work directory is on the same volume, a copy otherwise), then put in place with a single342 /// rename: `renamex_np(RENAME_EXCL)` when the name must be free, `FileManager.replaceItemAt` for `replace`. A343 /// partially written file is therefore never visible under the final name.344 ///345 /// - Parameters:346 /// - items: files or directories inside a work directory.347 /// - names: final file names, one per item (default: each item's own name).348 /// - sources: the job's source files. An output is never written over one of them, except with349 /// `policy == .replace` **and** `allowReplacingSource == true`; `rename` numbers the output instead, `skip`350 /// skips it, `askUser` reports the conflict.351 /// - copy: copy instead of moving (used when the item must stay where it is, e.g. exporting an original).352 /// - Throws: `ConversionError.destinationExists` (policy `askUser`, or an unauthorised overwrite of a source),353 /// `ConversionError.writeFailed` for file-system errors. Items committed before an error stay in place.354 public static func commit(_ items: [URL], names: [String]? = nil, to directory: URL, policy: ConflictPolicy,355 sources: [URL] = [], allowReplacingSource: Bool = false, copy: Bool = false) throws -> [CommittedOutput] {356 let fm = FileManager.default357 do {358 try fm.createDirectory(at: directory, withIntermediateDirectories: true)359 } catch {360 throw ConversionError.writeFailed("The destination folder \(directory.path) could not be created: \(error.localizedDescription)")361 }362 var results: [CommittedOutput] = []363 for (index, item) in items.enumerated() {364 let rawName = names.flatMap { index < $0.count ? $0[index] : nil } ?? item.lastPathComponent365 let name = OutputNameTemplate.fileName(base: (rawName as NSString).deletingPathExtension, ext: (rawName as NSString).pathExtension)366 results.append(try commitOne(item, name: name, to: directory, policy: policy, sources: sources,367 allowReplacingSource: allowReplacingSource, copy: copy))368 }369 return results370 }371372 /// The location `commit` would use for `name` in `directory` under `policy`, without writing anything:373 /// `nil` for `skip` when the name is taken; the numbered name for `rename`.374 public static func resolvedDestination(name: String, in directory: URL, policy: ConflictPolicy) -> URL? {375 let target = directory.appendingPathComponent(name)376 guard itemExists(target) else { return target }377 switch policy {378 case .askUser, .replace: return target379 case .skip: return nil380 case .rename: return firstFreeName(for: name, in: directory)381 }382 }383384 /// `name 2.ext`, `name 3.ext`… — the first one that does not exist.385 public static func firstFreeName(for name: String, in directory: URL) -> URL {386 let ext = (name as NSString).pathExtension387 let base = (name as NSString).deletingPathExtension388 for n in 2..<100_000 {389 let candidate = directory.appendingPathComponent(OutputNameTemplate.fileName(base: "\(base) \(n)", ext: ext))390 if !itemExists(candidate) { return candidate }391 }392 return directory.appendingPathComponent(OutputNameTemplate.fileName(base: "\(base) \(UUID().uuidString)", ext: ext))393 }394395 /// `true` when both URLs designate the same existing file (same device and inode), or the same path.396 public static func isSameFile(_ a: URL, _ b: URL) -> Bool {397 if a.standardizedFileURL.resolvingSymlinksInPath().path == b.standardizedFileURL.resolvingSymlinksInPath().path { return true }398 var sa = stat(), sb = stat()399 guard stat(a.path, &sa) == 0, stat(b.path, &sb) == 0 else { return false }400 return sa.st_dev == sb.st_dev && sa.st_ino == sb.st_ino401 }402403 private static func itemExists(_ url: URL) -> Bool {404 var st = stat()405 return lstat(url.path, &st) == 0406 }407408 private static func commitOne(_ item: URL, name: String, to directory: URL, policy: ConflictPolicy, sources: [URL],409 allowReplacingSource: Bool, copy: Bool) throws -> CommittedOutput {410 let fm = FileManager.default411 var target = directory.appendingPathComponent(name)412 var outcome = CommittedOutput.Outcome.written413 let hitsSource = sources.contains { isSameFile($0, target) }414 if hitsSource && !(policy == .replace && allowReplacingSource) {415 switch policy {416 case .rename:417 target = firstFreeName(for: name, in: directory)418 outcome = .renamed419 case .skip:420 return CommittedOutput(url: target, outcome: .skipped)421 case .askUser, .replace:422 throw ConversionError.destinationExists("\(target.path) is the source file. Choose another name, or allow replacing the original explicitly.")423 }424 } else if itemExists(target) {425 switch policy {426 case .askUser: throw ConversionError.destinationExists(target.path)427 case .skip: return CommittedOutput(url: target, outcome: .skipped)428 case .rename:429 target = firstFreeName(for: name, in: directory)430 outcome = .renamed431 case .replace: outcome = .replaced432 }433 }434435 // Stage inside the destination directory so the final step is a same-volume rename.436 let staged = directory.appendingPathComponent(".orix-convert-\(UUID().uuidString).partial")437 do {438 if copy {439 try fm.copyItem(at: item, to: staged)440 } else if rename(item.path, staged.path) != 0 {441 guard errno == EXDEV else { throw ConversionError.writeFailed("\(name): \(String(cString: strerror(errno)))") }442 try fm.copyItem(at: item, to: staged)443 try? fm.removeItem(at: item)444 }445 } catch let error as ConversionError {446 throw error447 } catch {448 try? fm.removeItem(at: staged)449 throw ConversionError.writeFailed("\(name) could not be copied to \(directory.path): \(error.localizedDescription)")450 }451452 if outcome == .replaced {453 do {454 _ = try fm.replaceItemAt(target, withItemAt: staged)455 return CommittedOutput(url: target, outcome: .replaced)456 } catch {457 try? fm.removeItem(at: staged)458 throw ConversionError.writeFailed("\(name) could not replace the existing file: \(error.localizedDescription)")459 }460 }461 // Exclusive rename: if another process created the name in the meantime, apply the policy again.462 for _ in 0..<1000 {463 if renamex_np(staged.path, target.path, UInt32(RENAME_EXCL)) == 0 { return CommittedOutput(url: target, outcome: outcome) }464 guard errno == EEXIST else {465 let message = String(cString: strerror(errno))466 try? fm.removeItem(at: staged)467 throw ConversionError.writeFailed("\(name) could not be moved into place: \(message)")468 }469 switch policy {470 case .rename:471 target = firstFreeName(for: name, in: directory)472 outcome = .renamed473 case .skip:474 try? fm.removeItem(at: staged)475 return CommittedOutput(url: target, outcome: .skipped)476 default:477 // Hand the staged item back so a later decision can still commit it.478 if !copy { try? fm.moveItem(at: staged, to: item) } else { try? fm.removeItem(at: staged) }479 throw ConversionError.destinationExists(target.path)480 }481 }482 try? fm.removeItem(at: staged)483 throw ConversionError.writeFailed("\(name) could not be given a free name in \(directory.path).")484 }485}486