Last Update: 2023-07-30 18:26:06 +0200

title: Shrine 1.4.0

New features

  • Added delete_promoted plugin for deleting files that have been promoted, which applies to any cached files that have been uploaded to store.

  • Added :fallbacks option to versions plugin, which allows specifying fallback URLs for versions which haven't finished processing yet.

class ImageUploader < Shrine
  plugin :versions, fallbacks: {:thumb_2x => :thumb, :large_2x => :large}
# ... (background job is working)

user.avatar_url(:thumb_2x) # returns :thumb URL until :thumb_2x becomes available
user.avatar_url(:large_2x) # returns :large URL until :large_2x becomes available
  • Added ability to do custom backgrounding via Attacher.dump and Attacher.load.

class Record < Sequel::Model
  def after_commit
    if something_happened?
      data = Shrine::Attacher.dump(image_attacher)
class SomethingJob
  include Sidekiq::Worker
  def perform(data)
    attacher = Shrine::Attacher.load(data)
    # ...
  • Added :presign_location to direct_upload plugin for generating the location for presigned upload.

plugin :direct_upload, presign: true, presign_location: ->(r) { "${filename}" }
  • Added :filename to data_uri for generating filenames based on content type of the data URI, in order for filename's extension to be automatically used in uploaded file's location.

require "mime/types"

plugin :data_uri, filename: ->(content_type) do
  extension = MIME::Types[content_type].first.preferred_extension

Other improvements

  • The download_endpoint now sets the Content-Length response header, if the size of the uploaded file is available (S3 now supports it).

  • It's now possible to swap S3 storage with FileSystem when using presigns in direct_upload plugin, without changing any code, which is very useful in tests.

  • The backup plugin now waits for the record to be saved with stored files before it starts uploading to backup storage.

  • The logging plugin now logs both number of input and output files for processing.

  • The migration_helpers now has a :delegate option, which when set to false doesn't add any additional methods to the model.

  • In restore_cached_data plugin the cached file is now closed after the metadata has been extracted.

  • Attacher#promote can now accept a phase, which makes it more generic and can now be used for securely reuploading stored files (no processing, aborts if attachment changes, old file is deleted with delete_promoted plugin), which is useful for moving to new location.

  • The :presign_options now accepts a static hash in addition to a block.

  • The direct_upload endpoint has now been refactored into methods, which means its now easier to override parts of its behaviour.

  • The user-defined hooks will now happen outside logging, regardless of the load order of logging and hooks plugins.

  • The parallelize plugin doesn't depend on the thread gem anymore, it now uses threads directly.

  • Improved the storage linter; it now accounts for some subtleties which could potentially make some storages error, it fails fast, and it tests the content length in streaming.

  • The before_* and after_* hooks now always happen around around_* hooks.

  • The IO is now automatically rewinded when custom analyzer is used with determine_mime_type and store_dimensions plugins.

Bug fixes

  • Fixed logger not being inherited in the logging plugin.

  • In validation_helpers plugin the dimensions validations now don't do anything when dimensions are missing from metadata (previously they were erroring).

  • The keep_files plugin doesn't spawn delete background jobs anymore for files that are to be kept.

  • Deleting backed up files now actually works with backgrounding plugin.

  • Shrine now ignores validations when promoting, which means it will work when saving the record when it is invalid (but validations are skipped).

  • S3 storage now properly encodes the URL when :host option is used, which would previously cause errors if location contained URL-unsafe characters.

  • Eliminate a tiny chance of a race condition during promoting, which could happen with subsequent attachment updates on the same record when using the backgrounding plugin.

  • S3 storage now uses an assigned SSL certificate when downloading.

Backwards compatibility

  • The restore_cached plugin has been renamed to "restore_cached_data". The plugin will stop being loadable with the old name in Shrine 2.

  • In direct_upload presign options are now accepted via :presign_options (instead of :presign). Accepting them via :presign will stop working in Shrine 2.

  • The direct_upload's endpoint has now been changed from /:storage/:name to /:storage/upload. The old endpoint is still accessible and will stay in Shrine 2, but will be removed in Shrine 3.

  • The :delegate option is now mandatory to pass for migration_helpers, until Shrine 2 where it will default to false.

  • The delete_uploaded plugin has been renamed to "delete_raw". The plugin can still be loaded via "delete_uploaded", but this won't be possible anymore in Shrine 2.

  • The moving plugin now deprecates "fake" moving, where in case the storage didn't support moving the file would be uploaded and deleted. In Shrine 2 the file won't be deleted anymore (you can use the delete_raw plugin for this functionality).

  • The Shrine.versions! and Shrine.versions methods have been removed, as they were part of internal API of versions plugin, but accidentally made public.