Repository navigation
Expand file tree
/
Copy pathStorageClient.swift
More file actions
252 lines (235 loc) · 9.35 KB
/
Copy pathStorageClient.swift
File metadata and controls
252 lines (235 loc) · 9.35 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
public import Foundation
public import HTTPTypes
public import Helpers
public import Logging
extension StorageClient {
/// Configuration for the Supabase Storage client.
///
/// Pass a ``StorageClient/Configuration`` to ``StorageClient/init(configuration:)`` to control
/// the Storage endpoint URL, authentication headers, and the underlying transport.
///
/// ```swift
/// let configuration = StorageClient.Configuration(
/// url: URL(string: "https://project.supabase.co/storage/v1")!,
/// headers: [.apikey: key],
/// http: HTTPClientConfiguration(
/// middlewares: [AccessTokenMiddleware { try await session.accessToken }]
/// )
/// )
/// let storage = try StorageClient(configuration: configuration)
/// ```
///
/// A user's token enters a request through the middleware chain in ``http``, never through a
/// configuration field: `AccessTokenMiddleware` resolves it for every request, so a token that
/// rotates is always current, and `SupabaseClient` installs the same middleware for its own
/// Storage client. A static `Authorization` in ``headers`` is sent as-is and wins over any
/// middleware, which only sets the header when the request has none.
///
/// ## Topics
///
/// ### Creating a configuration
///
/// - ``init(url:headers:usesNewHostname:http:logger:retryEnabled:clock:)``
///
/// ### Configuration properties
///
/// - ``url``
/// - ``headers``
/// - ``usesNewHostname``
/// - ``http``
/// - ``logger``
/// - ``retryEnabled``
/// - ``clock``
public struct Configuration: Sendable {
/// The base URL of the Storage API endpoint (e.g. `https://project.supabase.co/storage/v1`).
public var url: URL
/// HTTP headers sent with every request. `HTTPFields` matches names case-insensitively.
///
/// A static `Authorization` here wins over any middleware in ``http``. For a token that
/// rotates, leave it out and add an `AccessTokenMiddleware` instead.
public var headers: HTTPFields
/// When `true`, rewrites `project.supabase.co` hostnames to `project.storage.supabase.co`,
/// which disables request buffering and enables uploads larger than 50 GB.
public var usesNewHostname: Bool
/// How resumable uploads are chunked, retried and persisted.
///
/// - Warning: Experimental. See ``ResumableUpload``.
@_spi(Experimental) public var resumable = ResumableUploadConfiguration()
/// The transport and middleware chain every request goes through.
///
/// To send a user's access token, add an `AccessTokenMiddleware` to its middlewares. It runs
/// on every attempt, so a retried request gets a fresh token. A provider failure throws
/// ``StorageError`` with kind ``StorageError/Kind-swift.struct/accessToken``. An
/// `Authorization` header in ``headers`` wins over the middleware.
public var http: HTTPClientConfiguration
/// The logger used for debugging HTTP interactions. Defaults to a build-config-aware logger.
///
/// The client removes tokens, secrets, and URL query strings from each line before your handler
/// sees it, and tags the logger with the `system` metadata key set to `storage`.
public var logger: Logging.Logger
/// Whether transient failures of reads are retried. Defaults to `true`.
///
/// Only reads are replayed: `GET` and `HEAD` requests, ``StorageBucket/list(path:options:)``
/// and each page of ``StorageBucket/objects(prefix:options:)``, up to three attempts with
/// jittered backoff. Uploads, moves, copies, removals and bucket changes are never replayed.
public var retryEnabled: Bool
/// The clock the waits between retries sleep on.
///
/// Defaults to `ContinuousClock()`. Pass a `TestClock` to drive retries deterministically in
/// tests instead of waiting out real seconds. `TestClock` comes from
/// [swift-clocks](https://github.com/pointfreeco/swift-clocks); add it to your test target
/// yourself, as this package does not export it.
public var clock: any Clock<Duration>
/// Creates a configuration.
///
/// - Parameters:
/// - url: The base URL of the Storage API endpoint.
/// - headers: HTTP headers sent with every request.
/// - usesNewHostname: When `true`, the storage-specific hostname is used, enabling uploads
/// over 50 GB.
/// - http: The transport and middleware chain every request goes through.
/// - logger: The logger to use. Defaults to a build-config-aware logger; pass a logger backed
/// by `SwiftLogNoOpLogHandler` to disable logging entirely.
/// - retryEnabled: Whether transient failures of reads are retried.
/// - clock: The clock the waits between retries sleep on. Defaults to `ContinuousClock()`.
public init(
url: URL,
headers: HTTPFields = [:],
usesNewHostname: Bool = false,
http: HTTPClientConfiguration = .init(),
logger: Logging.Logger = supabaseDefaultLogger(label: "io.supabase.storage"),
retryEnabled: Bool = true,
clock: any Clock<Duration> = ContinuousClock()
) {
self.url = url
self.headers = headers
self.usesNewHostname = usesNewHostname
self.http = http
self.logger = logger
self.retryEnabled = retryEnabled
self.clock = clock
}
}
}
/// The top-level Supabase Storage client for managing buckets and files.
///
/// ``StorageClient`` provides bucket-management operations directly and a ``from(_:)``
/// method to obtain a ``StorageBucket`` scoped to a specific bucket.
///
/// Typically you obtain an instance via the main `SupabaseClient`:
///
/// ```swift
/// let client = try SupabaseClient(supabaseURL: url, supabaseKey: key)
/// let storage = client.storage
///
/// // Upload a file
/// try await storage.from("avatars").upload(path: "user123.png", data: imageData)
///
/// // List all buckets
/// let buckets = try await storage.listBuckets()
/// ```
///
/// ## Topics
///
/// ### Creating a client
///
/// - ``init(configuration:)``
///
/// ### Configuration
///
/// - ``configuration``
///
/// ### Customizing headers
///
/// - ``settingHeader(name:value:)``
///
/// ### Accessing buckets
///
/// - ``from(_:)``
///
/// ### Bucket management
///
/// - ``listBuckets(options:)``
/// - ``bucket(_:)``
/// - ``createBucket(_:options:)``
/// - ``updateBucket(_:options:)``
/// - ``emptyBucket(_:)``
/// - ``deleteBucket(_:)``
/// - ``purgeCache(bucket:transformationsOnly:)``
///
/// ### Bucket lifecycle
///
/// - ``lifecycle(forBucket:)``
/// - ``setLifecycle(_:forBucket:)``
/// - ``deleteLifecycle(forBucket:)``
public struct StorageClient: Sendable {
let api: StorageAPI
/// The configuration used to initialize this client instance.
public var configuration: Configuration { api.configuration }
/// Creates a ``StorageClient`` with the given configuration.
///
/// - Parameter configuration: The configuration that controls the endpoint URL, authentication
/// headers, and transport.
/// - Throws: ``StorageError`` with kind ``StorageError/Kind-swift.struct/invalidConfiguration``
/// if `configuration.url` has no scheme, no host, or cannot be split into components.
public init(configuration: Configuration) throws {
api = try StorageAPI(configuration: configuration)
}
init(api: StorageAPI) {
self.api = api
}
/// Returns a new ``StorageClient`` with an additional HTTP header merged into the
/// underlying configuration, included in all requests made by the returned instance (and by
/// ``StorageBucket`` instances subsequently obtained via ``from(_:)``).
///
/// Because ``StorageClient`` is an immutable value type, this method does not mutate
/// `self` — it returns a new instance. Discarding the return value is a no-op, so always use
/// the result:
///
/// ```swift
/// let storage = client.storage.settingHeader(
/// name: .init("X-Custom-Header")!, value: "x-custom-header")
/// ```
///
/// - Parameters:
/// - name: The header field. Names match case-insensitively.
/// - value: The value of the header field.
/// - Returns: A new ``StorageClient`` with the header merged into the configuration's
/// headers.
public func settingHeader(name: HTTPField.Name, value: String) -> Self {
StorageClient(api: api.settingHeader(name: name, value: value))
}
/// Returns a ``StorageBucket`` scoped to the given bucket.
///
/// Use the returned object to upload, download, list, move, copy, or delete files within the
/// specified bucket.
///
/// - Parameter id: The unique identifier of the bucket to operate on.
/// - Returns: A ``StorageBucket`` configured for the given bucket.
public func from(_ id: String) -> StorageBucket {
StorageBucket(id: id, api: api)
}
/// A client for managing vector buckets.
///
/// ```swift
/// try await client.storage.vectors.createBucket("documents")
/// let buckets = try await client.storage.vectors.listBuckets().page().vectorBuckets
/// ```
///
/// - Warning: Experimental. See ``StorageVectorsClient``.
@_spi(Experimental)
public var vectors: StorageVectorsClient {
StorageVectorsClient(api: api)
}
/// A client for managing analytics (Iceberg) buckets.
///
/// ```swift
/// try await client.storage.analytics.createBucket("events")
/// ```
///
/// - Warning: Experimental. See ``StorageAnalyticsClient``.
@_spi(Experimental)
public var analytics: StorageAnalyticsClient {
StorageAnalyticsClient(api: api)
}
}