edge badge

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. Subsequent to the file being uploaded server-side to the service via create_after_upload!.

  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.

Namespace
Methods
A
B
C
D
F
I
K
P
R
S
T
U
V
Class Public methods
build_after_upload(io:, filename:, content_type: nil, metadata: nil)

Returns a new, unsaved blob instance after the io has been uploaded to the service.

# File activestorage/app/models/active_storage/blob.rb, line 43
def build_after_upload(io,, filename,, content_type: nil, metadata: nil)
  new.tap do |blob|
    blob.filename     = filename
    blob.content_type = content_type
    blob.metadata     = metadata

    blob.upload io
  end
end
create_after_upload!(io:, filename:, content_type: nil, metadata: nil)

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.

# File activestorage/app/models/active_storage/blob.rb, line 56
def create_after_upload!(io,, filename,, content_type: nil, metadata: nil)
  build_after_upload(io: io, filename: filename, content_type: content_type, metadata: metadata).tap(&:save!)
end
create_before_direct_upload!(filename:, byte_size:, checksum:, content_type: nil, metadata: nil)

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.

# File activestorage/app/models/active_storage/blob.rb, line 65
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)

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.

# File activestorage/app/models/active_storage/blob.rb, line 38
def find_signed(id)
  find ActiveStorage.verifier.verify(id, purpose: :blob_id)
end
Instance Public methods
analyze()

Extracts and stores metadata from the file associated with this blob using a relevant analyzer. Active Storage comes with built-in analyzers for images and videos. See ActiveStorage::Analyzer::ImageAnalyzer and ActiveStorage::Analyzer::VideoAnalyzer for information about the specific attributes they extract and the third-party libraries they require.

To choose the analyzer for a blob, Active Storage calls accept? on each registered analyzer in order. It uses the first analyzer for which accept? returns true when given the blob. If no registered analyzer accepts the blob, no metadata is extracted from it.

In a Rails application, add or remove analyzers by manipulating Rails.application.config.active_storage.analyzers in an initializer:

# Add a custom analyzer for Microsoft Office documents:
Rails.application.config.active_storage.analyzers.append DOCXAnalyzer

# Remove the built-in video analyzer:
Rails.application.config.active_storage.analyzers.delete ActiveStorage::Analyzer::VideoAnalyzer

Outside of a Rails application, manipulate ActiveStorage.analyzers instead.

You won't ordinarily need to call this method from a Rails application. New blobs are automatically and asynchronously analyzed via analyze_later when they're attached for the first time.

# File activestorage/app/models/active_storage/blob.rb, line 250
def analyze
  update! metadata: metadata.merge(extract_metadata_via_analyzer)
end
analyze_later()

Enqueues an ActiveStorage::AnalyzeJob which calls analyze.

This method is automatically called for a blob when it's attached for the first time. You can call it to analyze a blob again (e.g. if you add a new analyzer or modify an existing one).

# File activestorage/app/models/active_storage/blob.rb, line 258
def analyze_later
  ActiveStorage::AnalyzeJob.perform_later(self)
end
analyzed?()

Returns true if the blob has been analyzed.

# File activestorage/app/models/active_storage/blob.rb, line 263
def analyzed?
  analyzed
end
audio?()

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

# File activestorage/app/models/active_storage/blob.rb, line 98
def audio?
  content_type.start_with?("audio")
end
delete()

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.

# File activestorage/app/models/active_storage/blob.rb, line 271
def delete
  service.delete(key)
  service.delete_prefixed("variants/#{key}/") if image?
end
download(&block)

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.

# File activestorage/app/models/active_storage/blob.rb, line 223
def download(&block)
  service.download key, &block
end
filename()

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.

# File activestorage/app/models/active_storage/blob.rb, line 88
def filename
  ActiveStorage::Filename.new(self[:filename])
end
image?()

Returns true if the content_type of this blob is in the image range, like image/png.

# File activestorage/app/models/active_storage/blob.rb, line 93
def image?
  content_type.start_with?("image")
end
key()

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.

# File activestorage/app/models/active_storage/blob.rb, line 80
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
preview(transformations)

Returns an ActiveStorage::Preview instance with the set of transformations provided. A preview is an image generated from a non-image blob. Active Storage comes with built-in previewers for videos and PDF documents. The video previewer extracts the first frame from a video and the PDF previewer extracts the first page from a PDF document.

blob.preview(resize: "100x100").processed.service_url

Avoid processing previews synchronously in views. Instead, link to a controller action that processes them on demand. Active Storage provides one, but you may want to create your own (for example, if you need authentication). Here’s how to use the built-in version:

<%= image_tag video.preview(resize: "100x100") %>

This method raises ActiveStorage::Blob::UnpreviewableError if no previewer accepts the receiving blob. To determine whether a blob is accepted by any previewer, call #previewable?.

# File activestorage/app/models/active_storage/blob.rb, line 146
def preview(transformations)
  if previewable?
    ActiveStorage::Preview.new(self, ActiveStorage::Variation.wrap(transformations))
  else
    raise UnpreviewableError
  end
end
previewable?()

Returns true if any registered previewer accepts the blob. By default, this will return true for videos and PDF documents.

# File activestorage/app/models/active_storage/blob.rb, line 155
def previewable?
  ActiveStorage.previewers.any? { |klass| klass.accept?(self) }
end
purge()

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.

# File activestorage/app/models/active_storage/blob.rb, line 279
def purge
  delete
  destroy
end
purge_later()

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.

# File activestorage/app/models/active_storage/blob.rb, line 286
def purge_later
  ActiveStorage::PurgeJob.perform_later(self)
end
representable?()

Returns true if the blob is an image or is previewable.

# File activestorage/app/models/active_storage/blob.rb, line 180
def representable?
  image? || previewable?
end
representation(transformations)

Returns an ActiveStorage::Preview instance for a previewable blob or an ActiveStorage::Variant instance for an image blob.

blob.representation(resize: "100x100").processed.service_url

Raises ActiveStorage::Blob::UnrepresentableError if the receiving blob is neither an image nor previewable. Call #representable? to determine whether a blob is representable.

See #preview and #variant for more information.

# File activestorage/app/models/active_storage/blob.rb, line 168
def representation(transformations)
  case
  when previewable?
    preview transformations
  when image?
    variant transformations
  else
    raise UnrepresentableError
  end
end
service_headers_for_direct_upload()

Returns a Hash of headers for service_url_for_direct_upload requests.

# File activestorage/app/models/active_storage/blob.rb, line 200
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")

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.

# File activestorage/app/models/active_storage/blob.rb, line 189
def service_url(expires_in: service.url_expires_in, disposition: "inline")
  service.url key, expires_in: expires_in, disposition: disposition, filename: filename, content_type: content_type
end
service_url_for_direct_upload(expires_in: service.url_expires_in)

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.

# File activestorage/app/models/active_storage/blob.rb, line 195
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()

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.

# File activestorage/app/models/active_storage/blob.rb, line 73
def signed_id
  ActiveStorage.verifier.generate(id, purpose: :blob_id)
end
text?()

Returns true if the content_type of this blob is in the text range, like text/plain.

# File activestorage/app/models/active_storage/blob.rb, line 108
def text?
  content_type.start_with?("text")
end
upload(io)

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

# File activestorage/app/models/active_storage/blob.rb, line 214
def upload(io)
  self.checksum  = compute_checksum_in_chunks(io)
  self.byte_size = io.size

  service.upload(key, io, checksum: checksum)
end
variant(transformations)

Returns an ActiveStorage::Variant instance with the set of transformations provided. This is only relevant for image files, and it allows any image to be transformed for size, colors, and the like. Example:

avatar.variant(resize: "100x100").processed.service_url

This will create and process a variant of the avatar blob that's constrained to a height and width of 100px. Then it'll upload said variant to the service according to a derivative key of the blob and the transformations.

Frequently, though, you don't actually want to transform the variant right away. But rather simply refer to a specific variant that can be created by a controller on-demand. Like so:

<%= image_tag Current.user.avatar.variant(resize: "100x100") %>

This will create a URL for that specific blob with that specific variant, which the ActiveStorage::VariantsController can then produce on-demand.

# File activestorage/app/models/active_storage/blob.rb, line 127
def variant(transformations)
  ActiveStorage::Variant.new(self, ActiveStorage::Variation.wrap(transformations))
end
video?()

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

# File activestorage/app/models/active_storage/blob.rb, line 103
def video?
  content_type.start_with?("video")
end