presigned_upload 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db1a9758dacddbb8efeffaf2b99b13c08fca378a82f93a628bba3b7ee38c5c3b
-  data.tar.gz: 93f42f25157570cdf9b036f513c53a588c3453c86777fe6157d58ec2b943a6c3
+  metadata.gz: ca293e74541ff82d393ac583e295699df5f5fbf80d32c2b4f4365fc820e76959
+  data.tar.gz: 75e337709fe872cf5f5fc71470017f37e5b6dc5266152ae166cec6d29fcc58bc
 SHA512:
-  metadata.gz: d5f58a70348ab99eb0ed36adcbca0d3d8f81336b76ea8c7206a9fc2cb4d9b4b4d0c215ecebcf4064ba722f694ce4be535bfcd45c3dc87446ad41f46b2ef9845b
-  data.tar.gz: 9e37103e3febbb2056ddadda8307d597d82c751d9fcd10de96eb4ec82fcdc9648fd80a688ef13bce0c72b632d6c9db93eca505a894f1fdc901c5aca04c08bb53
+  metadata.gz: ee83ec4b1fd4a499330eeb44eeaf0d75c5ac2f413109ef3fe41e4f555d3c1616d23fe4c819eeb761fa399e757177c71cf382045a0d1db058ac49422d1a8456a4
+  data.tar.gz: 4d57cc6b0317400c8637e2cfc71bed2a3bc3bfdfb04be6ab82d0a33fd0963f6ea68799697498543e651f958864e7299f7e1d0b1c8c0e650303d95a541c11c32a

data/CHANGELOG.md

@@ -3,3 +3,11 @@
 ## [0.1.0] - 2023-11-23
 
 - Initial release
+
+## [0.2.0] - 2024-07-25
+
+- Removed `store_path` attribute from migration
+- Moved `store_path` from `before_create` callback to `store_dir` instance method
+- The `store_path` now is mounted when it is called, joining `store_dir` + `original_name`
+- Added README documentation and installation instructions
+- Added `install_generator.rb` to generate the PresignedUpload default initializer

data/README.md

@@ -1,11 +1,13 @@
 # PresignedUpload
 
-Gem designed to control file uploads via presigned URLs to cloud storage services.
+Control file uploads via presigned URLs to cloud storage services.
 
 A presigned URL is generated by a server that grants temporary and controlled access to a specific resource. In the context of file uploads, it allows clients to directly upload files to a designated storage location without the server being directly involved in the transfer process.
 
 ## Installation
 
+### 1. Add the gem into your project
+
 Add this to your Gemfile and run `bundle install`.
 
 ```ruby
@@ -17,13 +19,168 @@ Or install it yourself as:
 gem install presigned_upload
 ```
 
+### 2. Create the initializer file
+
+Run the generator to create the initializer file:
+```sh
+rails g presigned_upload:install
+```
+
+### 3. Generate Uploadable Model
+
+Use the PresignedUpload generator to create your uploadable model.
+
+This model is intended to be a representation of access to a file, and also its basic informations. 
+
+For example, if you want create a UploadLink model, you can use:
+```sh
+rails g presigned_upload:uploadable_model UploadLink
+```
+If your database uses UUID for the primary and foreign keys, you can pass the `--uuid` option:
+```sh
+rails g presigned_upload:uploadable_model UploadLink --uuid
+```
+
+The generator will create the model with the given name and the migration file:
+```ruby
+# app/models/upload_link.rb
+class UploadLink < ApplicationRecord
+  presigned_uploadable_model
+end
+
+# This columns are required, but you can add more if you need.
+# For example, you can create a column called 'storage_size'
+#  to save the storage size of the file
+class CreateUploadLinks < ActiveRecord::Migration[7.0]
+  def change
+    create_table :upload_links, id: :uuid do |t|
+      t.string :original_name, null: false
+      t.string :content_type, null: false
+      t.string :upload_status, null: false
+
+      t.timestamps
+    end
+  end
+end
+```
+By default, an uploadable model contains:
+- `original_name`: The original name of the file
+- `content_type`: The content-type of the file _(Utile for validations)_
+- `upload_status`: The status of the upload process [`initial`, `completed`]
+
+### 4. Run the migration
+
+```
+rails db:migrate
+```
+
 ## Usage
 
-TODO: Write usage instructions here
+### Configuring initializer
+
+You can configure the presigned_upload initializer to set the storage service and its options.
+
+For AWS S3 for example, you going to need to add the `storage` to `:aws` and inform the `bucket` where you want to create presigned URLs in order to upload and access files:
+```ruby
+PresignedUpload.configure do |config|
+  config.storage = :aws
+  config.storage_options = {
+    bucket: 'my_bucket'
+  }
+end
+```
+
+**Important:** For an AWS configuration, you need to add the [AWS SDK for Ruby](https://github.com/aws/aws-sdk-ruby) in order to `PresignedUpload` gem to work correctly:
+```ruby
+gem 'aws-sdk-s3'
+```
+If you don't add this, an error will be raised when trying to run Rails.
+
+### Uploadable Model
+
+The uploadable model will be used to access files in the cloud storage services. Below there are some of the methods that can be accessed:
+```ruby
+# Returns a presigned URL for uploading the file
+# Only returns the URL if the upload_status is 'initial'
+upload_link.upload_url
+
+# Returns a presigned URL for accessing the stored file
+# Only returns the URL if the upload_status is 'completed'
+upload_link.url
+
+# Deletes the stored file from the cloud
+# This method is automatically called in before_destroy 
+#   callback when you destroy the record
+upload_link.delete_stored_file
+```
+
+In order to be able to use this methods, you need to configure the store directory where the file will be stored.
+
+#### Storage path
+
+By default, PresignedUpload inserts the method `presigned_uploadable_model` in your Model, that sets the value of the `store_dir` to: `"uploads/#{model_name.plural}/#{id}"`.
+
+The final `store_path` of the file in the cloud will be the junction between `store_dir` + `original_name`.
+
+So, in the example below, the file will be stored as `uploads/upload_links/123/my_file.txt`:
+```ruby
+class UploadLink < ApplicationRecord
+  presigned_uploadable_model
+end
+
+upload_link.id = '123'
+upload_link.original_name = 'my_file.txt'
+upload_link.store_path
+# => uploads/upload_links/123/my_file.txt
+```
+
+#### Changing the storage directory
+
+The `presigned_uploadable_model` method accepts the `:store_dir` option, that can be a `Symbol`, a `String` or a `Proc`.
+
+Using a string:
+```ruby
+class UploadLink < ApplicationRecord
+  presigned_uploadable_model store_dir: '/uploads/my/custom/path'
+end
+
+upload_link.original_name = 'my_file.txt'
+upload_link.store_path
+# => "/uploads/my/custom/path/my_file.txt"
+```
+
+Using a Proc:
+```ruby
+class UploadLink < ApplicationRecord
+  presigned_uploadable_model store_dir: -> { "/uploads/upload_links/#{id}" }
+end
+
+upload_link.id = '123'
+upload_link.original_name = 'my_file.txt'
+upload_link.store_path
+# => "/uploads/upload_links/123/my_file.txt"
+```
+
+Using a Symbol:
+```ruby
+class UploadLink < ApplicationRecord
+  presigned_uploadable_model store_dir: :my_custom_dir
+
+  # Using as a symbol, the code will expect a instance method with same name
+  def my_custom_dir
+    "/my/custom/dir/#{id}"
+  end
+end
+
+upload_link.id = '123'
+upload_link.original_name = 'my_file.txt'
+upload_link.store_path
+# => "/my/custom/dir/123/my_file.txt"
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/DenisStael/presigned_upload.
+Bug reports and pull requests are welcome on GitHub at https://github.com/denisstael/presigned_upload.
 
 ## License
 

data/lib/generators/presigned_upload/install_generator.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module PresignedUpload
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def generate_initializer
+      template "initializer.rb", "config/initializers/presigned_upload.rb"
+    end
+  end
+end

data/lib/generators/presigned_upload/templates/initializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Use this initializer to configure PresignedUpload.
+#
+PresignedUpload.configure do |config|
+  # Configure the storage option to define which storage service will be used.
+  config.storage = :aws
+
+  # Configure the storage_options for additional information about the choosen storage service.
+  config.storage_options = {
+    bucket: 'my_bucket'
+  }
+end

data/lib/generators/presigned_upload/templates/migration.rb

@@ -3,7 +3,6 @@ class Create<%= model_name.camelize.pluralize %> < ActiveRecord::Migration[7.0]
     create_table :<%= model_name.underscore.pluralize + migration_id_column %> do |t|
       t.string :original_name, null: false
       t.string :content_type, null: false
-      t.string :store_path, null: false
       t.string :upload_status, null: false
 
       t.timestamps

data/lib/presigned_upload/configuration.rb

@@ -17,10 +17,10 @@ module PresignedUpload
 
     def configure!
       unless AVAILABLE_STORAGES.include?(storage)
-        raise InvalidStorage, "Invalid storage. Allowed types are: #{AVAILABLE_STORAGES}"
+        raise InvalidStorage, "Invalid storage option. Allowed types are: #{AVAILABLE_STORAGES}"
       end
 
-      raise InvalidStorageConfig, "Empty storage configuration" if storage_options.empty?
+      raise InvalidStorageConfig, "Empty storage options configuration" if storage_options.empty?
 
       case storage
       when :aws

data/lib/presigned_upload/models.rb

@@ -31,33 +31,32 @@ module PresignedUpload
     # all the behavior from the Uploadable module and the Uploadable::Model, including validations and callbacks
     #
     # @param [Hash] options Options hash
-    # @option options [Symbol] :store_path The path to the storage location
+    # @option options [Symbol] :store_dir The path to the storage location directory
     #   Accepts a Symbol value, which will try to call a method with same name
-    #   in model, a String value representing the store path or a Proc to call
+    #   in model, a String value representing the store directory or a Proc to call
     #
     # @example
     #
     #   UploadLink < ApplicationRecord
-    #     presigned_uploadable_model, store_path: :generate_store_path
+    #     presigned_uploadable_model, store_dir: :generate_store_dir
     #   end
     #
     def presigned_uploadable_model(options = {})
       include Uploadable::Model
 
-      store_path = options[:store_path]
+      store_dir = options[:store_dir]
 
-      before_create do
-        self.store_path =
-          case store_path
-          when Symbol
-            __send__(store_path)
-          when String
-            store_path
-          when Proc
-            store_path.call
-          else
-            "uploads/#{model_name.plural}/#{original_name}"
-          end
+      define_method :store_dir do
+        case store_dir
+        when Symbol
+          __send__(store_dir)
+        when String
+          store_dir
+        when Proc
+          instance_exec(&store_dir)
+        else
+          "uploads/#{model_name.plural}/#{id}"
+        end
       end
     end
     # rubocop:enable Metrics/MethodLength

data/lib/presigned_upload/uploadable.rb

@@ -34,8 +34,6 @@ module PresignedUpload
       include Uploadable
 
       included do
-        attr_readonly :original_name, :content_type, :store_path
-
         validates :original_name, :content_type, :upload_status, presence: true
 
         enum upload_status: { initial: "initial", completed: "completed" }
@@ -54,14 +52,13 @@ module PresignedUpload
         presigned_url(store_path, :get)
       end
 
-      # Returns a presigned URL for uploading the file. Returns `nil` if the store path is blank or the
-      # upload status is 'completed'.
+      # Returns a presigned URL for uploading the file. Returns `nil` if the upload status is 'completed'.
       #
       # @return [String, nil] The presigned URL for uploading the file or `nil` if the upload status is
-      #   'completed' or store path is not present.
+      #   already marked as completed.
       #
       def upload_url
-        return if store_path.blank? || completed?
+        return if completed?
 
         presigned_url(store_path, :put)
       end
@@ -71,6 +68,18 @@ module PresignedUpload
       def delete_stored_file
         delete_file(store_path)
       end
+
+      # Returns the file store path.
+      #
+      # The store path is constructed by combining the storage directory
+      #   with the `original_name` of the file. If `store_dir` is present, it is
+      #   included in the path. If `store_dir` is not present, then the file
+      #   will be saved in the root directory.
+      #
+      # @return [String] the storage path for the uploaded file.
+      def store_path
+        "#{store_dir.present? ? "#{store_dir}/" : ""}#{original_name}"
+      end
     end
   end
 end

data/lib/presigned_upload/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PresignedUpload
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: presigned_upload
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Denis Stael
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-01 00:00:00.000000000 Z
+date: 2024-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -52,8 +52,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.4.2
-description: '    "This gem provides an easy way to handle direct file uploads to
-  cloud storage services via presigned URL."
+description: '    "Handle direct file uploads to cloud storage services via presigned
+  URLs."
 
   '
 email:
@@ -70,6 +70,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/generators/presigned_upload/install_generator.rb
+- lib/generators/presigned_upload/templates/initializer.rb
 - lib/generators/presigned_upload/templates/migration.rb
 - lib/generators/presigned_upload/templates/uploadable_model.rb
 - lib/generators/presigned_upload/uploadable_model_generator.rb
@@ -83,12 +85,13 @@ files:
 - lib/presigned_upload/storage.rb
 - lib/presigned_upload/uploadable.rb
 - lib/presigned_upload/version.rb
-homepage: https://github.com/DenisStael/presigned_upload
+homepage: https://github.com/denisstael/presigned_upload
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/DenisStael/presigned_upload
-  source_code_uri: https://github.com/DenisStael/presigned_upload
+  homepage_uri: https://github.com/denisstael/presigned_upload
+  source_code_uri: https://github.com/denisstael/presigned_upload
+  documentation_uri: https://rubydoc.info/gems/presigned_upload/0.2.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -107,6 +110,6 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
-summary: Control model associated files uploads via presigned URL to cloud storage
+summary: Control model associated files uploads via presigned URLs to cloud storage
   services.
 test_files: []