Class: Supabase::Storage::FileApi

Inherits:
Object
  • Object
show all
Includes:
Request
Defined in:
lib/supabase/storage/file_api.rb

Overview

All file-level operations scoped to one bucket — upload / download / list / remove / move / copy / info / exists, plus signed/public URL helpers. Mirrors storage3’s SyncBucketActionsMixin + SyncBucketProxy.

Constructed via Client#from(bucket_id).

Constant Summary collapse

KNOWN_TRANSFORM_KEYS =

Mirrors storage3’s ‘TypedDict` `TransformOptions` (height, width, resize, format, quality). PyJWT-style: we don’t error on unknown keys at runtime —the user-facing API quietly drops them — but Ruby has no TypedDict, so we warn through ‘Kernel#warn` to flag typos like `:hieght` or stale keys.

%i[height width resize format quality].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, base_url, headers, session) ⇒ FileApi

Returns a new instance of FileApi.



30
31
32
33
34
35
 
# File 'lib/supabase/storage/file_api.rb', line 30

def initialize(id, base_url, headers, session)
  @id       = id
  @base_url = base_url.end_with?("/") ? base_url : "#{base_url}/"
  @headers  = headers
  @session  = session
end

Instance Attribute Details

#id ⇒ Object (readonly)

Returns the value of attribute id.



22
23
24
 
# File 'lib/supabase/storage/file_api.rb', line 22

def id
  @id
end

Instance Method Details

#copy(from_path, to_path) ⇒ Object 



127
128
129
130
 
# File 'lib/supabase/storage/file_api.rb', line 127

def copy(from_path, to_path)
  _request(:post, ["object", "copy"],
           json: { "bucketId" => @id, "sourceKey" => from_path, "destinationKey" => to_path })
end

#create_signed_upload_url(path, upsert: nil) ⇒ Object

Raises:



201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/supabase/storage/file_api.rb', line 201

def create_signed_upload_url(path, upsert: nil)
  headers = upsert.nil? ? {} : { "x-upsert" => upsert.to_s }
  parts   = Utils.relative_path_to_parts(path)
  body    = _request(:post, ["object", "upload", "sign", @id, *parts], headers: headers)

  signed_url = "#{@base_url.chomp('/')}#{body['url']}"
  token = URI.decode_www_form(URI.parse(signed_url).query.to_s).to_h["token"]
  raise Errors::StorageError, "No token sent by the API" if token.nil? || token.empty?

  Types::SignedUploadURL.new(signed_url: signed_url, token: token, path: path)
end

#create_signed_url(path, expires_in:, download: nil, transform: nil) ⇒ Hash

Returns { “signedURL” => “…”, “signedUrl” => “…” }.

Parameters:

  • expires_in (Integer) —

    seconds until the URL expires

  • download (Boolean, String, nil) (defaults to: nil) —

    ‘true` to force browser download with the original filename, a String to override the filename, or nil to leave inline

Returns:

  • (Hash) —

    { “signedURL” => “…”, “signedUrl” => “…” }



151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/supabase/storage/file_api.rb', line 151

def create_signed_url(path, expires_in:, download: nil, transform: nil)
  warn_unknown_transform_keys(transform) if transform
  json = { "expiresIn" => expires_in.to_s }
  download_query = {}
  if download
    json["download"] = download
    download_query["download"] = download == true ? "" : download
  end
  json["transform"] = transform if transform

  parts = Utils.relative_path_to_parts(path)
  body  = _request(:post, ["object", "sign", @id, *parts], json: json)
  wrap_signed_url(body["signedURL"] || body["signedUrl"], download_query)
end

#create_signed_urls(paths, expires_in:, download: nil) ⇒ Object 



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/supabase/storage/file_api.rb', line 166

def create_signed_urls(paths, expires_in:, download: nil)
  json = { "paths" => Array(paths), "expiresIn" => expires_in.to_s }
  download_query = {}
  if download
    json["download"] = download
    download_query["download"] = download == true ? "" : download
  end

  items = _request(:post, ["object", "sign", @id], json: json)
  Array(items).map do |item|
    wrapped = wrap_signed_url(item["signedURL"] || item["signedUrl"], download_query)
    {
      "error"     => item["error"],
      "path"      => item["path"],
      "signedURL" => wrapped["signedURL"],
      "signedUrl" => wrapped["signedURL"]
    }
  end
end

#download(path, transform: nil, query_params: nil) ⇒ Object

When ‘transform:` is provided, the request is routed through the image rendering endpoint (`render/image/authenticated`) and the transform opts are passed as query params. `query_params:` adds arbitrary query params on top (merged after transform — explicit query_params win on conflict). Mirrors supabase-py’s DownloadOptions / TransformOptions split.



67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/supabase/storage/file_api.rb', line 67

def download(path, transform: nil, query_params: nil)
  warn_unknown_transform_keys(transform) if transform
  render_path = transform ? %w[render image authenticated] : %w[object]
  query = {}
  query.merge!(transform.transform_keys(&:to_s).transform_values(&:to_s)) if transform
  query.merge!(query_params.transform_keys(&:to_s).transform_values(&:to_s)) if query_params

  parts = Utils.relative_path_to_parts(path)
  response = _request(:get, [*render_path, @id, *parts], raw_response: true, query: query)
  response.body
end

#exists?(path) ⇒ Boolean

Returns:

  • (Boolean) 


137
138
139
140
141
142
143
 
# File 'lib/supabase/storage/file_api.rb', line 137

def exists?(path)
  parts = Utils.relative_path_to_parts(path)
  response = _request(:head, ["object", @id, *parts], raw_response: true)
  response.status == 200
rescue Errors::StorageApiError
  false
end

#get_public_url(path, download: nil, transform: nil) ⇒ Object 



186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/supabase/storage/file_api.rb', line 186

def get_public_url(path, download: nil, transform: nil)
  warn_unknown_transform_keys(transform) if transform
  download_query = {}
  if download
    download_query["download"] = download == true ? "" : download
  end

  render_path = transform ? %w[render image] : %w[object]
  transform_query = transform ? transform.transform_keys(&:to_s).transform_values(&:to_s) : {}
  query = download_query.merge(transform_query)

  parts = Utils.relative_path_to_parts(path)
  Utils.join_url(@base_url, [*render_path, "public", @id, *parts], query)
end

#info(path) ⇒ Object 



132
133
134
135
 
# File 'lib/supabase/storage/file_api.rb', line 132

def info(path)
  parts = Utils.relative_path_to_parts(path)
  _request(:get, ["object", "info", @id, *parts])
end

#list(prefix = nil, limit: nil, offset: nil, sort_by: nil, search: nil) ⇒ Object

Parameters:

  • prefix (String, nil) (defaults to: nil) —

    folder path to list under

  • limit (Integer) (defaults to: nil)
  • offset (Integer) (defaults to: nil)
  • sort_by (Hash) (defaults to: nil) —

    order:

  • search (String, nil) (defaults to: nil) 


86
87
88
89
90
91
92
93
94
 
# File 'lib/supabase/storage/file_api.rb', line 86

def list(prefix = nil, limit: nil, offset: nil, sort_by: nil, search: nil)
  body = Types::DEFAULT_SEARCH_OPTIONS.dup
  body["limit"]  = limit  unless limit.nil?
  body["offset"] = offset unless offset.nil?
  body["sortBy"] = stringify_sort_by(sort_by) if sort_by
  body["search"] = search unless search.nil?
  body["prefix"] = prefix || ""
  _request(:post, ["object", "list", @id], json: body, headers: { "Content-Type" => "application/json" })
end

#list_v2(prefix: nil, limit: nil, cursor: nil, with_delimiter: nil, sort_by: nil) ⇒ Types::SearchV2Result

Cursor-paginated list. Mirrors storage3’s list_v2 — only sends the keys the caller passed (no DEFAULT_SEARCH_OPTIONS merge).

Parameters:

  • prefix (String, nil) (defaults to: nil)
  • limit (Integer, nil) (defaults to: nil)
  • cursor (String, nil) (defaults to: nil) —

    opaque cursor returned by a previous call

  • with_delimiter (Boolean, nil) (defaults to: nil) —

    if true, server groups by “/” into folders

  • sort_by (Hash, nil) (defaults to: nil) —

    order:

Returns:



104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/supabase/storage/file_api.rb', line 104

def list_v2(prefix: nil, limit: nil, cursor: nil, with_delimiter: nil, sort_by: nil)
  body = {}
  body["prefix"]         = prefix         unless prefix.nil?
  body["limit"]          = limit          unless limit.nil?
  body["cursor"]         = cursor         unless cursor.nil?
  body["with_delimiter"] = with_delimiter unless with_delimiter.nil?
  body["sortBy"]         = stringify_sort_by(sort_by) if sort_by
  data = _request(:post, ["object", "list-v2", @id], json: body,
                                                     headers: { "Content-Type" => "application/json" })
  Types::SearchV2Result.from_hash(data)
end

#move(from_path, to_path) ⇒ Object 



122
123
124
125
 
# File 'lib/supabase/storage/file_api.rb', line 122

def move(from_path, to_path)
  _request(:post, ["object", "move"],
           json: { "bucketId" => @id, "sourceKey" => from_path, "destinationKey" => to_path })
end

#remove(paths) ⇒ Object

—– Remove / Move / Copy / Info / Exists —–



118
119
120
 
# File 'lib/supabase/storage/file_api.rb', line 118

def remove(paths)
  _request(:delete, ["object", @id], json: { "prefixes" => Array(paths) })
end

#update(path, file, content_type: nil, cache_control: nil, metadata: nil, headers: nil) ⇒ Object 



53
54
55
56
57
58
 
# File 'lib/supabase/storage/file_api.rb', line 53

def update(path, file, content_type: nil, cache_control: nil, metadata: nil, headers: nil)
  # Per Python: PUT never sends x-upsert.
  upload_or_update(:put, path, file,
                   content_type: content_type, cache_control: cache_control,
                   upsert: false, metadata: metadata, headers: headers, omit_upsert: true)
end

#upload(path, file, content_type: nil, cache_control: nil, upsert: false, metadata: nil, headers: nil) ⇒ Types::UploadResponse

Parameters:

  • path (String) —

    destination path within the bucket (e.g. “folder/avatar.png”)

  • file (String, IO, Pathname) —

    bytes / file-like object / path on disk

  • content_type (String, nil) (defaults to: nil)
  • cache_control (String, Integer, nil) (defaults to: nil) —

    becomes “max-age=<n>”

  • upsert (Boolean) (defaults to: false)
  • metadata (Hash, nil) (defaults to: nil) —

    base64-encoded into the x-metadata header

  • headers (Hash, nil) (defaults to: nil) —

    extra HTTP headers to send

Returns:



47
48
49
50
51
 
# File 'lib/supabase/storage/file_api.rb', line 47

def upload(path, file, content_type: nil, cache_control: nil, upsert: false, metadata: nil, headers: nil)
  upload_or_update(:post, path, file,
                   content_type: content_type, cache_control: cache_control,
                   upsert: upsert, metadata: metadata, headers: headers)
end

#upload_to_signed_url(path, token:, file:, content_type: nil, cache_control: nil, metadata: nil, headers: nil) ⇒ Object 



213
214
215
216
217
218
219
220
 
# File 'lib/supabase/storage/file_api.rb', line 213

def upload_to_signed_url(path, token:, file:, content_type: nil, cache_control: nil, metadata: nil, headers: nil)
  parts = Utils.relative_path_to_parts(path)
  send_multipart(:put, ["object", "upload", "sign", @id, *parts],
                 file: file, filename: parts.last, content_type: content_type,
                 cache_control: cache_control, upsert: nil, metadata: metadata,
                 extra_headers: headers, query: { "token" => token },
                 relative_path: parts.join("/"))
end