apple_kit

Apple-native services for Radroots iOS and macOS apps
git clone https://radroots.dev/git/apple_kit.git
Log | Files | Refs | README | LICENSE

RadrootsAppleFileRoots.swift (7483B)


      1 import Darwin
      2 import Foundation
      3 
      4 public struct RadrootsAppleFileRoots: Sendable, Equatable {
      5     public let appIdentifier: String
      6     public let dataRoot: URL
      7     public let cacheRoot: URL
      8     public let temporaryRoot: URL
      9     public let logsRoot: URL
     10     public let stagedBlobsRoot: URL
     11 
     12     public init(
     13         appIdentifier: String,
     14         dataRoot: URL,
     15         cacheRoot: URL,
     16         temporaryRoot: URL,
     17         logsRoot: URL? = nil,
     18         stagedBlobsRoot: URL? = nil
     19     ) throws {
     20         let normalizedAppIdentifier = try Self.normalizedAppIdentifier(appIdentifier)
     21         let normalizedDataRoot = try Self.normalizedRootURL(dataRoot, field: "dataRoot")
     22         let normalizedCacheRoot = try Self.normalizedRootURL(cacheRoot, field: "cacheRoot")
     23         let normalizedTemporaryRoot = try Self.normalizedRootURL(
     24             temporaryRoot, field: "temporaryRoot")
     25         self.appIdentifier = normalizedAppIdentifier
     26         self.dataRoot = normalizedDataRoot
     27         self.cacheRoot = normalizedCacheRoot
     28         self.temporaryRoot = normalizedTemporaryRoot
     29         self.logsRoot = try Self.normalizedRootURL(
     30             logsRoot ?? normalizedCacheRoot.appendingPathComponent("Logs", isDirectory: true),
     31             field: "logsRoot"
     32         )
     33         self.stagedBlobsRoot = try Self.normalizedRootURL(
     34             stagedBlobsRoot
     35                 ?? normalizedTemporaryRoot.appendingPathComponent("staged_blobs", isDirectory: true),
     36             field: "stagedBlobsRoot"
     37         )
     38     }
     39 
     40     public static func appContainer(
     41         appIdentifier: String,
     42         fileManager: FileManager = .default
     43     ) throws -> Self {
     44         do {
     45             let normalizedAppIdentifier = try normalizedAppIdentifier(appIdentifier)
     46             let dataBaseURL = try canonicalExistingDirectory(
     47                 fileManager.url(
     48                     for: .applicationSupportDirectory,
     49                     in: .userDomainMask,
     50                     appropriateFor: nil,
     51                     create: true
     52                 )
     53             )
     54             let cacheBaseURL = try canonicalExistingDirectory(
     55                 fileManager.url(
     56                     for: .cachesDirectory,
     57                     in: .userDomainMask,
     58                     appropriateFor: nil,
     59                     create: true
     60                 )
     61             )
     62             let dataRoot = dataBaseURL.appendingPathComponent(
     63                 normalizedAppIdentifier, isDirectory: true)
     64             let cacheRoot = cacheBaseURL.appendingPathComponent(
     65                 normalizedAppIdentifier, isDirectory: true
     66             )
     67             let temporaryRoot = try canonicalExistingDirectory(fileManager.temporaryDirectory)
     68                 .appendingPathComponent(normalizedAppIdentifier, isDirectory: true)
     69             return try Self(
     70                 appIdentifier: normalizedAppIdentifier,
     71                 dataRoot: dataRoot,
     72                 cacheRoot: cacheRoot,
     73                 temporaryRoot: temporaryRoot
     74             )
     75         } catch let error as RadrootsAppleFileError {
     76             throw error
     77         } catch {
     78             throw RadrootsAppleFileError.permanentFailure
     79         }
     80     }
     81 
     82     public func root(for scope: RadrootsFileScope) -> URL {
     83         switch scope {
     84         case .data:
     85             dataRoot
     86         case .cache:
     87             cacheRoot
     88         case .temporary:
     89             temporaryRoot
     90         case .logs:
     91             logsRoot
     92         }
     93     }
     94 
     95     public func resolvedURL(
     96         for file: RadrootsFileReference,
     97         allowRootDirectory: Bool = false
     98     ) throws -> URL {
     99         let rootURL = root(for: file.scope)
    100         let trimmedPath = file.relativePath.trimmingCharacters(in: .whitespacesAndNewlines)
    101         if trimmedPath.isEmpty {
    102             if allowRootDirectory {
    103                 return rootURL
    104             }
    105             throw RadrootsAppleFileError.invalidRequest
    106         }
    107         if NSString(string: trimmedPath).isAbsolutePath {
    108             throw RadrootsAppleFileError.invalidRequest
    109         }
    110 
    111         let components = try Self.normalizedRelativeComponents(trimmedPath)
    112         let candidateURL =
    113             components.isEmpty
    114             ? rootURL : rootURL.appendingPathComponent(components.joined(separator: "/"))
    115         if candidateURL.path == rootURL.path {
    116             if allowRootDirectory {
    117                 return candidateURL
    118             }
    119             throw RadrootsAppleFileError.invalidRequest
    120         }
    121         guard candidateURL.path.hasPrefix(rootURL.path + "/") else {
    122             throw RadrootsAppleFileError.invalidRequest
    123         }
    124         return candidateURL
    125     }
    126 
    127     private static func normalizedRelativeComponents(_ trimmedPath: String) throws -> [String] {
    128         var components: [String] = []
    129         for component in trimmedPath.split(separator: "/", omittingEmptySubsequences: true) {
    130             if component == "." {
    131                 continue
    132             }
    133             if component == ".." {
    134                 guard !components.isEmpty else { throw RadrootsAppleFileError.invalidRequest }
    135                 components.removeLast()
    136             } else {
    137                 guard !component.utf8.contains(0) else {
    138                     throw RadrootsAppleFileError.invalidRequest
    139                 }
    140                 components.append(String(component))
    141             }
    142         }
    143         return components
    144     }
    145 
    146     public func stagedBlobURL(for blob: RadrootsStagedBlobReference) throws -> URL {
    147         let normalizedBlobID = try RadrootsStagedBlobReference.normalizedBlobID(blob.blobID)
    148         // Foundation standardization can rewrite an existing /private/var path
    149         // back to the /var symlink alias. Keep the already-admitted root bytes.
    150         return stagedBlobsRoot.appendingPathComponent(normalizedBlobID, isDirectory: false)
    151     }
    152 
    153     public static func normalizedAppIdentifier(_ appIdentifier: String) throws -> String {
    154         let trimmed = appIdentifier.trimmingCharacters(in: .whitespacesAndNewlines)
    155         guard !trimmed.isEmpty, trimmed != ".", trimmed != "..",
    156             !trimmed.contains("/"), !trimmed.utf8.contains(0)
    157         else {
    158             throw RadrootsAppleFileError.invalidRequest
    159         }
    160         return trimmed
    161     }
    162 
    163     public static func normalizedRootURL(_ rootURL: URL, field _: String) throws -> URL {
    164         guard rootURL.isFileURL else {
    165             throw RadrootsAppleFileError.invalidRequest
    166         }
    167         guard rootURL.path.hasPrefix("/"), !rootURL.path.utf8.contains(0) else {
    168             throw RadrootsAppleFileError.invalidRequest
    169         }
    170         var components: [String] = []
    171         for component in rootURL.path.split(separator: "/", omittingEmptySubsequences: true) {
    172             if component == "." {
    173                 continue
    174             }
    175             if component == ".." {
    176                 if !components.isEmpty {
    177                     components.removeLast()
    178                 }
    179             } else {
    180                 components.append(String(component))
    181             }
    182         }
    183         return URL(fileURLWithPath: "/" + components.joined(separator: "/"), isDirectory: true)
    184     }
    185 
    186     private static func canonicalExistingDirectory(_ directory: URL) throws -> URL {
    187         guard directory.isFileURL,
    188             let pointer = directory.path.withCString({ Darwin.realpath($0, nil) })
    189         else {
    190             throw RadrootsAppleFileError.permanentFailure
    191         }
    192         defer { Darwin.free(pointer) }
    193         return URL(fileURLWithPath: String(cString: pointer), isDirectory: true)
    194     }
    195 }