diff options
Diffstat (limited to 'activestorage/app')
6 files changed, 28 insertions, 32 deletions
diff --git a/activestorage/app/controllers/active_storage/disk_controller.rb b/activestorage/app/controllers/active_storage/disk_controller.rb index b10d4e2cac..dee88054da 100644 --- a/activestorage/app/controllers/active_storage/disk_controller.rb +++ b/activestorage/app/controllers/active_storage/disk_controller.rb @@ -33,7 +33,6 @@ class ActiveStorage::DiskController < ActionController::Base ActiveStorage::Blob.service end - def decode_verified_key ActiveStorage.verifier.verified(params[:encoded_key], purpose: :blob_key) end @@ -42,7 +41,6 @@ class ActiveStorage::DiskController < ActionController::Base params[:disposition].presence_in(%w( inline attachment )) || "inline" end - def decode_verified_token ActiveStorage.verifier.verified(params[:encoded_token], purpose: :blob_token) end diff --git a/activestorage/app/jobs/active_storage/purge_job.rb b/activestorage/app/jobs/active_storage/purge_job.rb index 404ccefd05..369c07929d 100644 --- a/activestorage/app/jobs/active_storage/purge_job.rb +++ b/activestorage/app/jobs/active_storage/purge_job.rb @@ -1,6 +1,6 @@ # frozen_string_literal: true -# Provides delayed purging of attachments or blobs using their +#purge_later+ method. +# Provides delayed purging of attachments or blobs using their +purge_later+ method. class ActiveStorage::PurgeJob < ActiveJob::Base # FIXME: Limit this to a custom ActiveStorage error retry_on StandardError diff --git a/activestorage/app/models/active_storage/attachment.rb b/activestorage/app/models/active_storage/attachment.rb index adfa6d4aa5..ad43845e4e 100644 --- a/activestorage/app/models/active_storage/attachment.rb +++ b/activestorage/app/models/active_storage/attachment.rb @@ -4,7 +4,7 @@ require "active_support/core_ext/module/delegation" # Attachments associate records with blobs. Usually that's a one record-many blobs relationship, # but it is possible to associate many different records with the same blob. If you're doing that, -# you'll want to declare with `has_one/many_attached :thingy, dependent: false`, so that destroying +# you'll want to declare with <tt>has_one/many_attached :thingy, dependent: false</tt>, so that destroying # any one record won't destroy the blob as well. (Then you'll need to do your own garbage collecting, though). class ActiveStorage::Attachment < ActiveRecord::Base self.table_name = "active_storage_attachments" @@ -22,8 +22,8 @@ class ActiveStorage::Attachment < ActiveRecord::Base end # Purging an attachment means purging the blob, which means talking to the service, which means - # talking over the internet. Whenever you're doing that, it's a good idea to put that work in a job, - # so it doesn't hold up other operations. That's what +#purge_later+ provides. + # talking over the Internet. Whenever you're doing that, it's a good idea to put that work in a job, + # so it doesn't hold up other operations. That's what +purge_later+ provides. def purge_later ActiveStorage::PurgeJob.perform_later(self) end diff --git a/activestorage/app/models/active_storage/blob.rb b/activestorage/app/models/active_storage/blob.rb index dc91a9265f..36b8a35778 100644 --- a/activestorage/app/models/active_storage/blob.rb +++ b/activestorage/app/models/active_storage/blob.rb @@ -3,8 +3,8 @@ # 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! +# 1) Subsequent to the file being uploaded server-side to the service via <tt>create_after_upload!</tt>. +# 2) Ahead of the file being directly uploaded client-side to the service via <tt>create_before_direct_upload!</tt>. # # 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 @@ -12,7 +12,7 @@ # # 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. +# If you need to create a derivative or otherwise change the blob, simply create a new blob and purge the old one. class ActiveStorage::Blob < ActiveRecord::Base self.table_name = "active_storage_blobs" @@ -22,11 +22,11 @@ class ActiveStorage::Blob < ActiveRecord::Base class_attribute :service class << self - # 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 + # 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. + # The signed ID is also used to create stable URLs for the blob through the BlobsController. def find_signed(id) find ActiveStorage.verifier.verify(id, purpose: :blob_id) end @@ -43,8 +43,8 @@ class ActiveStorage::Blob < ActiveRecord::Base end # 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 doing to avoid opening a transaction and talking to - # the service during that (which is a bad idea and leads to deadlocks). + # 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. 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 @@ -59,9 +59,8 @@ class ActiveStorage::Blob < ActiveRecord::Base end end - # 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. + # It uses the framework-wide verifier on <tt>ActiveStorage.verifier</tt>, but with a dedicated purpose. def signed_id ActiveStorage.verifier.generate(id, purpose: :blob_id) end @@ -74,8 +73,9 @@ class ActiveStorage::Blob < ActiveRecord::Base self[:key] ||= self.class.generate_unique_secure_token end - # Returns a 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. + # 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. def filename ActiveStorage::Filename.new(self[:filename]) end @@ -100,8 +100,9 @@ class ActiveStorage::Blob < ActiveRecord::Base content_type.start_with?("text") end - # Returns a ActiveStorage::Variant instance with the set of +transformations+ passed in. This is only relevant - # for image files, and it allows any image to be transformed for size, colors, and the like. Example: + # Returns an ActiveStorage::Variant instance with the set of +transformations+ + # passed in. 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 # @@ -119,7 +120,6 @@ class ActiveStorage::Blob < ActiveRecord::Base ActiveStorage::Variant.new(self, ActiveStorage::Variation.new(transformations)) end - # 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 @@ -162,7 +162,6 @@ class ActiveStorage::Blob < ActiveRecord::Base service.download key, &block end - # 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. @@ -178,7 +177,7 @@ class ActiveStorage::Blob < ActiveRecord::Base destroy end - # Enqueues a ActiveStorage::PurgeJob job that'll call +#purge+. This is the recommended way to purge blobs when the call + # 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. def purge_later ActiveStorage::PurgeJob.perform_later(self) diff --git a/activestorage/app/models/active_storage/variant.rb b/activestorage/app/models/active_storage/variant.rb index 7b4ca18c8c..92fa445095 100644 --- a/activestorage/app/models/active_storage/variant.rb +++ b/activestorage/app/models/active_storage/variant.rb @@ -4,8 +4,8 @@ # These variants are used to create thumbnails, fixed-size avatars, or any other derivative image from the # original. # -# Variants rely on `MiniMagick` for the actual transformations of the file, so you must add `gem "mini_magick"` -# to your Gemfile if you wish to use variants. +# Variants rely on {MiniMagick}(https://github.com/minimagick/minimagick) for the actual transformations +# of the file, so you must add <tt>gem "mini_magick"</tt> to your Gemfile if you wish to use variants. # # Note that to create a variant it's necessary to download the entire blob file from the service and load it # into memory. The larger the image, the more memory is used. Because of this process, you also want to be @@ -21,7 +21,7 @@ # This will create a URL for that specific blob with that specific variant, which the ActiveStorage::VariantsController # can then produce on-demand. # -# When you do want to actually produce the variant needed, call +#processed+. This will check that the variant +# When you do want to actually produce the variant needed, call +processed+. This will check that the variant # has already been processed and uploaded to the service, and, if so, just return that. Otherwise it will perform # the transformations, upload the variant to the service, and return itself again. Example: # @@ -58,14 +58,13 @@ class ActiveStorage::Variant # 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. # - # Use `url_for(variant)` (or the implied form, like `link_to variant` or `redirect_to variant`) to get the stable URL - # for a variant that points to the ActiveStorage::VariantsController, which in turn will use this +#service_call+ method + # Use <tt>url_for(variant)</tt> (or the implied form, like +link_to variant+ or +redirect_to variant+) to get the stable URL + # for a variant that points to the ActiveStorage::VariantsController, which in turn will use this +service_call+ method # for its redirection. def service_url(expires_in: 5.minutes, disposition: :inline) service.url key, expires_in: expires_in, disposition: disposition, filename: blob.filename, content_type: blob.content_type end - private def processed? service.exist?(key) diff --git a/activestorage/app/models/active_storage/variation.rb b/activestorage/app/models/active_storage/variation.rb index 396ce85ef1..f657d90db4 100644 --- a/activestorage/app/models/active_storage/variation.rb +++ b/activestorage/app/models/active_storage/variation.rb @@ -15,13 +15,13 @@ class ActiveStorage::Variation attr_reader :transformations class << self - # Returns a variation instance with the transformations that were encoded by +#encode+. + # Returns a variation instance with the transformations that were encoded by +encode+. def decode(key) new ActiveStorage.verifier.verify(key, purpose: :variation) end # Returns a signed key for the +transformations+, which can be used to refer to a specific - # variation in a URL or combined key (like `ActiveStorage::Variant#key`). + # variation in a URL or combined key (like <tt>ActiveStorage::Variant#key</tt>). def encode(transformations) ActiveStorage.verifier.generate(transformations, purpose: :variation) end @@ -31,7 +31,7 @@ class ActiveStorage::Variation @transformations = transformations end - # Accepts an open MiniMagick image instance, like what's return by `MiniMagick::Image.read(io)`, + # Accepts an open MiniMagick image instance, like what's returned by <tt>MiniMagick::Image.read(io)</tt>, # and performs the +transformations+ against it. The transformed image instance is then returned. def transform(image) transformations.each do |(method, argument)| |