DOCSEARCHbyAlgolia
Submit Docs

Shrine Ruby Documentation

website·Indexed 34 days ago

https://shrinerb.com

API documentation for Shrine, a file upload toolkit for Ruby. This documentation covers various plugins including Derivatives, Instrumentation, RemoteUrl, DetermineMimeType, and RackResponse, detailing their class, instance, and attacher methods.

Tokens
192.4K
Snippets
1.3K
Records
1.7K
Agent score
68%

What's inside Shrine

  1. Overview of Shrine file attachment toolkit

    Shrine is a modular toolkit for handling file attachments in Ruby applications. Key features include:

    • Modular Design: A plugin system allows loading only necessary functionality.
    • Memory Efficiency: Supports streaming uploads and downloads for large files.
    • Cloud Storage: Compatible with local disk, AWS S3, Google Cloud, Cloudinary, and others.
    • Persistence Integrations: Works with ActiveRecord, Sequel, ROM, Hanami, and Mongoid.
    • Flexible Processing: Supports eager or on-the-fly thumbnail generation via ImageMagick or libvips.
    • Direct Uploads: Supports asynchronous uploads to the app or cloud (e.g., via Uppy), including resumable uploads on S3 or tus.
    • Background Processing: Built-in support for various backgrounding libraries.

  2. Overview of Shrine's architecture and design

    Shrine is a file upload library for Ruby designed to be framework-agnostic. Unlike other solutions coupled to Rails or Active Record, Shrine uses Rack for web-specific functionality and provides ORM integrations via plugins. It avoids 'god objects' by distributing responsibilities across specialized classes:

    • Shrine::Storage::*: Handles file operations for the underlying storage service.
    • Shrine: Wraps uploads and manages plugin loading.
    • Shrine::UploadedFile: Represents a file uploaded to storage.
    • Shrine::Attacher: Manages the process of attaching files to records.
    • Shrine::Attachment: Provides convenience methods to model instances.

  3. Overview of Shrine file attachment toolkit

    Shrine is a modular toolkit for handling file attachments in Ruby applications. Key features include:

    • Modular Design: A plugin system allows loading only necessary functionality.
    • Memory Efficiency: Supports streaming uploads and downloads for large files.
    • Cloud Storage: Compatible with disk, AWS S3, Google Cloud, Cloudinary, and others.
    • Persistence Integrations: Works with ActiveRecord, Sequel, ROM, Hanami, and Mongoid.
    • Flexible Processing: Supports eager or on-the-fly thumbnail generation via ImageMagick or libvips.
    • Direct & Resumable Uploads: Supports asynchronous uploads to the app or cloud (e.g., via Uppy) and resumable uploads on S3 or tus.
    • Background Processing: Built-in support for various backgrounding libraries.

  4. Prevent concurrency race conditions with atomic_helpers

    The atomic_helpers plugin provides tools to avoid race conditions when multiple processors (web workers, background jobs, etc.) edit a Shrine attachment concurrently. It specifically prevents:

    1. Overwriting a new attachment with a promoted version of a prior attachment.
    2. Overwriting metadata changes because multiple processes read and write the same JSON hash simultaneously.
    plugin :atomic_helpers

  5. Use Shrine::DerivationEndpoint to serve file derivations

    The Shrine::DerivationEndpoint class is a Rack application used to handle requests for file derivations. It extracts the derivation name, arguments, and the serialized file from the request path, verifies the request signature and expiry, and returns the resulting derivation response. It supports overriding static options via request parameters such as type, disposition, filename, version, and expires_at.
    # Initialize the endpoint with the Shrine class and optional configuration
endpoint = Shrine::DerivationEndpoint.new(shrine_class: MyUploader, options: { cache_control: 'public, max-age=3600' }) 

# The endpoint can be called in a Rack middleware stack
# status, headers, body = endpoint.call(env)

  6. Use Shrine::Plugins::Instrumentation::LogSubscriber to log file events

    The Shrine::Plugins::Instrumentation::LogSubscriber class is responsible for logging events triggered by the Shrine instrumentation plugin. It provides a centralized way to log the duration and metadata of common storage operations such as uploads, downloads, and deletions. The entry point for logging is the class method .call(event), which dynamically dispatches the event to the corresponding on_<event_name> instance method.
    # Example of how the class method is invoked internally
Shrine::Plugins::Instrumentation::LogSubscriber.call(event)

  7. Use Shrine::DownloadEndpoint to route file download requests

    The Shrine::DownloadEndpoint class is used to route incoming requests for file downloads. It validates that the storage is existent and allowed before proceeding with a streaming file download. It is designed to work within a Rack environment.

  8. Use Shrine::PresignEndpoint to serve presigned URLs

    Shrine::PresignEndpoint is a Rack application that accepts GET requests to its root URL. When a request is received, it calls the #presign method on the configured storage and returns the presigned URL information in JSON format.

    Behavioral constraints:

    • Only requests to the root URL (/ or empty path) are accepted; otherwise, it returns a 404 Not Found response.
    • Only GET requests are processed; other verbs result in a 405 Method Not Allowed response.

  9. Understand the architectural differences between Paperclip and Shrine

    Shrine differs from Paperclip in several key design areas:

    • Uploader Logic: Paperclip configures attachment logic directly in the model. Shrine uses dedicated 'uploader' classes to encapsulate logic, which are then included in the model.
    • Storage: Paperclip couples storage implementation with the attachment flow. Shrine decouples storage objects, allowing for separate configuration and the use of 'temporary' storage for validations and direct uploads.
    • Persistence: Paperclip uses multiple columns (e.g., _file_name, _content_type, _file_size). Shrine uses a single JSON column (e.g., _data) to store the file ID, storage key, and metadata.
    • Location: Paperclip stores only the filename and calculates the path dynamically. Shrine persists the full location upon attachment, ensuring links remain valid even if location generation logic changes.
    • ORM Support: While Paperclip is tied to Active Record, Shrine supports multiple persistence libraries including Active Record, Sequel, ROM, Hanami, and Mongoid, or can be used standalone.

  10. Use Shrine::Attacher to handle file attachments

    Shrine::Attacher is the core class in the Shrine library used for attaching files. It manages the attachment process by internally utilizing Shrine and Shrine::UploadedFile objects.

  11. Implement direct uploads with Uppy

    Shrine supports client-side direct uploads using the Uppy JavaScript library. This allows files to be uploaded directly to storage (like AWS S3) or a custom endpoint, reducing server load. Shrine provides Rack-based server-side components to support various Uppy upload methods.

  12. Use the Shrine core class for file uploads

    The Shrine class is the core component of the Shrine library, responsible for handling the process of uploading files to a specified storage backend.