SPB Git

Repository Public

NotesAPI+Files.swift 16.6 KB 329 lines swift

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

Theme