Repository Public
1// SP Notes Core2// File: Sources/SPNotesAPI/NotesAPI+Files.swift3// Description: Ranged access to `GET /api/files/<id>` (API-NEXT §4.15): a byte range with its `Content-Range`, and a4// resumable attachment download (Range + If-Range, append on 206, clean restart on 200, 416 handled,5// ETag = sha256 of the content verified at the end).6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import CryptoKit10import Foundation1112// MARK: - Models1314/// One byte range of a `Range` header (the server serves a single range per request).15public enum ByteRange: Sendable, Equatable {16 /// `bytes=a-b` (both inclusive).17 case bounded(ClosedRange<Int64>)18 /// `bytes=a-` — from an offset to the end.19 case from(Int64)20 /// `bytes=-n` — the last `n` bytes.21 case suffix(Int64)2223 /// The value of the `Range` header.24 public var headerValue: String {25 switch self {26 case .bounded(let range): return "bytes=\(range.lowerBound)-\(range.upperBound)"27 case .from(let offset): return "bytes=\(offset)-"28 case .suffix(let count): return "bytes=-\(count)"29 }30 }31}3233/// A parsed `Content-Range` header: `bytes a-b/<size>` (206) or `bytes */<size>` (416).34public struct ContentRange: Sendable, Equatable {35 /// The bytes carried by the answer; `nil` for `*` (unsatisfiable range).36 public var range: ClosedRange<Int64>?37 /// The size of the whole file; `nil` for `/*`.38 public var total: Int64?3940 public init(range: ClosedRange<Int64>?, total: Int64?) {41 self.range = range42 self.total = total43 }4445 /// Parses the header value; `nil` when it is not a `bytes` content range.46 public init?(header: String) {47 let text = header.trimmingCharacters(in: .whitespaces)48 guard text.lowercased().hasPrefix("bytes") else { return nil }49 let body = text.dropFirst(5).trimmingCharacters(in: CharacterSet(charactersIn: " ="))50 let parts = body.split(separator: "/", maxSplits: 1, omittingEmptySubsequences: false)51 guard parts.count == 2 else { return nil }52 let size = parts[1].trimmingCharacters(in: .whitespaces)53 if size == "*" { total = nil } else { guard let n = Int64(size), n >= 0 else { return nil }; total = n }54 let span = parts[0].trimmingCharacters(in: .whitespaces)55 if span == "*" {56 range = nil57 } else {58 let bounds = span.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)59 guard bounds.count == 2, let a = Int64(bounds[0]), let b = Int64(bounds[1]), a >= 0, b >= a else { return nil }60 range = a...b61 }62 }63}6465/// Answer of `NotesAPI.fileRange(id:range:ifRange:)`.66public struct FileRange: Sendable, Equatable {67 /// `206` (the range), `200` (the whole file: several ranges, a malformed header, or `If-Range` with another68 /// ETag) or `416` (unsatisfiable range: no bytes).69 public var status: Int70 public var data: Data71 public var contentRange: ContentRange?72 /// `"<sha256 of the whole content>"`, quotes included, as the server sent it.73 public var etag: String?74 public var contentType: String?7576 /// The answer carries exactly the requested range.77 public var isPartial: Bool { status == 206 }78 /// `416`: the range starts at or after the end of the file (`totalSize` tells where the end is).79 public var isUnsatisfiable: Bool { status == 416 }80 /// The size of the whole file, when the answer tells it.81 public var totalSize: Int64? { contentRange?.total ?? (status == 200 ? Int64(data.count) : nil) }82}8384/// Result of a resumable download.85public struct ResumedDownload: Sendable, Equatable {86 /// The complete file (the `destination`).87 public var fileURL: URL88 public var size: Int6489 /// The ETag of the content (`"<sha256>"`).90 public var etag: String?91 public var contentType: String?92 /// File name announced by the server (`Content-Disposition`).93 public var suggestedFilename: String?94 /// Bytes of the partial file that were kept (0 = downloaded from the first byte).95 public var resumedFrom: Int6496 /// A partial file existed and had to be thrown away (the content changed on the server, or it did not match).97 public var restarted: Bool98 /// The sha256 of the file was checked against the ETag.99 public var verified: Bool100}101102// MARK: - Routes103104extension NotesAPI {105 /// `GET /api/files/<id>` with `Range` — a slice of an attachment, held in memory (thumbnails, audio seeking,106 /// probing the size with `.bounded(0...0)`). A `416` is **returned** (`isUnsatisfiable`, `totalSize`), not thrown.107 /// `404` unknown or deleted attachment, `410 gone` file missing on disk.108 /// - Parameter ifRange: an ETag; when the content changed the server answers the whole file (`status == 200`).109 public func fileRange(id: String, range: ByteRange, ifRange: String? = nil) async throws -> FileRange {110 var request = HTTPRequest.get(Self.filePath(id: id))111 request.accept = "*/*"112 request.extraHeaders = ["Range": range.headerValue, "Accept-Encoding": "identity"]113 if let ifRange { request.extraHeaders["If-Range"] = ifRange }114 let (response, bytes) = try await client.openBytes(request)115 var data = Data()116 do { for try await byte in bytes { data.append(byte) } } catch { throw APIError.fromTransport(error) }117 guard response.status == 200 || response.status == 206 || response.status == 416 else {118 throw APIError.fromResponse(status: response.status, body: data)119 }120 return FileRange(status: response.status, data: response.status == 416 ? Data() : data,121 contentRange: response.header("content-range").flatMap(ContentRange.init(header:)),122 etag: response.header("etag"), contentType: response.contentType)123 }124125 /// Where the ETag of a partial download is remembered between two attempts: `<partial>.etag`.126 public static func etagSidecarURL(forPartial partial: URL) -> URL {127 URL(fileURLWithPath: partial.path + ".etag")128 }129130 /// `GET /api/files/<id>` — **resumable** download of an attachment, streamed to disk.131 ///132 /// The bytes go to `partial`; when the file is complete (and its sha256 equals the ETag) it is moved to133 /// `destination` (replaced if it exists). If the transfer is interrupted — cancellation, lost connection,134 /// timeout — the error is thrown and **`partial` keeps the bytes read so far**: call again with the same `partial`135 /// to continue. The ETag the partial bytes belong to is kept next to it (`etagSidecarURL(forPartial:)`).136 ///137 /// With a non-empty `partial` the request carries `Range: bytes=<size>-` and, when the ETag is known,138 /// `If-Range`:139 /// - `206` → the bytes are appended;140 /// - `200` → the content changed (or the server ignored the range): `partial` is restarted from the first byte;141 /// - `416` → `partial` already holds the whole file (same size, same ETag): nothing is transferred; otherwise142 /// the content changed and the download restarts from the first byte.143 ///144 /// - Parameters:145 /// - etag: the ETag the partial bytes belong to, when the caller stored it itself (default: the sidecar file).146 /// - verifyChecksum: compare the sha256 of the complete file with the ETag (`APIError.file` on a mismatch,147 /// after one automatic restart when the mismatch comes from resumed bytes).148 /// - progress: called on a background task; `completedBytes` counts the resumed bytes too.149 public func downloadFile(id: String, to destination: URL, resumingFrom partial: URL, etag: String? = nil, verifyChecksum: Bool = true,150 progress: TransferProgressHandler? = nil) async throws -> ResumedDownload {151 let fm = FileManager.default152 let sidecar = Self.etagSidecarURL(forPartial: partial)153 var knownETag = etag ?? (try? String(contentsOf: sidecar, encoding: .utf8)).map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }.flatMap { $0.isEmpty ? nil : $0 }154 var restarted = false155 var attempt = 0156157 func discard() {158 try? fm.removeItem(at: partial)159 try? fm.removeItem(at: sidecar)160 knownETag = nil161 restarted = true162 }163164 while true {165 attempt += 1166 let offset = Self.fileSize(partial)167 if offset == 0 { knownETag = etag }168 var request = HTTPRequest.get(Self.filePath(id: id))169 request.accept = "*/*"170 // The offsets are those of the stored bytes: no transparent content decoding.171 request.extraHeaders["Accept-Encoding"] = "identity"172 if offset > 0 {173 request.extraHeaders["Range"] = ByteRange.from(offset).headerValue174 if let knownETag { request.extraHeaders["If-Range"] = knownETag }175 }176 let (response, bytes) = try await client.openBytes(request)177 let answerETag = response.header("etag")178 var resumedFrom: Int64 = 0179180 switch response.status {181 case 206:182 let range = response.header("content-range").flatMap(ContentRange.init(header:))183 let sameContent = knownETag == nil || answerETag == nil || Self.sameETag(knownETag, answerETag)184 guard offset > 0, range?.range?.lowerBound == offset, sameContent else {185 // Not the continuation of what is on disk: start again from the first byte.186 guard attempt < 3 else { throw APIError.invalidResponse }187 discard()188 continue189 }190 if let answerETag { try? Data(answerETag.utf8).write(to: sidecar, options: .atomic) }191 resumedFrom = offset192 try await Self.receive(bytes, into: partial, appendingAt: offset, total: range?.total, progress: progress)193 case 200:194 if offset > 0 { restarted = true }195 try? fm.removeItem(at: sidecar)196 if let answerETag {197 try? fm.createDirectory(at: sidecar.deletingLastPathComponent(), withIntermediateDirectories: true)198 try? Data(answerETag.utf8).write(to: sidecar, options: .atomic)199 }200 try await Self.receive(bytes, into: partial, appendingAt: 0, total: response.header("content-length").flatMap(Int64.init), progress: progress)201 case 416:202 let total = response.header("content-range").flatMap(ContentRange.init(header:))?.total203 let sameContent = knownETag == nil || answerETag == nil || Self.sameETag(knownETag, answerETag)204 guard offset > 0, total == offset, sameContent else {205 // The file on the server is shorter than, or different from, what is on disk.206 guard attempt < 3 else { throw APIError.invalidResponse }207 discard()208 continue209 }210 resumedFrom = offset211 progress?(TransferProgress(completedBytes: offset, totalBytes: offset))212 default:213 var body = Data()214 do { for try await byte in bytes { body.append(byte); if body.count >= 1 << 20 { break } } } catch { throw APIError.fromTransport(error) }215 throw APIError.fromResponse(status: response.status, body: body)216 }217218 let finalETag = answerETag ?? knownETag219 var verified = false220 if verifyChecksum, let expected = Self.sha256Hex(fromETag: finalETag) {221 let actual: String222 do { actual = try Self.sha256Hex(ofFile: partial) } catch { throw APIError.file("cannot read the download: \(error.localizedDescription)") }223 guard actual == expected else {224 let wasResumed = resumedFrom > 0225 discard()226 // Resumed bytes that belonged to another content: one clean restart, then give up.227 if wasResumed, attempt < 3 { continue }228 throw APIError.file("the downloaded file does not match its checksum")229 }230 verified = true231 }232 do {233 try fm.createDirectory(at: destination.deletingLastPathComponent(), withIntermediateDirectories: true)234 if fm.fileExists(atPath: destination.path) { try fm.removeItem(at: destination) }235 try fm.moveItem(at: partial, to: destination)236 } catch {237 throw APIError.file("cannot store the download: \(error.localizedDescription)")238 }239 try? fm.removeItem(at: sidecar)240 return ResumedDownload(241 fileURL: destination, size: Self.fileSize(destination), etag: finalETag, contentType: response.contentType,242 suggestedFilename: response.header("content-disposition").flatMap(Self.filename(fromContentDisposition:)),243 resumedFrom: resumedFrom, restarted: restarted, verified: verified244 )245 }246 }247248 // MARK: plumbing249250 static func fileSize(_ url: URL) -> Int64 {251 ((try? FileManager.default.attributesOfItem(atPath: url.path))?[.size] as? NSNumber)?.int64Value ?? 0252 }253254 /// Strong comparison of two ETags, ignoring the weak prefix and the quotes.255 static func sameETag(_ a: String?, _ b: String?) -> Bool {256 guard let a, let b else { return false }257 return bareETag(a) == bareETag(b)258 }259260 static func bareETag(_ etag: String) -> String {261 var text = etag.trimmingCharacters(in: .whitespaces)262 if text.hasPrefix("W/") { text.removeFirst(2) }263 return text.trimmingCharacters(in: CharacterSet(charactersIn: "\""))264 }265266 /// The sha256 carried by an ETag of the files route (`"<64 hex digits>"`); `nil` for any other ETag.267 static func sha256Hex(fromETag etag: String?) -> String? {268 guard let etag else { return nil }269 let bare = bareETag(etag).lowercased()270 guard bare.count == 64, bare.allSatisfy({ $0.isHexDigit }) else { return nil }271 return bare272 }273274 static func sha256Hex(ofFile url: URL) throws -> String {275 let handle = try FileHandle(forReadingFrom: url)276 defer { try? handle.close() }277 var hasher = SHA256()278 while let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty { hasher.update(data: chunk) }279 return hasher.finalize().map { byte in (byte < 16 ? "0" : "") + String(byte, radix: 16) }.joined()280 }281282 /// Writes the stream to `file` from `offset` (0 = the file is started again). Whatever happens, the bytes read283 /// from the stream so far are on disk when this returns or throws.284 private static func receive<Bytes: AsyncSequence & Sendable>(_ bytes: Bytes, into file: URL, appendingAt offset: Int64, total: Int64?,285 progress: TransferProgressHandler?) async throws where Bytes.Element == UInt8 {286 let fm = FileManager.default287 let handle: FileHandle288 do {289 try fm.createDirectory(at: file.deletingLastPathComponent(), withIntermediateDirectories: true)290 if offset == 0 || !fm.fileExists(atPath: file.path) {291 guard fm.createFile(atPath: file.path, contents: nil) else { throw CocoaError(.fileWriteUnknown) }292 }293 handle = try FileHandle(forWritingTo: file)294 try handle.truncate(atOffset: UInt64(offset))295 try handle.seekToEnd()296 } catch {297 throw APIError.file("cannot write the download: \(error.localizedDescription)")298 }299 defer { try? handle.close() }300 let capacity = 64 * 1024301 var buffer = [UInt8]()302 buffer.reserveCapacity(capacity)303 var written = offset304305 func flush() throws {306 guard !buffer.isEmpty else { return }307 do { try handle.write(contentsOf: buffer) } catch { throw APIError.file("cannot write the download: \(error.localizedDescription)") }308 written += Int64(buffer.count)309 buffer.removeAll(keepingCapacity: true)310 progress?(TransferProgress(completedBytes: written, totalBytes: total))311 }312313 do {314 for try await byte in bytes {315 buffer.append(byte)316 if buffer.count >= capacity { try flush() }317 }318 } catch {319 try? flush()320 throw APIError.fromTransport(error)321 }322 try flush()323 if let total, written < total {324 // The connection closed early without an error: what was received is kept for the next attempt.325 throw APIError.transport(.networkConnectionLost)326 }327 }328}329