28015504651

Committed 23 Jun 2026 09:13AM UTC coverage: 80.889%. First build

Build # 28015504651

Build Type

push

github

Committed by

web-flow

Commit Message

feat(storage): add TUS resumable uploads, background downloads, and multipart upload engine (#988)

* docs: add storage background transfers design spec

Covers TUS resumable uploads, background URLSession downloads,
StorageTransferTask<Success> public API, error handling, and test plan.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add storage background transfers implementation plan

9-task TDD plan covering StorageTransferTask types, TUSUploadEngine,
DownloadSessionDelegate, StorageFileAPI wiring, and integration tests.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(storage): add StorageTransferTask, TransferEvent, TransferProgress types

Introduces core transfer infrastructure: StorageTransferTask<Success> generic
handle with events stream and async result, TransferEvent and TransferProgress
value types, mapResult transformation, StorageErrorCode/StorageError extensions
for networkError, fileSystemError, and cancelled, and typed aliases
StorageUploadTask and StorageDownloadTask.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(storage): fix mapResult bridge Task leak, add missing tests

Store the bridge Task in mapResult and cancel it when the returned task
is cancelled to prevent the loop from leaking. Add terminal doc comment
to .completed, and add tests for cancel closure invocation and transform
error propagation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(storage): add backgroundDownloadSessionIdentifier config + download session setup

Adds `backgroundDownloadSessionIdentifier` to `StorageClientConfiguration`,
creates a stub `DownloadSessionDelegate`, and wires a `URLSession` download
session (foreground or background) into `StorageClient` with a
`handleBackgroundEvents(forSessionIdentifier:completionHandler:)` entry point.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(storage): add TUSUploadEngine with POST create and PATCH chunk loop

Co... (continued)

Coverage Stats

982 of 1143 new or added lines in 11 files covered. (85.91%)

8279 of 10235 relevant lines covered (80.89%)

34.2 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.23

/Sources/Storage/StorageFileAPI.swift

import Foundation
import Helpers
import XCTestDynamicOverlay

#if canImport(FoundationNetworking)
  import FoundationNetworking
#endif

let defaultSearchOptions = SearchOptions(
  limit: 100,
  offset: 0,
  sortBy: SortBy(
    column: "name",
    order: .ascending
  )
)

let defaultFileOptions = FileOptions(
  cacheControl: "3600",
  contentType: "text/plain;charset=UTF-8",
  upsert: false
)

#if DEBUG
  import ConcurrencyExtras
  let testingBoundary = LockIsolated<String?>(nil)
#endif

/// File operations API for objects stored within a single Supabase Storage bucket.
///
/// Obtain an instance by calling ``StorageClient/from(_:)`` — do not create one directly.
///
/// `StorageFileAPI` covers the full lifecycle of objects in a bucket: uploading, updating,
/// downloading, listing, deleting, moving, copying, and generating signed or public URLs.
///
/// ## Basic usage
///
/// ```swift
/// let bucket = supabase.storage.from("avatars")
///
/// // Upload
/// let response = try await bucket.upload("user-123/photo.png", data: imageData)
///
/// // Download to disk
/// let url = try await bucket.download(path: "user-123/photo.png").value
/// // Or download into memory
/// let data = try await bucket.downloadData(path: "user-123/photo.png").value
///
/// // Public URL (public bucket)
/// let url = try bucket.getPublicURL(path: "user-123/photo.png")
///
/// // Signed URL (private bucket, valid for 60 seconds)
/// let signedURL = try await bucket.createSignedURL(path: "user-123/photo.png", expiresIn: 60)
/// ```
///
/// - Note: All stored properties are immutable, making `StorageFileAPI` safe to share across
///   concurrency boundaries.
public struct StorageFileAPI: Sendable {
  /// The bucket id to operate on.
  let bucketId: String
  let client: StorageClient

  /// JSONEncoder with default key strategy used when we want `camelCase` keys instead of the default
  /// `snake_case` used in Storage services.
  let originalEncoder: JSONEncoder = {
    let encoder = JSONEncoder()
    #if DEBUG
      if isTesting {
        encoder.outputFormatting = .sortedKeys
      }
    #endif
    return encoder
  }()

  init(bucketId: String, client: StorageClient) {
    self.bucketId = bucketId
    self.client = client
  }

  private struct MoveResponse: Decodable {
    let message: String
  }

  private struct SignedURLAPIResponse: Decodable {
    let signedURL: String
  }

  private struct SignedURLsAPIResponse: Decodable {
    let signedURL: String?
    let path: String
    let error: String?
  }

  private enum Header {
    static let cacheControl = "Cache-Control"
    static let contentType = "Content-Type"
    static let xUpsert = "x-upsert"
  }

  private struct SignedUploadResponse: Decodable {
    let Key: String
  }

  /// Uploads a `Data` value to an existing bucket.
  ///
  /// - Parameters:
  ///   - path: The destination path within the bucket, e.g. `"folder/image.png"`.
  ///     The bucket must already exist.
  ///   - data: The raw file bytes to store.
  ///   - options: Upload options such as content type, cache duration, and upsert behaviour.
  ///   - method: The upload protocol to use. Defaults to ``UploadMethod/auto``, which picks
  ///     multipart for files ≤ 6 MB and TUS resumable for larger files.
  ///     Pass ``UploadMethod/multipart`` or ``UploadMethod/resumable`` to override.
  /// - Returns: A ``StorageUploadTask`` that can be awaited for the result, observed for progress,
  ///   or paused/resumed/cancelled (TUS only).
  ///
  /// If the path already exists and ``FileOptions/upsert`` is `false` (the default), an error
  /// is returned. Set `upsert: true` to overwrite silently instead.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // Auto (default) — picks the right protocol based on size
  /// let response = try await storage.from("avatars").upload(
  ///   "user-123/photo.jpg",
  ///   data: imageData,
  ///   options: FileOptions(contentType: "image/jpeg")
  /// ).value
  ///
  /// // Force TUS for a large video with pause/resume support
  /// let task = storage.from("videos").upload("clip.mp4", data: videoData, method: .resumable)
  /// await task.pause()
  /// await task.resume()
  /// let response = try await task.value
  /// ```
  @discardableResult
  public func upload(
    _ path: String,
    data: Data,
    options: FileOptions = FileOptions(),
    method: UploadMethod = .auto
  ) -> StorageUploadTask {
    let useResumable: Bool
    switch method {
    case .auto: useResumable = data.count > client.configuration.tusChunkSize
    case .multipart: useResumable = false
    case .resumable: useResumable = true
    }
    if useResumable {
      return TUSUploadEngine.makeTask(
        bucketId: bucketId, path: path, source: .data(data), options: options, client: client)
    } else {
      return MultipartUploadEngine.makeTask(
        bucketId: bucketId, path: path, source: .data(data), options: options, client: client)
    }
  }

  /// Uploads a file from a local `URL` to an existing bucket.
  ///
  /// - Parameters:
  ///   - path: The destination path within the bucket, e.g. `"folder/image.png"`.
  ///     The bucket must already exist.
  ///   - fileURL: A local `file://` URL pointing to the file to upload.
  ///   - options: Upload options such as content type, cache duration, and upsert behaviour.
  ///     When `contentType` is `nil`, the MIME type is inferred from the file extension.
  ///   - method: The upload protocol to use. Defaults to ``UploadMethod/auto``, which picks
  ///     multipart for files ≤ 6 MB and TUS resumable for larger files. When the file size
  ///     cannot be determined, ``UploadMethod/auto`` falls back to TUS as a safe default.
  ///     Pass ``UploadMethod/multipart`` or ``UploadMethod/resumable`` to override.
  /// - Returns: A ``StorageUploadTask`` that can be awaited for the result, observed for progress,
  ///   or paused/resumed/cancelled (TUS only).
  ///
  /// ## Example
  ///
  /// ```swift
  /// let response = try await storage.from("documents").upload(
  ///   "reports/2024/annual.pdf",
  ///   fileURL: fileURL
  /// ).value
  ///
  /// // Explicit TUS for a large video
  /// let task = storage.from("videos").upload("tour.mov", fileURL: movURL, method: .resumable)
  /// let response = try await task.value
  /// ```
  @discardableResult
  public func upload(
    _ path: String,
    fileURL: URL,
    options: FileOptions = FileOptions(),
    method: UploadMethod = .auto
  ) -> StorageUploadTask {
    let useResumable: Bool
    switch method {
    case .auto:
      let size = (try? fileURL.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? Int.max
      useResumable = size > client.configuration.tusChunkSize
    case .multipart: useResumable = false
    case .resumable: useResumable = true
    }
    if useResumable {
      return TUSUploadEngine.makeTask(
        bucketId: bucketId, path: path, source: .fileURL(fileURL), options: options, client: client)
    } else {
      return MultipartUploadEngine.makeTask(
        bucketId: bucketId, path: path, source: .fileURL(fileURL), options: options, client: client)
    }
  }

  /// Replaces an existing file at the specified path with new `Data`.
  ///
  /// Sends a `PUT` request to the storage server — the file must already exist.
  /// To create a file if it does not exist, use ``upload(_:data:options:method:)`` with
  /// ``FileOptions/upsert`` set to `true`.
  ///
  /// - Parameters:
  ///   - path: The path of the file to replace, e.g. `"folder/image.png"`.
  ///   - data: The new raw file bytes.
  ///   - options: Upload options such as content type and cache duration.
  /// - Returns: A ``StorageUploadTask`` that can be awaited for the result, or observed for progress.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let response = try await storage.from("avatars").update(
  ///   "user-123/photo.png",
  ///   data: newImageData,
  ///   options: FileOptions(contentType: "image/png")
  /// ).value
  /// ```
  @discardableResult
  public func update(
    _ path: String,
    data: Data,
    options: FileOptions = FileOptions()
  ) -> StorageUploadTask {
    MultipartUploadEngine.makeTask(
      bucketId: bucketId, path: path, source: .data(data), options: options,
      httpMethod: .put, client: client)
  }

  /// Replaces an existing file at the specified path with the contents of a local `URL`.
  ///
  /// Sends a `PUT` request to the storage server — the file must already exist.
  /// To create a file if it does not exist, use ``upload(_:fileURL:options:method:)`` with
  /// ``FileOptions/upsert`` set to `true`.
  ///
  /// - Parameters:
  ///   - path: The path of the file to replace, e.g. `"folder/image.png"`.
  ///   - fileURL: A local `file://` URL pointing to the replacement file.
  ///   - options: Upload options such as content type and cache duration.
  ///     When `contentType` is `nil`, the MIME type is inferred from the file extension.
  /// - Returns: A ``StorageUploadTask`` that can be awaited for the result, or observed for progress.
  ///
  /// ## Example
  ///
  /// ```swift
  /// try await storage.from("documents").update(
  ///   "reports/2024/annual.pdf",
  ///   fileURL: newFileURL
  /// ).value
  /// ```
  @discardableResult
  public func update(
    _ path: String,
    fileURL: URL,
    options: FileOptions = FileOptions()
  ) -> StorageUploadTask {
    MultipartUploadEngine.makeTask(
      bucketId: bucketId, path: path, source: .fileURL(fileURL), options: options,
      httpMethod: .put, client: client)
  }

  /// Moves an existing file to a new path within the same or a different bucket.
  ///
  /// The source file is removed after the move completes. To keep the original, use ``copy(from:to:options:)`` instead.
  ///
  /// - Parameters:
  ///   - source: The current file path, e.g. `"folder/image.png"`.
  ///   - destination: The new file path, e.g. `"archive/image.png"`.
  ///   - options: Optional destination overrides, such as moving the file into a different bucket.
  /// - Throws: ``StorageError`` if the source path does not exist or the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // Rename within the same bucket
  /// try await storage.from("avatars").move(from: "old-name.png", to: "new-name.png")
  ///
  /// // Move to a different bucket
  /// try await storage.from("avatars").move(
  ///   from: "user-123/photo.png",
  ///   to: "user-123/photo.png",
  ///   options: DestinationOptions(destinationBucket: "archive")
  /// )
  /// ```
  public func move(
    from source: String,
    to destination: String,
    options: DestinationOptions? = nil
  ) async throws {
    let body: [String: String?] = [
      "bucketId": bucketId,
      "sourceKey": source,
      "destinationKey": destination,
      "destinationBucket": options?.destinationBucket,
    ]

    try await client.fetchData(
      .post,
      "object/move",
      body: .data(client.encoder.encode(body))
    )
  }

  /// Copies an existing file to a new path, leaving the original in place.
  ///
  /// To move a file without keeping the original, use ``move(from:to:options:)`` instead.
  ///
  /// - Parameters:
  ///   - source: The current file path, e.g. `"folder/image.png"`.
  ///   - destination: The path for the copy, e.g. `"folder/image-copy.png"`.
  ///   - options: Optional destination overrides, such as copying the file into a different bucket.
  /// - Returns: The full storage key of the newly created copy.
  /// - Throws: ``StorageError`` if the source path does not exist or the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // Duplicate a file in the same bucket
  /// let key = try await storage.from("avatars").copy(
  ///   from: "user-123/photo.png",
  ///   to: "user-123/photo-backup.png"
  /// )
  /// print(key) // "avatars/user-123/photo-backup.png"
  /// ```
  @discardableResult
  public func copy(
    from source: String,
    to destination: String,
    options: DestinationOptions? = nil
  ) async throws -> String {
    struct UploadResponse: Decodable {
      let Key: String
    }

    let body: [String: String?] = [
      "bucketId": bucketId,
      "sourceKey": source,
      "destinationKey": destination,
      "destinationBucket": options?.destinationBucket,
    ]

    let response: UploadResponse = try await client.fetchDecoded(
      .post,
      "object/copy",
      body: .data(client.encoder.encode(body))
    )

    return response.Key
  }

  /// Creates a signed URL that grants time-limited access to a private file.
  ///
  /// Signed URLs can be shared with unauthenticated users. They expire after `expiresIn` and
  /// cannot be revoked once issued, so avoid long expiration windows for sensitive files.
  ///
  /// - Parameters:
  ///   - path: The file path within the bucket, e.g. `"folder/image.png"`.
  ///   - expiresIn: How long until the signed URL expires, e.g. `.seconds(3600)` for one hour.
  ///   - download: When non-`nil`, the browser treats the URL as a file download.
  ///   - transform: Optional on-the-fly image transformation applied before the file is served.
  ///   - cacheNonce: An opaque string appended as a `cacheNonce` query parameter.
  /// - Returns: A signed `URL` ready to be shared or embedded.
  /// - Throws: ``StorageError`` if the file does not exist or the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // Short-lived link for streaming a private video
  /// let url = try await storage.from("media")
  ///   .createSignedURL(path: "user-123/video.mp4", expiresIn: .seconds(3600))
  ///
  /// // Signed download link with a custom filename
  /// let downloadURL = try await storage.from("reports")
  ///   .createSignedURL(
  ///     path: "q4-2024.pdf",
  ///     expiresIn: .seconds(300),
  ///     download: .named("Q4-2024-Report.pdf")
  ///   )
  /// ```
  public func createSignedURL(
    path: String,
    expiresIn: Duration,
    download: DownloadBehavior? = nil,
    transform: TransformOptions? = nil,
    cacheNonce: String? = nil
  ) async throws -> URL {
    struct Body: Encodable {
      let expiresIn: Int
      let transform: TransformOptions?
    }

    let response: SignedURLAPIResponse = try await client.fetchDecoded(
      .post,
      "object/sign/\(bucketId)/\(path)",
      body: .data(
        originalEncoder.encode(
          Body(
            expiresIn: Int(expiresIn.components.seconds),
            transform: transform
          )
        )
      )
    )

    return try makeSignedURL(
      response.signedURL,
      download: download,
      cacheNonce: cacheNonce
    )
  }

  /// Creates signed URLs for multiple files in a single request.
  ///
  /// - Parameters:
  ///   - paths: The file paths within the bucket.
  ///   - expiresIn: How long until the signed URLs expire.
  ///   - download: When non-`nil`, the browser treats each URL as a file download.
  ///   - cacheNonce: An opaque string appended as a `cacheNonce` query parameter.
  /// - Returns: An array of ``SignedURLResult`` values, one per input path.
  /// - Throws: ``StorageError`` if the batch request itself fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let results = try await storage.from("media").createSignedURLs(
  ///   paths: ["photo1.jpg", "photo2.jpg", "missing.jpg"],
  ///   expiresIn: .seconds(3600)
  /// )
  ///
  /// for result in results {
  ///   switch result {
  ///   case .success(let path, let url):
  ///     print("\(path) → \(url)")
  ///   case .failure(let path, let error):
  ///     print("\(path) failed: \(error)")
  ///   }
  /// }
  /// ```
  public func createSignedURLs(
    paths: [String],
    expiresIn: Duration,
    download: DownloadBehavior? = nil,
    cacheNonce: String? = nil
  ) async throws -> [SignedURLResult] {
    struct Params: Encodable {
      let expiresIn: Int
      let paths: [String]
    }

    let response: [SignedURLsAPIResponse] = try await client.fetchDecoded(
      .post,
      "object/sign/\(bucketId)",
      body: .data(
        originalEncoder.encode(
          Params(expiresIn: Int(expiresIn.components.seconds), paths: paths)
        )
      )
    )

    return try response.map { item in
      if let signedURLString = item.signedURL {
        let url = try makeSignedURL(
          signedURLString,
          download: download,
          cacheNonce: cacheNonce
        )
        return .success(path: item.path, signedURL: url)
      } else {
        return .failure(path: item.path, error: item.error ?? "Unknown error")
      }
    }
  }

  private func makeSignedURL(
    _ signedURL: String,
    download: DownloadBehavior?,
    cacheNonce: String? = nil
  ) throws -> URL {
    guard let signedURLComponents = URLComponents(string: signedURL),
      var baseComponents = URLComponents(
        url: client.url,
        resolvingAgainstBaseURL: false
      )
    else {
      throw URLError(.badURL)
    }

    baseComponents.path +=
      signedURLComponents.path.hasPrefix("/")
      ? signedURLComponents.path : "/\(signedURLComponents.path)"
    baseComponents.queryItems = signedURLComponents.queryItems

    if let download {
      baseComponents.queryItems = baseComponents.queryItems ?? []
      let value: String
      switch download {
      case .withOriginalName: value = ""
      case .named(let name): value = name
      }
      baseComponents.queryItems!.append(
        URLQueryItem(name: "download", value: value)
      )
    }

    if let cacheNonce {
      baseComponents.queryItems = baseComponents.queryItems ?? []
      baseComponents.queryItems!.append(
        URLQueryItem(name: "cacheNonce", value: cacheNonce)
      )
    }

    guard let url = baseComponents.url else {
      throw URLError(.badURL)
    }
    return url
  }

  /// Deletes one or more files from the bucket.
  ///
  /// All listed paths are deleted in a single request. Non-existent paths are silently ignored.
  ///
  /// - Parameter paths: The paths of the files to delete, e.g. `["folder/image.png", "other.pdf"]`.
  /// - Returns: An array of ``FileObject`` values describing the deleted files.
  /// - Throws: ``StorageError`` if the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let deleted = try await storage.from("avatars").remove(paths: [
  ///   "user-123/photo.png",
  ///   "user-456/photo.png"
  /// ])
  /// print("Deleted \(deleted.count) file(s)")
  /// ```
  @discardableResult
  public func remove(paths: [String]) async throws -> [FileObject] {
    try await client.fetchDecoded(
      .delete,
      "object/\(bucketId)",
      body: .data(client.encoder.encode(["prefixes": paths]))
    )
  }

  /// Lists files and folders within the bucket, optionally scoped to a path prefix.
  ///
  /// Results include both files and virtual folder entries. Paginate large buckets using
  /// ``SearchOptions/limit`` and ``SearchOptions/offset``.
  ///
  /// - Parameters:
  ///   - path: An optional folder path to list. When `nil`, lists the bucket root.
  ///   - options: Filtering, sorting, and pagination options. Defaults to 100 items sorted
  ///     by name ascending when `nil`.
  /// - Returns: An array of ``FileObject`` values representing the matching files and folders.
  /// - Throws: ``StorageError`` if the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // List all files in the "user-123" folder
  /// let files = try await storage.from("avatars").list(path: "user-123")
  ///
  /// // Paginate with custom sort
  /// let page2 = try await storage.from("photos").list(
  ///   path: "gallery",
  ///   options: SearchOptions(limit: 20, offset: 20, sortBy: SortBy(column: "created_at", order: .descending))
  /// )
  /// ```
  public func list(
    path: String? = nil,
    options: SearchOptions? = nil
  ) async throws -> [FileObject] {
    var options = options ?? defaultSearchOptions
    options.prefix = path ?? ""

    return try await client.fetchDecoded(
      .post,
      "object/list/\(bucketId)",
      body: .data(originalEncoder.encode(options))
    )
  }

  /// Downloads a file to a temporary location on disk.
  ///
  /// The task's success value is a `URL` pointing to a temporary file. Move or copy the file to a
  /// permanent location before the app exits — the file is not guaranteed to persist across
  /// launches.
  ///
  /// Downloads support pause and resume. Calling ``StorageDownloadTask/pause()`` suspends the
  /// transfer and captures resume data when the server returns `Accept-Ranges: bytes`. Calling
  /// ``StorageDownloadTask/resume()`` continues from the last received byte when resume data is
  /// available, or restarts from the beginning otherwise.
  ///
  /// When ``StorageClientConfiguration/backgroundDownloadSessionIdentifier`` is set, downloads
  /// continue while the app is suspended. Wire up
  /// ``StorageClient/handleBackgroundEvents(forSessionIdentifier:completionHandler:)`` in your
  /// `AppDelegate` to support background transfers.
  ///
  /// - Parameters:
  ///   - path: Path within the bucket, e.g. `"folder/image.png"`.
  ///   - options: Optional on-the-fly image transformation (resize, reformat, quality).
  ///   - query: Additional query items appended to the request URL.
  ///   - cacheNonce: An opaque string appended as `cacheNonce=<value>` for cache busting.
  /// - Returns: A ``StorageDownloadTask`` whose success value is a `URL` to the file on disk.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let task = storage.from("videos").download(path: "clip.mp4")
  ///
  /// // Pause mid-download and resume later
  /// await task.pause()
  /// await task.resume()
  ///
  /// // Await the final file URL
  /// let url = try await task.value
  /// let dest = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
  ///   .appendingPathComponent("clip.mp4")
  /// try FileManager.default.moveItem(at: url, to: dest)
  /// ```
  @discardableResult
  public func download(
    path: String,
    options: TransformOptions? = nil,
    query additionalQueryItems: [URLQueryItem]? = nil,
    cacheNonce: String? = nil
  ) -> StorageDownloadTask {
    let url = _downloadURL(
      path: path, options: options, query: additionalQueryItems, cacheNonce: cacheNonce)
    // Use http.createRequest so the token provider is called before the
    // URLSession download task is created — client.mergedHeaders alone strips
    // the Authorization header when a token provider is configured.
    return client.downloadDelegate.makeStorageDownloadTask(in: client.downloadSession) {
      try await client.http.createRequest(.get, url: url, headers: client.mergedHeaders([:]))
    }
  }

  /// Downloads a file into memory as `Data`.
  ///
  /// The entire file is held in memory, so prefer ``download(path:options:)`` for large files or
  /// when you need background transfer support.
  ///
  /// - Parameters:
  ///   - path: Path within the bucket, e.g. `"folder/image.png"`.
  ///   - options: Optional on-the-fly image transformation.
  ///   - query: Additional query items appended to the request URL.
  ///   - cacheNonce: An opaque string appended as `cacheNonce=<value>` for cache busting.
  /// - Returns: A task whose success value is the raw file bytes.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let data = try await storage.from("avatars").downloadData(path: "user-123/photo.png").value
  /// let image = UIImage(data: data)
  /// ```
  @discardableResult
  public func downloadData(
    path: String,
    options: TransformOptions? = nil,
    query additionalQueryItems: [URLQueryItem]? = nil,
    cacheNonce: String? = nil
  ) -> StorageTransferTask<Data> {
    download(path: path, options: options, query: additionalQueryItems, cacheNonce: cacheNonce)
      .mapResult { url in
        defer { try? FileManager.default.removeItem(at: url) }
        return try Data(contentsOf: url)
      }
  }

  private func _downloadURL(
    path: String,
    options: TransformOptions?,
    query additionalQueryItems: [URLQueryItem]? = nil,
    cacheNonce: String? = nil
  ) -> URL {
    let finalPath = _getFinalPath(_removeEmptyFolders(path))

    var queryItems = options?.queryItems ?? []
    if let additionalQueryItems { queryItems.append(contentsOf: additionalQueryItems) }
    if let cacheNonce { queryItems.append(URLQueryItem(name: "cacheNonce", value: cacheNonce)) }

    let basePath =
      options.map { !$0.isEmpty } == true
      ? "render/image/authenticated/\(finalPath)"
      : "object/\(finalPath)"

    if queryItems.isEmpty {
      return client.url.appendingPathComponent(basePath)
    }

    var components = URLComponents(
      url: client.url.appendingPathComponent(basePath),
      resolvingAgainstBaseURL: false
    )
    components?.queryItems = queryItems
    return components?.url ?? client.url.appendingPathComponent(basePath)
  }

  /// Retrieves extended metadata for a file without downloading its contents.
  ///
  /// Returns a ``FileInfo`` that includes the file size, ETag, content type, and other
  /// server-side metadata. To check only whether a file exists, prefer ``exists(path:)``.
  ///
  /// - Parameter path: The path of the file within the bucket, e.g. `"folder/image.png"`.
  /// - Returns: A ``FileInfo`` containing the file's metadata.
  /// - Throws: ``StorageError`` if the file does not exist or the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let info = try await storage.from("avatars").info(path: "user-123/photo.png")
  /// print("Size: \(info.size ?? 0) bytes, type: \(info.contentType ?? "unknown")")
  /// ```
  public func info(path: String) async throws -> FileInfo {
    let _path = _getFinalPath(path)

    return try await client.fetchDecoded(.get, "object/info/\(_path)")
  }

  /// Checks whether a file exists in the bucket.
  ///
  /// Issues a `HEAD` request and returns `true` if the server responds with a success status,
  /// `false` if the server returns 400 or 404. Any other error is re-thrown.
  ///
  /// - Parameter path: The path of the file within the bucket, e.g. `"folder/image.png"`.
  /// - Returns: `true` if the file exists, `false` if it does not.
  /// - Throws: ``StorageError`` for server errors other than 400/404.
  ///
  /// ## Example
  ///
  /// ```swift
  /// if try await storage.from("avatars").exists(path: "user-123/photo.png") {
  ///   print("File found")
  /// } else {
  ///   print("File not found")
  /// }
  /// ```
  public func exists(path: String) async throws -> Bool {
    do {
      try await client.fetchData(.head, "object/\(bucketId)/\(path)")
      return true
    } catch let error as StorageError
      where error.isNotFound || error.statusCode == 400
    {
      // The Storage server returns 400 (instead of 404) for HEAD requests on non-existent objects.
      return false
    }
  }

  /// Returns the public URL for a file in a public bucket.
  ///
  /// The bucket must be configured as public; for private buckets use
  /// ``createSignedURL(path:expiresIn:download:transform:cacheNonce:)`` instead.
  ///
  /// - Parameters:
  ///   - path: The path of the file within the bucket, e.g. `"user-123/avatar.png"`.
  ///   - download: When non-`nil`, the browser treats the URL as a file download.
  ///   - options: Optional on-the-fly image transformation (resize, reformat, quality).
  ///   - cacheNonce: An opaque string appended as a `cacheNonce` query parameter.
  /// - Returns: The public `URL` for the file.
  /// - Throws: `URLError(.badURL)` if the resulting URL cannot be constructed.
  ///
  /// ## Example
  ///
  /// ```swift
  /// // Direct embed URL
  /// let url = try storage.from("avatars").getPublicURL(path: "user-123/photo.png")
  ///
  /// // 200×200 thumbnail in WebP
  /// let thumbURL = try storage.from("avatars").getPublicURL(
  ///   path: "user-123/photo.png",
  ///   options: TransformOptions(width: 200, height: 200, format: .webp)
  /// )
  /// ```
  public func getPublicURL(
    path: String,
    download: DownloadBehavior? = nil,
    options: TransformOptions? = nil,
    cacheNonce: String? = nil
  ) throws -> URL {
    var queryItems: [URLQueryItem] = []

    guard
      var components = URLComponents(
        url: client.url,
        resolvingAgainstBaseURL: true
      )
    else {
      throw URLError(.badURL)
    }

    if let download {
      let value: String
      switch download {
      case .withOriginalName: value = ""
      case .named(let name): value = name
      }
      queryItems.append(URLQueryItem(name: "download", value: value))
    }

    if let optionsQueryItems = options?.queryItems {
      queryItems.append(contentsOf: optionsQueryItems)
    }

    if let cacheNonce {
      queryItems.append(URLQueryItem(name: "cacheNonce", value: cacheNonce))
    }

    let renderPath =
      options.map { !$0.isEmpty } == true ? "render/image" : "object"
    components.path += "/\(renderPath)/public/\(bucketId)/\(path)"
    components.queryItems = !queryItems.isEmpty ? queryItems : nil

    guard let generatedUrl = components.url else {
      throw URLError(.badURL)
    }
    return generatedUrl
  }

  /// Creates a signed upload URL for uploading a file without further authentication.
  ///
  /// Signed upload URLs are valid for **2 hours** and allow anyone in possession of the URL to
  /// upload a file to the specified path. This is useful for client-side uploads where you do not
  /// want to expose Storage credentials.
  ///
  /// After calling this method, pass the returned ``SignedUploadURL/token`` to
  /// ``uploadToSignedURL(_:token:data:options:)`` or
  /// ``uploadToSignedURL(_:token:fileURL:options:)`` to perform the actual upload.
  ///
  /// - Parameters:
  ///   - path: The destination path within the bucket, e.g. `"user-123/upload.png"`.
  ///   - options: Optional overrides, such as enabling upsert behaviour.
  /// - Returns: A ``SignedUploadURL`` containing the signed URL, path, and extracted token.
  /// - Throws: ``StorageError`` if the request fails.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let signed = try await storage.from("uploads").createSignedUploadURL(path: "user-123/photo.png")
  ///
  /// // Later, upload the file using the signed token
  /// try await storage.from("uploads").uploadToSignedURL(
  ///   signed.path,
  ///   token: signed.token,
  ///   data: imageData,
  ///   options: FileOptions(contentType: "image/png")
  /// )
  /// ```
  public func createSignedUploadURL(
    path: String,
    options: CreateSignedUploadURLOptions? = nil
  ) async throws -> SignedUploadURL {
    struct Response: Decodable {
      let url: String
    }

    var headers = [String: String]()
    if let upsert = options?.upsert, upsert {
      headers[Header.xUpsert] = "true"
    }

    let response: Response = try await client.fetchDecoded(
      .post,
      "object/upload/sign/\(bucketId)/\(path)",
      headers: headers
    )

    let signedURL = try makeSignedURL(response.url, download: nil)

    guard
      let components = URLComponents(
        url: signedURL,
        resolvingAgainstBaseURL: false
      )
    else {
      throw URLError(.badURL)
    }

    guard
      let token = components.queryItems?.first(where: { $0.name == "token" })?
        .value
    else {
      throw StorageError.noTokenReturned
    }

    guard let url = components.url else {
      throw URLError(.badURL)
    }

    return SignedUploadURL(
      signedURL: url,
      path: path,
      token: token
    )
  }

  /// Uploads `Data` to a path using a token obtained from ``createSignedUploadURL(path:options:)``.
  ///
  /// The token must match the path and must not have expired (signed upload URLs are valid for
  /// 2 hours).
  ///
  /// - Parameters:
  ///   - path: The destination path within the bucket, matching the path used when the token
  ///     was created.
  ///   - token: The upload token from ``SignedUploadURL/token``.
  ///   - data: The raw file bytes to store.
  ///   - options: Upload options such as content type and cache duration.
  /// - Returns: A ``StorageTransferTask`` that can be awaited for the ``SignedURLUploadResponse``
  ///   result, or observed for progress.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let signed = try await storage.from("uploads").createSignedUploadURL(path: "file.pdf")
  /// let response = try await storage.from("uploads").uploadToSignedURL(
  ///   signed.path,
  ///   token: signed.token,
  ///   data: pdfData,
  ///   options: FileOptions(contentType: "application/pdf")
  /// ).value
  /// print(response.fullPath)
  /// ```
  @discardableResult
  public func uploadToSignedURL(
    _ path: String,
    token: String,
    data: Data,
    options: FileOptions = FileOptions()
  ) -> StorageTransferTask<SignedURLUploadResponse> {
    makeSignedURLUploadTask {
      try await self._uploadToSignedURL(
        path: path,
        token: token,
        file: .data(data),
        options: options
      )
    }
  }

  /// Uploads a file from a local `URL` to a path using a token obtained from
  /// ``createSignedUploadURL(path:options:)``.
  ///
  /// For files ≥ 10 MB the SDK automatically streams from a temporary file on disk to avoid
  /// loading the entire payload into memory.
  ///
  /// - Parameters:
  ///   - path: The destination path within the bucket, matching the path used when the token
  ///     was created.
  ///   - token: The upload token from ``SignedUploadURL/token``.
  ///   - fileURL: A local `file://` URL pointing to the file to upload.
  ///   - options: Upload options such as content type and cache duration.
  ///     When `contentType` is `nil`, the MIME type is inferred from the file extension.
  /// - Returns: A ``StorageTransferTask`` that can be awaited for the ``SignedURLUploadResponse``
  ///   result, or observed for progress.
  ///
  /// ## Example
  ///
  /// ```swift
  /// let fileURL = URL(fileURLWithPath: "/tmp/video.mp4")
  /// let signed = try await storage.from("uploads").createSignedUploadURL(path: "user-123/video.mp4")
  /// let response = try await storage.from("uploads").uploadToSignedURL(
  ///   signed.path,
  ///   token: signed.token,
  ///   fileURL: fileURL
  /// ).value
  /// ```
  @discardableResult
  public func uploadToSignedURL(
    _ path: String,
    token: String,
    fileURL: URL,
    options: FileOptions = FileOptions()
  ) -> StorageTransferTask<SignedURLUploadResponse> {
    makeSignedURLUploadTask {
      try await self._uploadToSignedURL(
        path: path,
        token: token,
        file: .fileURL(fileURL),
        options: options
      )
    }
  }

  private func makeSignedURLUploadTask(
    _ body: @Sendable @escaping () async throws -> SignedURLUploadResponse
  ) -> StorageTransferTask<SignedURLUploadResponse> {
    let (eventStream, eventsContinuation) =
      AsyncStream<TransferEvent<SignedURLUploadResponse>>.makeStream()
    let (resultStream, resultContinuation) =
      AsyncStream<Result<SignedURLUploadResponse, any Error>>.makeStream(
        bufferingPolicy: .bufferingNewest(1))

    let resultTask = Task<SignedURLUploadResponse, any Error> {
      for await r in resultStream { return try r.get() }
      throw StorageError.cancelled
    }

    let uploadTask = Task {
      do {
        let response = try await body()
        eventsContinuation.yield(.completed(response))
        eventsContinuation.finish()
        resultContinuation.yield(.success(response))
        resultContinuation.finish()
      } catch {
        let storageError = StorageError.from(error)
        eventsContinuation.yield(.failed(storageError))
        eventsContinuation.finish()
        resultContinuation.yield(.failure(storageError))
        resultContinuation.finish()
      }
    }

    return StorageTransferTask<SignedURLUploadResponse>(
      events: eventStream,
      resultTask: resultTask,
      pause: {},
      resume: {},
      cancel: { uploadTask.cancel() }
    )
  }

  private func _uploadToSignedURL(
    path: String,
    token: String,
    file: UploadSource,
    options: FileOptions
  ) async throws -> SignedURLUploadResponse {
    var headers = multipartHeaders(options: options)
    headers[Header.xUpsert] = "\(options.upsert)"

    let response: SignedUploadResponse = try await _performMultipartRequest(
      .put,
      url: storageURL(
        path: "object/upload/sign/\(bucketId)/\(path)",
        queryItems: [URLQueryItem(name: "token", value: token)]
      ),
      path: path,
      file: file,
      options: options,
      headers: headers
    )

    return SignedURLUploadResponse(path: path, fullPath: response.Key)
  }

  private func _performMultipartRequest<Response: Decodable>(
    _ method: HTTPMethod,
    url: URL,
    path: String,
    file: UploadSource,
    options: FileOptions,
    headers: [String: String]
  ) async throws -> Response {
    #if DEBUG
      let builder = MultipartBuilder(
        boundary: testingBoundary.value ?? "----sb-\(UUID().uuidString)"
      )
    #else
      let builder = MultipartBuilder()
    #endif

    let multipart = file.append(
      to: builder,
      withPath: path,
      options: options
    )

    var headers = headers
    headers[Header.contentType] = multipart.contentType

    let request = try await client.http.createRequest(
      method,
      url: url,
      headers: client.mergedHeaders(headers)
    )

    do {
      client.logRequest(method, url: url)
      let data: Data
      let response: URLResponse

      if file.usesTempFileUpload {
        let tempFile = try multipart.buildToTempFile()
        defer { try? FileManager.default.removeItem(at: tempFile) }

        (data, response) = try await client.http.session.upload(
          for: request,
          fromFile: tempFile
        )
      } else {
        (data, response) = try await client.http.session.upload(
          for: request,
          from: try multipart.buildInMemory()
        )
      }

      let httpResponse = try client.http.validateResponse(response, data: data)
      client.logResponse(httpResponse, data: data)
      return try client.decoder.decode(Response.self, from: data)
    } catch {
      client.logFailure(error)
      throw client.translateStorageError(error)
    }
  }

  private func multipartHeaders(options: FileOptions) -> [String: String] {
    var headers: [String: String] = [:]
    headers.setIfMissing(
      Header.cacheControl,
      value: "max-age=\(options.cacheControl)"
    )
    return headers
  }

  private func storageURL(path: String, queryItems: [URLQueryItem] = []) throws
    -> URL
  {
    var components = URLComponents(
      url: client.url.appendingPathComponent(path),
      resolvingAgainstBaseURL: false
    )
    components?.queryItems = queryItems.isEmpty ? nil : queryItems

    guard let url = components?.url else {
      throw URLError(.badURL)
    }

    return url
  }

  private func _getFinalPath(_ path: String) -> String {
    let trimmed = path.hasPrefix("/") ? String(path.dropFirst()) : path
    return "\(bucketId)/\(trimmed)"
  }
}

func _removeEmptyFolders(_ path: String) -> String {
  let trimmedPath = path.trimmingCharacters(in: CharacterSet(charactersIn: "/"))
  let cleanedPath = trimmedPath.replacingOccurrences(
    of: "/+",
    with: "/",
    options: .regularExpression
  )
  return cleanedPath
}

extension [String: String] {
  fileprivate mutating func setIfMissing(_ key: String, value: String) {
    guard
      keys.first(where: { $0.caseInsensitiveCompare(key) == .orderedSame })
        == nil
    else {
      return
    }

    self[key] = value
  }
}

supabase / supabase-swift / 28015504651

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous