Shrine::Plugins::Rom

Provides ROM integration for Shrine.

Installation

$ bundle add shrine-rom

Quick start

Let's asume we have "photos" that have an "image" attachment. We start by configuring Shrine in our initializer, and loading the rom plugin provided by shrine-rom:

# Gemfile
gem "shrine", "~> 3.0"
gem "shrine-rom"

require "shrine"
require "shrine/storage/file_system"

Shrine.storages = {
  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"), # temporary
  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads"),       # permanent
}

Shrine.plugin :rom                    # ROM integration, provided by shrine-rom
Shrine.plugin :cached_attachment_data # for retaining the cached file across form redisplays
Shrine.plugin :rack_file              # for accepting Rack uploaded file hashes
Shrine.plugin :form_assign            # for assigning file from form fields
Shrine.plugin :restore_cached_data    # re-extract metadata when attaching a cached file
Shrine.plugin :validation_helpers     # for validating uploaded files
Shrine.plugin :determine_mime_type    # determine MIME type from file content

Next, we run a migration that adds an image_data text or JSON column to our photos table:

ROM::SQL.migration do
  change do
    add_column :photos, :image_data, :text # or :jsonb
  end
end

Now we can define an ImageUploader class and include an attachment module into our Photo entity:

class ImageUploader < Shrine
  # we add some basic validation
  Attacher.validate do
    validate_max_size 20*1024*1024
    validate_mime_type %w[image/jpeg image/png image/webp]
    validate_extension %w[jpg jpeg png webp]
  end
end

class PhotoRepo < ROM::Repository[:photos]
  commands :create, update: :by_pk, delete: :by_pk
  struct_namespace Entities

  def find(id)
    photos.fetch(id)
  end
end

module Entities
  class Photo < ROM::Struct
    include ImageUploader::Attachment[:image]
  end
end

Let's now add fields for our image attachment to our HTML form for creating photos:

# with Forme gem:
form @photo, action: "/photos", enctype: "multipart/form-data", namespace: "photo" do |f|
  f.input :title, type: :text
  f.input :image, type: :hidden, value: @attacher&.cached_data
  f.input :image, type: :file
  f.button "Create"
end

Now in our controller we can attach the uploaded file from request params. We'll assume you're using dry-validation for validating user input.

post "/photos" do
  @photo    = Entities::Photo.new
  @attacher = @photo.image_attacher

  @attacher.form_assign(params["photo"]) # assigns file and performs validation

  contract = CreatePhotoContract.new(image_attacher: @attacher)
  result   = contract.call(params["photo"])

  if result.success?
    @attacher.finalize # upload cached file to permanent storage

    attributes = result.to_h
    attributes.merge!(@attacher.column_values)

    photo_repo.create(attributes)
    # ...
  else
    # ... render view with form ...
  end
end

class CreatePhotoContract < Dry::Validation::Contract
  option :image_attacher

  params do
    required(:title).filled(:string)
  end

  # copy any attacher's validation errors into our dry-validation contract
  rule(:image) do
    key.failure("must be present") unless image_attacher.attached?
    image_attacher.errors.each { |message| key.failure(message) }
  end
end

Once the image has been successfully attached to our photo, we can retrieve the image URL by calling #image_url on the entity:

<img src="<%= @photo.image_url %>" />

If you want to see a complete example with direct uploads and backgrounding, see the demo app.

Understanding

The rom plugin builds upon Shrine's entity plugin, providing persistence functionality.

The attachment module included into the entity provides convenience methods for reading the data attribute:

photo.image_data #=> '{"id":"path/to/file","storage":"store","metadata":{...}}'

photo.image          #=> #<Shrine::UploadedFile @id="path/to/file" @storage_key=:store ...>
photo.image_url      #=> "https://s3.amazonaws.com/..."
photo.image_attacher #=> #<Shrine::Attacher ...>

Updating

When updating the attached file for an existing record, it's important to initialize the attacher from that record's current attachment. That way the old file will be automatically deleted on Attacher#finalize.

photo = photo_repo.find(photo_id)
photo.image #=> #<Shrine::UploadedFile @id="foo" ...>

attacher = photo.image_attacher # has current attachment
attacher.assign(file)

photo_repo.update(photo_id, attacher.column_values)

attacher.finalize # deletes previous attachment

Attacher state

Unlike the model plugin, the entity plugin doesn't memoize the Shrine::Attacher instance:

photo.image_attacher #=> #<Shrine::Attacher:0x00007ffe564085d8>
photo.image_attacher #=> #<Shrine::Attacher:0x00007ffe53b2f378> (different instance)

So, if you want to update the attacher state, you need to first assign it to a variable:

attacher = photo.image_attacher
attacher.assign(file)
attacher.finalize

Persisting

Normally you'd persist attachment changes explicitly, by using Attacher#column_data or Attacher#column_values:

attacher = photo.image_attacher
attacher.attach(file)

photo_repo.create(image_data: attacher.column_data)
# or
photo_repo.create(attacher.column_values)

Backgrounding

If you want to delay promotion into a background job, you need to call Attacher#finalize after you've persisted the cached file, so that your background job is able to retrieve the record. We'll assume your repository objects are registered using dry-container.

Shrine.plugin :backgrounding

Shrine::Attacher.promote_block do
  Attachment::PromoteJob.perform_async(self.class.name, record.class.name, record.id, name, file_data)
end

Shrine::Attacher.destroy_block do
  Attachment::DestroyJob.perform_async(self.class.name, data)
end

attacher = photo.image_attacher
attacher.assign(file)

photo = photo_repo.create(attacher.column_values)

attacher.finalize # calls the promote block

class Attachment::PromoteJob
  include Sidekiq::Worker

  def perform(attacher_class, entity_class, entity_id, name, file_data)
    attacher_class = Object.const_get(attacher_class)

    # entity_class is your custom ROM::Struct entity class name.
    # generate repo_registry_name from entity_class.
    repo = Application[repo_registry_name] # retrieve repo from container

    entity = repo.find(entity_id)

    attacher = attacher_class.retrieve(
      entity:     entity,
      name:       name,
      file:       file_data,
      repository: repo, # repository needs to be passed in and it should be the last parameter
    )

    attacher.atomic_promote
  rescue Shrine::AttachmentChanged,   # attachment has changed
         ROM::TupleCountMismatchError # record has been deleted
  end
end

class Attachment::DestroyJob
  include Sidekiq::Worker

  def perform(attacher_class, data)
    attacher = Object.const_get(attacher_class).from_data(data)
    attacher.destroy
  end
end

Contributing

Tests are run with:

$ bundle exec rake test

Code of Conduct

Everyone interacting in the Shrine::Rom project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

License

MIT