Class: ActiveStorage::Service
Relationships & Source Files | |
Namespace Children | |
Classes:
| |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
|
|
Inherits: | Object |
Defined in: | activestorage/lib/active_storage/service.rb |
Overview
Abstract class serving as an interface for concrete services.
The available services are:
-
Disk
, to manage attachments saved directly on the hard drive. -
GCS
, to manage attachments through Google Cloud Storage. -
S3
, to manage attachments through Amazon S3. -
AzureStorage
, to manage attachments through Microsoft Azure Storage. -
Mirror
, to be able to use several services to manage attachments.
Inside a Rails application, you can set-up your services through the generated config/storage.yml
file and reference one of the aforementioned constant under the service
key. For example:
local:
service: Disk
root: <%= Rails.root.join("storage") %>
You can checkout the service’s constructor to know which keys are required.
Then, in your application’s configuration, you can specify the service to use like this:
config.active_storage.service = :local
If you are using Active Storage outside of a Ruby on Rails application, you can configure the service to use like this:
ActiveStorage::Blob.service = ActiveStorage::Service.configure(
:local,
{ local: {service: "Disk", root: Pathname("/tmp/foo/storage") } }
)
Class Method Summary
-
.configure(service_name, configurations)
Configure an Active Storage service by name from a set of configurations, typically loaded from a YAML file.
-
.build(configurator:, name:, service: nil, **service_config)
Internal use only
Override in subclasses that stitch together multiple services and hence need to build additional services using the configurator.
::ActiveSupport::Autoload
- Extended
Instance Attribute Summary
- #name rw
- #public? ⇒ Boolean readonly
Instance Method Summary
-
#compose(source_keys, destination_key, filename: nil, content_type: nil, disposition: nil, custom_metadata: {})
Concatenate multiple files into a single “composed” file.
-
#delete(key)
Delete the file at the
key
. -
#delete_prefixed(prefix)
Delete files at keys starting with the
prefix
. -
#download(key)
Return the content of the file at the
key
. -
#download_chunk(key, range)
Return the partial content in the byte
range
of the file at thekey
. -
#exist?(key) ⇒ Boolean
Return
true
if a file exists at thekey
. -
#headers_for_direct_upload(key, filename:, content_type:, content_length:, checksum:, custom_metadata: {})
Returns a
::Hash
of headers for #url_for_direct_upload requests. - #open(*args, **options, &block)
-
#update_metadata(key, **metadata)
Update metadata for the file identified by
key
in the service. -
#upload(key, io, checksum: nil, **options)
Upload the
io
to thekey
specified. -
#url(key, **options)
Returns the URL for the file at the
key
. -
#url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:, custom_metadata: {})
Returns a signed, temporary URL that a direct upload file can be PUT to on the
key
. - #content_disposition_with(type: "inline", filename:) private
- #custom_metadata_headers(metadata) private
- #instrument(operation, payload = {}, &block) private
- #private_url(key, expires_in:, filename:, disposition:, content_type:) private
- #public_url(key) private
- #service_name private
Class Method Details
.build(configurator:, name:, service: nil, **service_config)
Override in subclasses that stitch together multiple services and hence need to build additional services using the configurator.
Passes the configurator and all of the service’s config as keyword args.
See MirrorService for an example.
.configure(service_name, configurations)
Configure an Active Storage service by name from a set of configurations, typically loaded from a YAML file. The Active Storage engine uses this to set the global Active Storage service when the app boots.
# File 'activestorage/lib/active_storage/service.rb', line 52
def configure(service_name, configurations) Configurator.build(service_name, configurations) end
Instance Attribute Details
#name (rw)
[ GitHub ]# File 'activestorage/lib/active_storage/service.rb', line 46
attr_accessor :name
#public? ⇒ Boolean
(readonly)
[ GitHub ]
# File 'activestorage/lib/active_storage/service.rb', line 147
def public? @public end
Instance Method Details
#compose(source_keys, destination_key, filename: nil, content_type: nil, disposition: nil, custom_metadata: {})
Concatenate multiple files into a single “composed” file.
# File 'activestorage/lib/active_storage/service.rb', line 96
def compose(source_keys, destination_key, filename: nil, content_type: nil, disposition: nil, custom_metadata: {}) raise NotImplementedError end
#content_disposition_with(type: "inline", filename:) (private)
[ GitHub ]# File 'activestorage/lib/active_storage/service.rb', line 175
def content_disposition_with(type: "inline", filename:) disposition = (type.to_s.presence_in(%w( attachment inline )) || "inline") ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: filename.sanitized) end
#custom_metadata_headers(metadata) (private)
# File 'activestorage/lib/active_storage/service.rb', line 160
def ( ) raise NotImplementedError end
#delete(key)
Delete the file at the key
.
# File 'activestorage/lib/active_storage/service.rb', line 101
def delete(key) raise NotImplementedError end
#delete_prefixed(prefix)
Delete files at keys starting with the prefix
.
# File 'activestorage/lib/active_storage/service.rb', line 106
def delete_prefixed(prefix) raise NotImplementedError end
#download(key)
Return the content of the file at the key
.
# File 'activestorage/lib/active_storage/service.rb', line 82
def download(key) raise NotImplementedError end
#download_chunk(key, range)
Return the partial content in the byte range
of the file at the key
.
# File 'activestorage/lib/active_storage/service.rb', line 87
def download_chunk(key, range) raise NotImplementedError end
#exist?(key) ⇒ Boolean
Return true
if a file exists at the key
.
# File 'activestorage/lib/active_storage/service.rb', line 111
def exist?(key) raise NotImplementedError end
#headers_for_direct_upload(key, filename:, content_type:, content_length:, checksum:, custom_metadata: {})
Returns a ::Hash
of headers for #url_for_direct_upload requests.
# File 'activestorage/lib/active_storage/service.rb', line 143
def headers_for_direct_upload(key, filename:, content_type:, content_length:, checksum:, custom_metadata: {}) {} end
#instrument(operation, payload = {}, &block) (private)
[ GitHub ]# File 'activestorage/lib/active_storage/service.rb', line 164
def instrument(operation, payload = {}, &block) ActiveSupport::Notifications.instrument( "service_#{operation}.active_storage", payload.merge(service: service_name), &block) end
#open(*args, **options, &block)
[ GitHub ]# File 'activestorage/lib/active_storage/service.rb', line 91
def open(*args, **, &block) ActiveStorage::Downloader.new(self).open(*args, **, &block) end
#private_url(key, expires_in:, filename:, disposition:, content_type:) (private)
# File 'activestorage/lib/active_storage/service.rb', line 152
def private_url(key, expires_in:, filename:, disposition:, content_type:, **) raise NotImplementedError end
#public_url(key) (private)
# File 'activestorage/lib/active_storage/service.rb', line 156
def public_url(key, **) raise NotImplementedError end
#service_name (private)
[ GitHub ]# File 'activestorage/lib/active_storage/service.rb', line 170
def service_name # ActiveStorage::Service::DiskService => Disk self.class.name.split("::").third.remove("Service") end
#update_metadata(key, **metadata)
Update metadata for the file identified by key
in the service. Override in subclasses only if the service needs to store specific metadata that has to be updated upon identification.
# File 'activestorage/lib/active_storage/service.rb', line 78
def (key, ** ) end
#upload(key, io, checksum: nil, **options)
Upload the io
to the key
specified. If a checksum
is provided, the service will ensure a match when the upload has completed or raise an IntegrityError
.
# File 'activestorage/lib/active_storage/service.rb', line 71
def upload(key, io, checksum: nil, ** ) raise NotImplementedError end
#url(key, **options)
Returns the URL for the file at the key
. This returns a permanent URL for public files, and returns a short-lived URL for private files. For private files you can provide the disposition
(:inline
or :attachment
), filename
, and content_type
that you wish the file to be served with on request. Additionally, you can also provide the amount of seconds the URL will be valid for, specified in expires_in
.
# File 'activestorage/lib/active_storage/service.rb', line 119
def url(key, ** ) instrument :url, key: key do |payload| generated_url = if public? public_url(key, ** ) else private_url(key, ** ) end payload[:url] = generated_url generated_url end end
#url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:, custom_metadata: {})
Returns a signed, temporary URL that a direct upload file can be PUT to on the key
. The URL will be valid for the amount of seconds specified in expires_in
. You must also provide the content_type
, content_length
, and checksum
of the file that will be uploaded. All these attributes will be validated by the service upon upload.
# File 'activestorage/lib/active_storage/service.rb', line 138
def url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:, custom_metadata: {}) raise NotImplementedError end