design.md

title
The Design of Shrine

If you want an in-depth walkthrough through the Shrine codebase, see Notes on study of shrine implementation article by Jonathan Rochkind.

There are five main types of classes that you deal with in Shrine:

Class	Description
Shrine::Storage::*	Manages files on a particular storage service
Shrine	Wraps uploads and handles loading plugins
Shrine::UploadedFile	Represents a file uploaded to a storage
Shrine::Attacher	Handles file attachment logic
Shrine::Attachment	Provides convenience model attachment interface

Storage

On the lowest level we have a storage. A storage class encapsulates file management logic on a particular service. It is what actually performs uploads, generation of URLs, deletions and similar. By convention it is namespaced under Shrine::Storage::*.

filesystem = Shrine::Storage::FileSystem.new("uploads")
filesystem.upload(file, "foo")
filesystem.url("foo") #=> "uploads/foo"
filesystem.delete("foo")

A storage is a PORO which implements the following interface:

class Shrine
  module Storage
    class MyStorage
      def upload(io, id, shrine_metadata: {}, **upload_options)
        # uploads `io` to the location `id`
      end

      def open(id, **options)
        # returns the remote file as an IO-like object
      end

      def exists?(id)
        # checks if the file exists on the storage
      end

      def delete(id)
        # deletes the file from the storage
      end

      def url(id, **options)
        # URL to the remote file, accepts options for customizing the URL
      end
    end
  end
end

Storages are typically not used directly, but through Shrine and Shrine::UploadedFile classes.

Shrine

The Shrine class (also called an "uploader") primarily provides a wrapper method around Storage#upload. First, the storage needs to be registered under a name:

Shrine.storages[:disk] = Shrine::Storage::FileSystem.new("uploads")

Now we can upload files to the registered storage:

uploaded_file = Shrine.upload(file, :disk)
uploaded_file #=> #<Shrine::UploadedFile storage=:disk id="6a9fb596cc554efb" ...>

The argument to Shrine#upload must be an IO-like object. The method does the following:

• generates a unique location
• extracts metadata
• uploads the file (calls Storage#upload)
• closes the file
• creates a Shrine::UploadedFile from the data

Plugins

The Shrine class is also used for loading plugins, which provide additional functionality by extending core classes.

Shrine.plugin :derivatives

Shrine::UploadedFile.ancestors #=> [..., Shrine::Plugins::Derivatives::FileMethods, Shrine::UploadedFile::InstanceMethods, ...]
Shrine::Attacher.ancestors     #=> [..., Shrine::Plugins::Derivatives::AttacherMethods, Shrine::Attacher::InstanceMethods,  ...]
Shrine::Attachment.ancestors   #=> [..., Shrine::Plugins::Derivatives::AttachmentMethods, Shrine::Attachment::InstanceMethods, ...]

The plugins store their configuration in Shrine.opts:

Shrine.plugin :derivation_endpoint, secret_key: "foo"
Shrine.plugin :default_storage, store: :other_store
Shrine.plugin :activerecord

Shrine.opts #=>
# { derivation_endpoint: { options: { secret_key: "foo" }, derivations: {} },
#   default_storage: { store: :other_store },
#   column: { serializer: Shrine::Plugins::Column::JsonSerializer },
#   model: { cache: true },
#   activerecord: { callbacks: true, validations: true } }

Each Shrine subclass has its own copy of the core classes, storages and options, which makes it possible to customize attachment logic per uploader.

MyUploader = Class.new(Shrine)
MyUploader::UploadedFile.superclass #=> Shrine::UploadedFile
MyUploader::Attacher.superclass     #=> Shrine::Attacher
MyUploader::Attachment.superclass   #=> Shrine::Attachment

See Creating a New Plugin guide and the Plugin system of Sequel and Roda article for more details on the design of Shrine's plugin system.

Shrine::UploadedFile

A Shrine::UploadedFile object represents a file that was uploaded to a storage, containing upload location, storage, and any metadata extracted during the upload.

uploaded_file #=> #<Shrine::UploadedFile id="949sdjg834.jpg" storage=:store metadata={...}>

uploaded_file.id          #=> "949sdjg834.jpg"
uploaded_file.storage_key #=> :store
uploaded_file.storage     #=> #<Shrine::Storage::S3>
uploaded_file.metadata    #=> {...}

It has convenience methods for accessing metadata:

uploaded_file.metadata #=>
# {
#   "filename" => "matrix.mp4",
#   "mime_type" => "video/mp4",
#   "size" => 345993,
# }

uploaded_file.original_filename #=> "matrix.mp4"
uploaded_file.extension         #=> "mp4"
uploaded_file.mime_type         #=> "video/mp4"
uploaded_file.size              #=> 345993

It also has methods that delegate to the storage:

uploaded_file.url                     #=> "https://my-bucket.s3.amazonaws.com/949sdjg834.jpg"
uploaded_file.open { |io| ... }       # opens the uploaded file stream
uploaded_file.download { |file| ... } # downloads the uploaded file to disk
uploaded_file.stream(destination)     # streams uploaded content into a writable destination
uploaded_file.exists?                 #=> true
uploaded_file.delete                  # deletes the uploaded file from the storage

A Shrine::UploadedFile is itself an IO-like object (built on top of Storage#open), so it can be passed to Shrine#upload as well.

Shrine::Attacher

We usually want to treat uploaded files as attachments to records, saving their data into a database column. This is done by Shrine::Attacher, which internally uses Shrine and Shrine::UploadedFile classes.

The attaching process requires a temporary and a permanent storage to be registered (by default that's :cache and :store):

Shrine.storages = {
  cache: Shrine::Storage::FileSystem.new("uploads/cache"),
  store: Shrine::Storage::FileSystem.new("uploads/store"),
}

A Shrine::Attacher can be initialized standalone and handle the common attachment flow, which includes dirty tracking (promoting cached file to permanent storage, deleting previously attached file), validation, processing, serialization etc.

attacher = Shrine::Attacher.new

# ... user uploads a file ...

attacher.assign(io) # uploads to temporary storage
attacher.file       #=> #<Shrine::UploadedFile storage=:cache ...>

# ... handle file validations ...

attacher.finalize   # uploads to permanent storage
attacher.file       #=> #<Shrine::UploadedFile storage=:store ...>

It can also be initialized with a model instance to handle serialization into a model attribute:

attacher = Shrine::Attacher.from_model(photo, :image)

attacher.assign(file)
photo.image_data #=> "{\"storage\":\"cache\",\"id\":\"9260ea09d8effd.jpg\",\"metadata\":{...}}"

attacher.finalize
photo.image_data #=> "{\"storage\":\"store\",\"id\":\"ksdf02lr9sf3la.jpg\",\"metadata\":{...}}"

For more details, see the Using Attacher guide and entity/model plugins.

Shrine::Attachment

A Shrine::Attachment module provides a convenience model interface around the Shrine::Attacher object. The Shrine::Attachment class is a subclass of Module, which means that an instance of Shrine::Attachment is a module:

Shrine::Attachment.new(:image).is_a?(Module) #=> true
Shrine::Attachment.new(:image).instance_methods #=> [:image=, :image, :image_url, :image_attacher, ...]

# equivalents
Shrine::Attachment.new(:image)
Shrine::Attachment[:image]
Shrine::Attachment(:image)

We can include this module into a model:

Photo.include Shrine::Attachment(:image)

photo.image = file   # shorthand for `photo.image_attacher.assign(file)`
photo.image          # shorthand for `photo.image_attacher.get`
photo.image_url      # shorthand for `photo.image_attacher.url`

photo.image_attacher #=> #<Shrine::Attacher @cache_key=:cache @store_key=:store ...>

When a persistence plugin is loaded (activerecord, sequel), the Shrine::Attachment module also automatically:

• syncs Shrine's validation errors with the record
• triggers promoting after record is saved
• deletes the uploaded file if attachment was replaced or the record destroyed