shrine-rom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78bc603cf077c91b940f0df8d4cd0304c68b4182b0ae6b086e911eb1107a1465
+  data.tar.gz: c0eabd2c656ddd614a21cf729f0c344de88e2dec2874d9c70052262e748b4107
+SHA512:
+  metadata.gz: cea2d2928e38caaf138e9246dd5df636aed3e3de01ee7860a1fedec4c69ce5ba197632423d36be05b644d8d383646e9d86b56ff5b40f1f99795f0a575b82db8a
+  data.tar.gz: bd9e6a7cf0ac72be3ae91a3ed10665c172f202f45aa6523d53c72b06edba96905e24933a1dcf8246af691821e756706afb306a4f08837f1a22382c6973479d0f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Janko Marohnić
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,291 @@
+# Shrine::Plugins::Rom
+
+Provides [ROM] integration for [Shrine].
+
+## Installation
+
+```sh
+$ 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:
+
+```rb
+# Gemfile
+gem "shrine", "~> 3.0"
+gem "shrine-rom"
+```
+```rb
+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:
+
+```rb
+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:
+
+```rb
+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
+```
+```rb
+class PhotoRepo < ROM::Repository[:photos]
+  commands :create, update: :by_pk, delete: :by_pk
+  struct_namespace Entities
+
+  def find(id)
+    photos.fetch(id)
+  end
+end
+```
+```rb
+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:
+
+```rb
+# 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.
+
+```rb
+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
+```
+```rb
+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:
+
+```erb
+<img src="<%= @photo.image_url %>" />
+```
+
+If you want to see a complete example with direct uploads and backgrounding,
+see the [demo app][demo].
+
+## Understanding
+
+The `rom` plugin builds upon Shrine's [`entity`][entity] plugin, providing
+persistence functionality.
+
+The attachment module included into the entity provides convenience methods for
+reading the data attribute:
+
+```rb
+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`.
+
+```rb
+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`][model] plugin, the `entity` plugin doesn't memoize the
+`Shrine::Attacher` instance:
+
+```rb
+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:
+
+```rb
+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`:
+
+```rb
+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].
+
+```rb
+Shrine.plugin :backgrounding
+Shrine::Attacher.destroy_block { Attachment::DestroyJob.perform_async(self.class, data) }
+```
+```rb
+attacher = photo.image_attacher
+attacher.assign(file)
+
+photo = photo_repo.create(attacher.column_values)
+
+attacher.promote_block do |attacher|
+  Attachment::PromoteJob.perform_async(:photo_repo, photo.id, :image, attacher.file_data)
+end
+
+attacher.finalize # calls the promote block
+```
+```rb
+class Attachment::PromoteJob
+  include Sidekiq::Worker
+
+  def perform(repo_name, record_id, name, file_data)
+    repo   = Application[repo_name] # retrieve repo from container
+    entity = repo.find(record_id)
+
+    attacher = Shrine::Attacher.retrieve(
+      entity:     entity,
+      name:       name,
+      file:       file_data,
+      repository: repo, # repository needs to be passed in
+    )
+
+    attacher.atomic_promote
+  rescue Shrine::AttachmentChanged,   # attachment has changed
+         ROM::TupleCountMismatchError # record has been deleted
+  end
+end
+```
+```rb
+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:
+
+```sh
+$ 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](https://github.com/janko/shrine-rom/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](/LICENSE.txt)
+
+[ROM]: https://rom-rb.org
+[Shrine]: https://shrinerb.com
+[entity]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/entity.md#readme
+[model]: https://github.com/shrinerb/shrine/blob/master/doc/plugins/model.md#readme
+[dry-validation]: https://dry-rb.org/gems/dry-validation/
+[dry-container]: https://dry-rb.org/gems/dry-container/
+[demo]: /demo

data/lib/shrine/plugins/rom.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Plugins
+    module Rom
+      def self.load_dependencies(uploader)
+        uploader.plugin :entity
+        uploader.plugin :_persistence, plugin: self
+      end
+
+      module AttachmentMethods
+        # Disables model behaviour for ROM::Struct and Hanami::Entity
+        # subclasses.
+        def included(klass)
+          @model = false if klass < ::Dry::Struct
+          super
+        end
+      end
+
+      module AttacherMethods
+        attr_reader :repository
+
+        def initialize(repository: nil, **options)
+          super(**options)
+          @repository = repository
+        end
+
+        # The _persistence plugin uses #rom_persist, #rom_reload and #rom? to
+        # implement the following methods:
+        #
+        #   * Attacher#persist
+        #   * Attacher#atomic_persist
+        #   * Attacher#atomic_promote
+        private
+
+        # Updates the record with attachment column values. Used by the
+        # _persistence plugin.
+        def rom_persist
+          rom.update_record(column_values)
+        end
+
+        # Locks the database row and yields the reloaded record. Used by the
+        # _persistence plugin.
+        def rom_reload
+          rom.retrieve_record { |entity| yield entity }
+        end
+
+        # Returns true if the data attribute represents a JSON or JSONB column.
+        # Used by the _persistence plugin to determine whether serialization
+        # should be skipped.
+        def rom_hash_attribute?
+          return false unless repository
+
+          column = rom.column_type(attribute)
+          column && [:json, :jsonb].include?(column.to_sym)
+        end
+
+        # Returns whether the record is a ROM entity. Used by the _persistence
+        # plugin.
+        def rom?
+          record.is_a?(::ROM::Struct)
+        end
+
+        # Returns internal ROM wrapper object.
+        def rom
+          fail Shrine::Error, "repository is missing" unless repository
+
+          RomWrapper.new(repository: repository, record: record)
+        end
+      end
+
+      class RomWrapper
+        attr_reader :repository, :record_pk
+
+        def initialize(repository:, record: nil)
+          @repository = repository
+          @record_pk  = record.send(relation.primary_key)
+        end
+
+        def update_record(attributes)
+          repository.update(record_pk, attributes)
+        end
+
+        def retrieve_record
+          case adapter
+          when :sql
+            repository.transaction do
+              yield record_relation.lock.one!
+            end
+          else
+            yield record_relation.one!
+          end
+        end
+
+        def column_type(attribute)
+          # sends "json" or "jsonb" string for JSON or JSONB column.
+          # returns nil for String column
+          relation.schema[attribute].type.meta[:db_type]
+        end
+
+        private
+
+        def record_relation
+          case adapter
+          when :sql, :mongo   then relation.by_pk(record_pk)
+          when :elasticsearch then relation.get(record_pk)
+          else
+            fail Shrine::Error, "unsupported ROM adapter: #{adapter.inspect}"
+          end
+        end
+
+        def adapter
+          relation.adapter
+        end
+
+        def relation
+          repository.root
+        end
+      end
+    end
+
+    register_plugin(:rom, Rom)
+  end
+end

data/shrine-rom.gemspec

@@ -0,0 +1,23 @@
+Gem::Specification.new do |gem|
+  gem.name          = "shrine-rom"
+  gem.version       = "0.1.0"
+
+  gem.required_ruby_version = ">= 2.3"
+
+  gem.summary      = "Provides rom-rb integration for Shrine."
+  gem.homepage     = "https://github.com/shrinerb/shrine-rom"
+  gem.authors      = ["Janko Marohnić", "Ahmad Musaffa"]
+  gem.email        = ["janko.marohnic@gmail.com", "musaffa_csemm@yahoo.com"]
+  gem.license      = "MIT"
+
+  gem.files        = Dir["README.md", "LICENSE.txt", "lib/**/*.rb", "*.gemspec"]
+  gem.require_path = "lib"
+
+  gem.add_dependency "shrine", "~> 3.0"
+  gem.add_dependency "rom", "~> 5.0"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "minitest"
+  gem.add_development_dependency "rom-sql"
+  gem.add_development_dependency "sqlite3"
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: shrine-rom
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Janko Marohnić
+- Ahmad Musaffa
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shrine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rom
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rom-sql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- janko.marohnic@gmail.com
+- musaffa_csemm@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/shrine/plugins/rom.rb
+- shrine-rom.gemspec
+homepage: https://github.com/shrinerb/shrine-rom
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Provides rom-rb integration for Shrine.
+test_files: []