Class: ActiveStorage::Blob
- Inherits:
-
ActiveRecord::Base
- Object
- ActiveRecord::Base
- ActiveStorage::Blob
- Includes:
- Analyzable, Identifiable, Representable
- Defined in:
- app/models/active_storage/blob.rb
Overview
A blob is a record that contains the metadata about a file and a key for where that file resides on the service. Blobs can be created in two ways:
-
Subsequent to the file being uploaded server-side to the service via
create_after_upload!
. -
Ahead of the file being directly uploaded client-side to the service via
create_before_direct_upload!
.
The first option doesn’t require any client-side JavaScript integration, and can be used by any other back-end service that deals with files. The second option is faster, since you’re not using your own server as a staging point for uploads, and can work with deployments like Heroku that do not provide large amounts of disk space.
Blobs are intended to be immutable in as-so-far as their reference to a specific file goes. You’re allowed to update a blob’s metadata on a subsequent pass, but you should not update the key or change the uploaded file. If you need to create a derivative or otherwise change the blob, simply create a new blob and purge the old one.
Defined Under Namespace
Modules: Analyzable, Identifiable, Representable
Class Method Summary collapse
-
.build_after_upload(io:, filename:, content_type: nil, metadata: nil) ⇒ Object
Returns a new, unsaved blob instance after the
io
has been uploaded to the service. -
.create_after_upload!(io:, filename:, content_type: nil, metadata: nil) ⇒ Object
Returns a saved blob instance after the
io
has been uploaded to the service. -
.create_before_direct_upload!(filename:, byte_size:, checksum:, content_type: nil, metadata: nil) ⇒ Object
Returns a saved blob without uploading a file to the service.
-
.find_signed(id) ⇒ Object
You can used the signed ID of a blob to refer to it on the client side without fear of tampering.
Instance Method Summary collapse
-
#audio? ⇒ Boolean
Returns true if the content_type of this blob is in the audio range, like audio/mpeg.
-
#delete ⇒ Object
Deletes the file on the service that’s associated with this blob.
-
#download(&block) ⇒ Object
Downloads the file associated with this blob.
-
#filename ⇒ Object
Returns an ActiveStorage::Filename instance of the filename that can be queried for basename, extension, and a sanitized version of the filename that’s safe to use in URLs.
-
#image? ⇒ Boolean
Returns true if the content_type of this blob is in the image range, like image/png.
-
#key ⇒ Object
Returns the key pointing to the file on the service that’s associated with this blob.
-
#purge ⇒ Object
Deletes the file on the service and then destroys the blob record.
-
#purge_later ⇒ Object
Enqueues an ActiveStorage::PurgeJob job that’ll call
purge
. -
#service_headers_for_direct_upload ⇒ Object
Returns a Hash of headers for
service_url_for_direct_upload
requests. -
#service_url(expires_in: service.url_expires_in, disposition: :inline, filename: nil, **options) ⇒ Object
Returns the URL of the blob on the service.
-
#service_url_for_direct_upload(expires_in: service.url_expires_in) ⇒ Object
Returns a URL that can be used to directly upload a file for this blob on the service.
-
#signed_id ⇒ Object
Returns a signed ID for this blob that’s suitable for reference on the client-side without fear of tampering.
-
#text? ⇒ Boolean
Returns true if the content_type of this blob is in the text range, like text/plain.
-
#upload(io) ⇒ Object
Uploads the
io
to the service on thekey
for this blob. -
#video? ⇒ Boolean
Returns true if the content_type of this blob is in the video range, like video/mp4.
Methods included from Representable
#preview, #previewable?, #representable?, #representation, #variable?, #variant
Methods included from Identifiable
Methods included from Analyzable
#analyze, #analyze_later, #analyzed?
Class Method Details
.build_after_upload(io:, filename:, content_type: nil, metadata: nil) ⇒ Object
Returns a new, unsaved blob instance after the io
has been uploaded to the service.
47 48 49 50 51 52 53 54 55 |
# File 'app/models/active_storage/blob.rb', line 47 def build_after_upload(io:, filename:, content_type: nil, metadata: nil) new.tap do |blob| blob.filename = filename blob.content_type = content_type blob. = blob.upload io end end |
.create_after_upload!(io:, filename:, content_type: nil, metadata: nil) ⇒ Object
Returns a saved blob instance after the io
has been uploaded to the service. Note, the blob is first built, then the io
is uploaded, then the blob is saved. This is done this way to avoid uploading (which may take time), while having an open database transaction.
60 61 62 |
# File 'app/models/active_storage/blob.rb', line 60 def create_after_upload!(io:, filename:, content_type: nil, metadata: nil) build_after_upload(io: io, filename: filename, content_type: content_type, metadata: ).tap(&:save!) end |
.create_before_direct_upload!(filename:, byte_size:, checksum:, content_type: nil, metadata: nil) ⇒ Object
Returns a saved blob without uploading a file to the service. This blob will point to a key where there is no file yet. It’s intended to be used together with a client-side upload, which will first create the blob in order to produce the signed URL for uploading. This signed URL points to the key generated by the blob. Once the form using the direct upload is submitted, the blob can be associated with the right record using the signed ID.
69 70 71 |
# File 'app/models/active_storage/blob.rb', line 69 def create_before_direct_upload!(filename:, byte_size:, checksum:, content_type: nil, metadata: nil) create! filename: filename, byte_size: byte_size, checksum: checksum, content_type: content_type, metadata: end |
.find_signed(id) ⇒ Object
You can used the signed ID of a blob to refer to it on the client side without fear of tampering. This is particularly helpful for direct uploads where the client-side needs to refer to the blob that was created ahead of the upload itself on form submission.
The signed ID is also used to create stable URLs for the blob through the BlobsController.
42 43 44 |
# File 'app/models/active_storage/blob.rb', line 42 def find_signed(id) find ActiveStorage.verifier.verify(id, purpose: :blob_id) end |
Instance Method Details
#audio? ⇒ Boolean
Returns true if the content_type of this blob is in the audio range, like audio/mpeg.
101 102 103 |
# File 'app/models/active_storage/blob.rb', line 101 def audio? content_type.start_with?("audio") end |
#delete ⇒ Object
Deletes the file on the service that’s associated with this blob. This should only be done if the blob is going to be deleted as well or you will essentially have a dead reference. It’s recommended to use the #purge
and #purge_later
methods in most circumstances.
168 169 170 171 |
# File 'app/models/active_storage/blob.rb', line 168 def delete service.delete(key) service.delete_prefixed("variants/#{key}/") if image? end |
#download(&block) ⇒ Object
Downloads the file associated with this blob. If no block is given, the entire file is read into memory and returned. That’ll use a lot of RAM for very large files. If a block is given, then the download is streamed and yielded in chunks.
160 161 162 |
# File 'app/models/active_storage/blob.rb', line 160 def download(&block) service.download key, &block end |
#filename ⇒ Object
Returns an ActiveStorage::Filename instance of the filename that can be queried for basename, extension, and a sanitized version of the filename that’s safe to use in URLs.
91 92 93 |
# File 'app/models/active_storage/blob.rb', line 91 def filename ActiveStorage::Filename.new(self[:filename]) end |
#image? ⇒ Boolean
Returns true if the content_type of this blob is in the image range, like image/png.
96 97 98 |
# File 'app/models/active_storage/blob.rb', line 96 def image? content_type.start_with?("image") end |
#key ⇒ Object
Returns the key pointing to the file on the service that’s associated with this blob. The key is in the standard secure-token format from Rails. So it’ll look like: XTAPjJCJiuDrLk3TmwyJGpUo. This key is not intended to be revealed directly to the user. Always refer to blobs using the signed_id or a verified form of the key.
83 84 85 86 |
# File 'app/models/active_storage/blob.rb', line 83 def key # We can't wait until the record is first saved to have a key for it self[:key] ||= self.class.generate_unique_secure_token end |
#purge ⇒ Object
Deletes the file on the service and then destroys the blob record. This is the recommended way to dispose of unwanted blobs. Note, though, that deleting the file off the service will initiate a HTTP connection to the service, which may be slow or prevented, so you should not use this method inside a transaction or in callbacks. Use #purge_later
instead.
176 177 178 179 |
# File 'app/models/active_storage/blob.rb', line 176 def purge delete destroy end |
#purge_later ⇒ Object
Enqueues an ActiveStorage::PurgeJob job that’ll call purge
. This is the recommended way to purge blobs when the call needs to be made from a transaction, a callback, or any other real-time scenario.
183 184 185 |
# File 'app/models/active_storage/blob.rb', line 183 def purge_later ActiveStorage::PurgeJob.perform_later(self) end |
#service_headers_for_direct_upload ⇒ Object
Returns a Hash of headers for service_url_for_direct_upload
requests.
134 135 136 |
# File 'app/models/active_storage/blob.rb', line 134 def service_headers_for_direct_upload service.headers_for_direct_upload key, filename: filename, content_type: content_type, content_length: byte_size, checksum: checksum end |
#service_url(expires_in: service.url_expires_in, disposition: :inline, filename: nil, **options) ⇒ Object
Returns the URL of the blob on the service. This URL is intended to be short-lived for security and not used directly with users. Instead, the service_url
should only be exposed as a redirect from a stable, possibly authenticated URL. Hiding the service_url
behind a redirect also gives you the power to change services without updating all URLs. And it allows permanent URLs that redirect to the service_url
to be cached in the view.
120 121 122 123 124 125 |
# File 'app/models/active_storage/blob.rb', line 120 def service_url(expires_in: service.url_expires_in, disposition: :inline, filename: nil, **) filename = ActiveStorage::Filename.wrap(filename || self.filename) service.url key, expires_in: expires_in, filename: filename, content_type: content_type, disposition: forcibly_serve_as_binary? ? :attachment : disposition, ** end |
#service_url_for_direct_upload(expires_in: service.url_expires_in) ⇒ Object
Returns a URL that can be used to directly upload a file for this blob on the service. This URL is intended to be short-lived for security and only generated on-demand by the client-side JavaScript responsible for doing the uploading.
129 130 131 |
# File 'app/models/active_storage/blob.rb', line 129 def service_url_for_direct_upload(expires_in: service.url_expires_in) service.url_for_direct_upload key, expires_in: expires_in, content_type: content_type, content_length: byte_size, checksum: checksum end |
#signed_id ⇒ Object
Returns a signed ID for this blob that’s suitable for reference on the client-side without fear of tampering. It uses the framework-wide verifier on ActiveStorage.verifier
, but with a dedicated purpose.
76 77 78 |
# File 'app/models/active_storage/blob.rb', line 76 def signed_id ActiveStorage.verifier.generate(id, purpose: :blob_id) end |
#text? ⇒ Boolean
Returns true if the content_type of this blob is in the text range, like text/plain.
111 112 113 |
# File 'app/models/active_storage/blob.rb', line 111 def text? content_type.start_with?("text") end |
#upload(io) ⇒ Object
Uploads the io
to the service on the key
for this blob. Blobs are intended to be immutable, so you shouldn’t be using this method after a file has already been uploaded to fit with a blob. If you want to create a derivative blob, you should instead simply create a new blob based on the old one.
Prior to uploading, we compute the checksum, which is sent to the service for transit integrity validation. If the checksum does not match what the service receives, an exception will be raised. We also measure the size of the io
and store that in byte_size
on the blob record.
Normally, you do not have to call this method directly at all. Use the factory class methods of build_after_upload
and create_after_upload!
.
149 150 151 152 153 154 155 156 |
# File 'app/models/active_storage/blob.rb', line 149 def upload(io) self.checksum = compute_checksum_in_chunks(io) self.content_type = extract_content_type(io) self.byte_size = io.size self.identified = true service.upload(key, io, checksum: checksum) end |
#video? ⇒ Boolean
Returns true if the content_type of this blob is in the video range, like video/mp4.
106 107 108 |
# File 'app/models/active_storage/blob.rb', line 106 def video? content_type.start_with?("video") end |