SPB Git

Repository Public License

SafeOutput.swift 27.0 KB 486 lines swift

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
Files main
Menu

Theme