Class: ActiveStorage::Service

Inherits:
Object
  • Object
show all
Extended by:
ActiveSupport::Autoload
Defined in:
activestorage/lib/active_storage/service.rb

Overview

Active Storage Service

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") } }
)

Defined Under Namespace

Classes: AzureStorageService, Configurator, DiskService, GCSService, MirrorService, Registry, S3Service

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ActiveSupport::Autoload

autoload, autoload_at, autoload_under, eager_autoload, eager_load!

Instance Attribute Details

#name ⇒ Object

Returns the value of attribute name.



46
47
48
 
# File 'activestorage/lib/active_storage/service.rb', line 46

def name
  @name
end

Class Method Details

.build(configurator:, name:, service: nil, **service_config) ⇒ Object

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.



62
63
64
65
66
 
# File 'activestorage/lib/active_storage/service.rb', line 62

def build(configurator:, name:, service: nil, **service_config) # :nodoc:
  new(**service_config).tap do |service_instance|
    service_instance.name = name
  end
end

.configure(service_name, configurations) ⇒ Object

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.



52
53
54
 
# File 'activestorage/lib/active_storage/service.rb', line 52

def configure(service_name, configurations)
  Configurator.build(service_name, configurations)
end

Instance Method Details

#compose(source_keys, destination_key, filename: nil, content_type: nil, disposition: nil, custom_metadata: {}) ⇒ Object

Concatenate multiple files into a single “composed” file.

Raises:

  • (NotImplementedError) 


96
97
98
 
# 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

#delete(key) ⇒ Object

Delete the file at the key.

Raises:

  • (NotImplementedError) 


101
102
103
 
# File 'activestorage/lib/active_storage/service.rb', line 101

def delete(key)
  raise NotImplementedError
end

#delete_prefixed(prefix) ⇒ Object

Delete files at keys starting with the prefix.

Raises:

  • (NotImplementedError) 


106
107
108
 
# File 'activestorage/lib/active_storage/service.rb', line 106

def delete_prefixed(prefix)
  raise NotImplementedError
end

#download(key) ⇒ Object

Return the content of the file at the key.

Raises:

  • (NotImplementedError) 


82
83
84
 
# File 'activestorage/lib/active_storage/service.rb', line 82

def download(key)
  raise NotImplementedError
end

#download_chunk(key, range) ⇒ Object

Return the partial content in the byte range of the file at the key.

Raises:

  • (NotImplementedError) 


87
88
89
 
# 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.

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


111
112
113
 
# 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: {}) ⇒ Object

Returns a Hash of headers for url_for_direct_upload requests.



143
144
145
 
# File 'activestorage/lib/active_storage/service.rb', line 143

def headers_for_direct_upload(key, filename:, content_type:, content_length:, checksum:, custom_metadata: {})
  {}
end

#open(*args, **options, &block) ⇒ Object 



91
92
93
 
# File 'activestorage/lib/active_storage/service.rb', line 91

def open(*args, **options, &block)
  ActiveStorage::Downloader.new(self).open(*args, **options, &block)
end

#public? ⇒ Boolean

Returns:

  • (Boolean) 


147
148
149
 
# File 'activestorage/lib/active_storage/service.rb', line 147

def public?
  @public
end

#update_metadata(key, **metadata) ⇒ Object

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.



78
79
 
# File 'activestorage/lib/active_storage/service.rb', line 78

def update_metadata(key, **metadata)
end

#upload(key, io, checksum: nil, **options) ⇒ Object

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

Raises:

  • (NotImplementedError) 


71
72
73
 
# File 'activestorage/lib/active_storage/service.rb', line 71

def upload(key, io, checksum: nil, **options)
  raise NotImplementedError
end

#url(key, **options) ⇒ Object

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.



119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'activestorage/lib/active_storage/service.rb', line 119

def url(key, **options)
  instrument :url, key: key do |payload|
    generated_url =
      if public?
        public_url(key, **options)
      else
        private_url(key, **options)
      end

    payload[:url] = generated_url

    generated_url
  end
end

#url_for_direct_upload(key, expires_in:, content_type:, content_length:, checksum:, custom_metadata: {}) ⇒ Object

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.

Raises:

  • (NotImplementedError) 


138
139
140
 
# 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