Class: ActiveStorage::Blob

Inherits:
ActiveRecord::Base
  • Object
show all
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:

  1. Ahead of the file being uploaded server-side to the service, via create_and_upload!. A rewindable io with the file contents must be available at the server for this operation.

  2. 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

Instance Method Summary collapse

Methods included from Representable

#preview, #previewable?, #representable?, #representation, #variable?, #variant

Methods included from Identifiable

#identified?, #identify

Methods included from Analyzable

#analyze, #analyze_later, #analyzed?

Class Method Details

.build_after_unfurling(io:, filename:, content_type: nil, metadata: nil, identify: true) ⇒ Object

:nodoc:



61
62
63
64
65
 
# File 'app/models/active_storage/blob.rb', line 61

def build_after_unfurling(io:, filename:, content_type: nil, metadata: nil, identify: true) #:nodoc:
  new(filename: filename, content_type: content_type, metadata: metadata).tap do |blob|
    blob.unfurl(io, identify: identify)
  end
end

.build_after_upload(io:, filename:, content_type: nil, metadata: nil, identify: true) ⇒ Object

Returns a new, unsaved blob instance after the io has been uploaded to the service. When providing a content type, pass identify: false to bypass automatic content type inference.



55
56
57
58
59
 
# File 'app/models/active_storage/blob.rb', line 55

def build_after_upload(io:, filename:, content_type: nil, metadata: nil, identify: true)
  new(filename: filename, content_type: content_type, metadata: metadata).tap do |blob|
    blob.upload(io, identify: identify)
  end
end

.create_after_unfurling!(io:, filename:, content_type: nil, metadata: nil, identify: true, record: nil) ⇒ Object

:nodoc:



67
68
69
 
# File 'app/models/active_storage/blob.rb', line 67

def create_after_unfurling!(io:, filename:, content_type: nil, metadata: nil, identify: true, record: nil) #:nodoc:
  build_after_unfurling(io: io, filename: filename, content_type: content_type, metadata: metadata, identify: identify).tap(&:save!)
end

.create_and_upload!(io:, filename:, content_type: nil, metadata: nil, identify: true, record: nil) ⇒ Object Also known as: create_after_upload!

Creates a new blob instance and then uploads the contents of the given io to the service. The blob instance is saved before the upload begins to avoid clobbering another due to key collisions.

When providing a content type, pass identify: false to bypass automatic content type inference.



76
77
78
79
80
 
# File 'app/models/active_storage/blob.rb', line 76

def create_and_upload!(io:, filename:, content_type: nil, metadata: nil, identify: true, record: nil)
  create_after_unfurling!(io: io, filename: filename, content_type: content_type, metadata: metadata, identify: identify).tap do |blob|
    blob.upload_without_unfurling(io)
  end
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.



89
90
91
 
# File 'app/models/active_storage/blob.rb', line 89

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: metadata
end

.find_signed(id) ⇒ Object

You can use 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.



49
50
51
 
# File 'app/models/active_storage/blob.rb', line 49

def find_signed(id)
  find ActiveStorage.verifier.verify(id, purpose: :blob_id)
end

.generate_unique_secure_token ⇒ Object

To prevent problems with case-insensitive filesystems, especially in combination with databases which treat indices as case-sensitive, all blob keys generated are going to only contain the base-36 character alphabet and will therefore be lowercase. To maintain the same or higher amount of entropy as in the base-58 encoding used by `has_secure_token` the number of bytes used is increased to 28 from the standard 24



98
99
100
 
# File 'app/models/active_storage/blob.rb', line 98

def generate_unique_secure_token
  SecureRandom.base36(28)
end

Instance Method Details

#audio? ⇒ Boolean

Returns true if the content_type of this blob is in the audio range, like audio/mpeg.

Returns:

  • (Boolean) 


131
132
133
 
# File 'app/models/active_storage/blob.rb', line 131

def audio?
  content_type.start_with?("audio")
end

#delete ⇒ Object

Deletes the files on the service associated with the 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 #purge and #purge_later methods in most circumstances.



225
226
227
228
 
# File 'app/models/active_storage/blob.rb', line 225

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.



199
200
201
 
# File 'app/models/active_storage/blob.rb', line 199

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.



121
122
123
 
# File 'app/models/active_storage/blob.rb', line 121

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.

Returns:

  • (Boolean) 


126
127
128
 
# File 'app/models/active_storage/blob.rb', line 126

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 the secure-token format from Rails in lower case. So it'll look like: xtapjjcjiudrlk3tmwyjgpuobabd. 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.



113
114
115
116
 
# File 'app/models/active_storage/blob.rb', line 113

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

#open(tmpdir: nil, &block) ⇒ Object

Downloads the blob to a tempfile on disk. Yields the tempfile.

The tempfile's name is prefixed with ActiveStorage- and the blob's ID. Its extension matches that of the blob.

By default, the tempfile is created in Dir.tmpdir. Pass tmpdir: to create it in a different directory:

blob.open(tmpdir: "/path/to/tmp") do |file|
  # ...
end

The tempfile is automatically closed and unlinked after the given block is executed.

Raises ActiveStorage::IntegrityError if the downloaded data does not match the blob's checksum.



216
217
218
219
 
# File 'app/models/active_storage/blob.rb', line 216

def open(tmpdir: nil, &block)
  service.open key, checksum: checksum,
    name: [ "ActiveStorage-#{id}-", filename.extension_with_delimiter ], tmpdir: tmpdir, &block
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.



233
234
235
236
237
 
# File 'app/models/active_storage/blob.rb', line 233

def purge
  destroy
  delete
rescue ActiveRecord::InvalidForeignKey
end

#purge_later ⇒ Object

Enqueues an ActiveStorage::PurgeJob to call #purge. This is the recommended way to purge blobs from a transaction, an Active Record callback, or in any other real-time scenario.



241
242
243
 
# File 'app/models/active_storage/blob.rb', line 241

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.



164
165
166
 
# File 'app/models/active_storage/blob.rb', line 164

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: ActiveStorage.service_urls_expire_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.



150
151
152
153
154
155
 
# File 'app/models/active_storage/blob.rb', line 150

def service_url(expires_in: ActiveStorage.service_urls_expire_in, disposition: :inline, filename: nil, **options)
  filename = ActiveStorage::Filename.wrap(filename || self.filename)

  service.url key, expires_in: expires_in, filename: filename, content_type: content_type_for_service_url,
    disposition: forced_disposition_for_service_url || disposition, **options
end

#service_url_for_direct_upload(expires_in: ActiveStorage.service_urls_expire_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.



159
160
161
 
# File 'app/models/active_storage/blob.rb', line 159

def service_url_for_direct_upload(expires_in: ActiveStorage.service_urls_expire_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.



105
106
107
 
# File 'app/models/active_storage/blob.rb', line 105

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.

Returns:

  • (Boolean) 


141
142
143
 
# File 'app/models/active_storage/blob.rb', line 141

def text?
  content_type.start_with?("text")
end

#unfurl(io, identify: true) ⇒ Object

:nodoc:



186
187
188
189
190
191
 
# File 'app/models/active_storage/blob.rb', line 186

def unfurl(io, identify: true) #:nodoc:
  self.checksum     = compute_checksum_in_chunks(io)
  self.content_type = extract_content_type(io) if content_type.nil? || identify
  self.byte_size    = io.size
  self.identified   = true
end

#upload(io, identify: true) ⇒ 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. The content type is automatically extracted from the io unless you specify a content_type and pass identify as false.

Normally, you do not have to call this method directly at all. Use the create_and_upload! class method instead. If you do use this method directly, make sure you are using it on a persisted Blob as otherwise another blob's data might get overwritten on the service.



181
182
183
184
 
# File 'app/models/active_storage/blob.rb', line 181

def upload(io, identify: true)
  unfurl io, identify: identify
  upload_without_unfurling io
end

#upload_without_unfurling(io) ⇒ Object

:nodoc:



193
194
195
 
# File 'app/models/active_storage/blob.rb', line 193

def upload_without_unfurling(io) #:nodoc:
  service.upload key, io, checksum: checksum, **service_metadata
end

#video? ⇒ Boolean

Returns true if the content_type of this blob is in the video range, like video/mp4.

Returns:

  • (Boolean) 


136
137
138
 
# File 'app/models/active_storage/blob.rb', line 136

def video?
  content_type.start_with?("video")
end