shrine 2.14.0 → 2.15.0

data/lib/shrine/storage/file_system.rb

@@ -5,83 +5,6 @@ require "pathname"
 
 class Shrine
   module Storage
-    # The FileSystem storage handles uploads to the filesystem, and it is
-    # most commonly initialized with a "base" folder and a "prefix":
-    #
-    #     require "shrine/storage/file_system"
-    #
-    #     storage = Shrine::Storage::FileSystem.new("public", prefix: "uploads")
-    #     storage.url("image.jpg") #=> "/uploads/image.jpg"
-    #
-    # This storage will upload all files to "public/uploads", and the URLs of
-    # the uploaded files will start with "/uploads/*". This way you can use
-    # FileSystem for both cache and store, one having the prefix
-    # "uploads/cache" and other "uploads/store". If you're uploading files
-    # to the `public` directory itself, you need to set `:prefix` to `"/"`:
-    #
-    #     storage = Shrine::Storage::FileSystem.new("public", prefix: "/") # no prefix
-    #     storage.url("image.jpg") #=> "/image.jpg"
-    #
-    # You can also initialize the storage just with the "base" directory, and
-    # then the FileSystem storage will generate absolute URLs to files:
-    #
-    #     storage = Shrine::Storage::FileSystem.new(Dir.tmpdir)
-    #     storage.url("image.jpg") #=> "/var/folders/k7/6zx6dx6x7ys3rv3srh0nyfj00000gn/T/image.jpg"
-    #
-    # In general you can always retrieve path to the file using `#path`:
-    #
-    #     storage.path("image.jpg") #=> #<Pathname:public/image.jpg>
-    #
-    # ## Host
-    #
-    # It's generally a good idea to serve your files via a CDN, so an
-    # additional `:host` option can be provided to `#url`:
-    #
-    #     storage = Shrine::Storage::FileSystem.new("public", prefix: "uploads")
-    #     storage.url("image.jpg", host: "http://abc123.cloudfront.net")
-    #     #=> "http://abc123.cloudfront.net/uploads/image.jpg"
-    #
-    # If you're not using a CDN, it's recommended that you still set `:host` to
-    # your application's domain (at least in production).
-    #
-    # The `:host` option can also be used wihout `:prefix`, and is
-    # useful if you for example have files located on another server:
-    #
-    #     storage = Shrine::Storage::FileSystem.new("/opt/files")
-    #     storage.url("image.jpg", host: "http://943.23.43.1")
-    #     #=> "http://943.23.43.1/opt/files/image.jpg"
-    #
-    # ## Clearing cache
-    #
-    # If you're using FileSystem as cache, you will probably want to
-    # periodically delete old files which aren't used anymore. You can run
-    # something like this periodically:
-    #
-    #     file_system = Shrine.storages[:cache]
-    #     file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
-    #
-    # ## Permissions
-    #
-    # The storage sets the default UNIX permissions to 0644 for files and 0755
-    # for directories, but you can change that:
-    #
-    #     Shrine::Storage::FileSystem.new("directory", permissions: 0644)
-    #     Shrine::Storage::FileSystem.new("directory", directory_permissions: 0755)
-    #
-    # ## Heroku
-    #
-    # Note that Heroku has a read-only filesystem, and doesn't allow you to
-    # upload your files to the "public" directory, you can however upload to
-    # "tmp" directory:
-    #
-    #     Shrine::Storage::FileSystem.new("tmp/uploads")
-    #
-    # Note that this approach has a couple of downsides. For example, you can
-    # only use it for cache, since Heroku wipes this directory between app
-    # restarts. This also means that deploying the app can cancel someone's
-    # uploading if you're using backgrounding. Also, by default you cannot
-    # generate URLs to files in the "tmp" directory, but you can with the
-    # `download_endpoint` plugin.
     class FileSystem
       attr_reader :directory, :prefix, :host, :permissions, :directory_permissions
 

data/lib/shrine/storage/s3.rb

@@ -25,255 +25,6 @@ require "tempfile"
 
 class Shrine
   module Storage
-    # The S3 storage handles uploads to Amazon S3 service, using the
-    # [aws-sdk-s3] gem:
-    #
-    #     gem "aws-sdk-s3", "~> 1.2"
-    #
-    # It can be initialized by providing the bucket name and credentials:
-    #
-    #     require "shrine/storage/s3"
-    #
-    #     s3 = Shrine::Storage::S3.new(
-    #       bucket: "my-app", # required
-    #       access_key_id: "abc",
-    #       secret_access_key: "xyz",
-    #       region: "eu-west-1",
-    #     )
-    #
-    # The core features of this storage require the following AWS permissions:
-    # `s3:ListBucket`, `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`.
-    # If you have additional upload options configured such as setting object
-    # ACLs, then additional permissions may be required.
-    #
-    # The storage exposes the underlying Aws objects:
-    #
-    #     s3.client #=> #<Aws::S3::Client>
-    #     s3.client.access_key_id #=> "abc"
-    #     s3.client.secret_access_key #=> "xyz"
-    #     s3.client.region #=> "eu-west-1"
-    #
-    #     s3.bucket #=> #<Aws::S3::Bucket>
-    #     s3.bucket.name #=> "my-app"
-    #
-    #     s3.object("key") #=> #<Aws::S3::Object>
-    #
-    # ## Public uploads
-    #
-    # By default, uploaded S3 objects will have private visibility, meaning
-    # they can only be accessed via signed expiring URLs generated using your
-    # private S3 credentials. If you would like to generate public URLs, you
-    # can tell S3 storage to make uploads public:
-    #
-    #     s3 = Shrine::Storage::S3.new(public: true, **s3_options)
-    #
-    #     s3.upload(io, "key") # uploads with "public-read" ACL
-    #     s3.url("key")        # returns public (unsigned) object URL
-    #
-    # ## Prefix
-    #
-    # The `:prefix` option can be specified for uploading all files inside
-    # a specific S3 prefix (folder), which is useful when using S3 for both
-    # cache and store:
-    #
-    #     Shrine::Storage::S3.new(prefix: "cache", **s3_options)
-    #
-    # ## Upload options
-    #
-    # Sometimes you'll want to add additional upload options to all S3 uploads.
-    # You can do that by passing the `:upload` option:
-    #
-    #     Shrine::Storage::S3.new(upload_options: { acl: "private" }, **s3_options)
-    #
-    # These options will be passed to aws-sdk-s3's methods for [uploading],
-    # [copying] and [presigning].
-    #
-    # You can also generate upload options per upload with the `upload_options`
-    # plugin
-    #
-    #     class MyUploader < Shrine
-    #       plugin :upload_options, store: ->(io, context) do
-    #         if context[:version] == :thumb
-    #           {acl: "public-read"}
-    #         else
-    #           {acl: "private"}
-    #         end
-    #       end
-    #     end
-    #
-    # or when using the uploader directly
-    #
-    #     uploader.upload(file, upload_options: { acl: "private" })
-    #
-    # Note that, unlike the `:upload_options` storage option, upload options
-    # given on the uploader level won't be forwarded for generating presigns,
-    # since presigns are generated using the storage directly.
-    #
-    # ## URL options
-    #
-    # This storage supports various URL options that will be forwarded from
-    # uploaded file.
-    #
-    #     s3.url(public: true)   # public URL without signed parameters
-    #     s3.url(download: true) # forced download URL
-    #
-    # All other options are forwarded to the aws-sdk-s3 gem:
-    #
-    #     s3.url(expires_in: 15, response_content_disposition: "...")
-    #
-    # ## URL Host
-    #
-    # If you want your S3 object URLs to be generated with a different URL host
-    # (e.g. a CDN), you can specify the `:host` option to `#url`:
-    #
-    #     s3.url("image.jpg", host: "http://abc123.cloudfront.net")
-    #     #=> "http://abc123.cloudfront.net/image.jpg"
-    #
-    # The host URL can include a path prefix, but it needs to end with a slash:
-    #
-    #     s3.url("image.jpg", host: "https://your-s3-host.com/prefix/") # needs to end with a slash
-    #     #=> "http://your-s3-host.com/prefix/image.jpg"
-    #
-    # To have the `:host` option passed automatically for every URL, use the
-    # `default_url_options` plugin.
-    #
-    #     plugin :default_url_options, store: { host: "http://abc123.cloudfront.net" }
-    #
-    # If you would like to [serve private content via CloudFront], you need to
-    # sign the object URLs with a special signer, such as
-    # [`Aws::CloudFront::UrlSigner`] provided by the `aws-sdk-cloudfront` gem.
-    # The S3 storage initializer accepts a `:signer` block, which you can use
-    # to call your signer:
-    #
-    #
-    #     require "aws-sdk-cloudfront"
-    #
-    #     signer = Aws::CloudFront::UrlSigner.new(
-    #       key_pair_id:      "cf-keypair-id",
-    #       private_key_path: "./cf_private_key.pem"
-    #     )
-    #
-    #     Shrine::Storage::S3.new(signer: signer.method(:signed_url))
-    #     # or
-    #     Shrine::Storage::S3.new(signer: -> (url, **options) { signer.signed_url(url, **options) })
-    #
-    # ## Presigns
-    #
-    # The `#presign` method can be used for generating paramters for direct
-    # uploads to Amazon S3:
-    #
-    #     s3.presign("/path/to/file") #=>
-    #     # {
-    #     #   url: "https://my-bucket.s3.amazonaws.com/...",
-    #     #   fields: { ... },  # blank for PUT presigns
-    #     #   headers: { ... }, # blank for POST presigns
-    #     #   method: "post",
-    #     # }
-    #
-    # Additional presign options can be given in three places:
-    #
-    # * in `Storage::S3#presign` by forwarding options
-    # * in `:upload_options` option on this storage
-    # * in `presign_endpoint` plugin through `:presign_options`
-    #
-    # ## Large files
-    #
-    # The aws-sdk-s3 gem has the ability to automatically use multipart
-    # upload/copy for larger files, splitting the file into multiple chunks
-    # and uploading/copying them in parallel.
-    #
-    # By default any files that are uploaded will use the multipart upload
-    # if they're larger than 15MB, and any files that are copied will use the
-    # multipart copy if they're larger than 150MB, but you can change the
-    # thresholds via `:multipart_threshold`.
-    #
-    #     thresholds = { upload: 30*1024*1024, copy: 200*1024*1024 }
-    #     Shrine::Storage::S3.new(multipart_threshold: thresholds, **s3_options)
-    #
-    # If you want to change how many threads aws-sdk-s3 will use for multipart
-    # upload/copy, you can use the `upload_options` plugin to specify
-    # `:thread_count`.
-    #
-    #     plugin :upload_options, store: -> (io, context) do
-    #       { thread_count: 5 }
-    #     end
-    #
-    # ## Encryption
-    #
-    # The easiest way to use server-side encryption for uploaded S3 objects is
-    # to configure default encryption for your S3 bucket. Alternatively, you
-    # can pass server-side encryption parameters to the API calls.
-    #
-    # The `#upload` method accepts `:sse_*` options:
-    #
-    #     s3.upload(io, "key", sse_customer_algorithm: "AES256",
-    #                          sse_customer_key:       "secret_key",
-    #                          sse_customer_key_md5:   "secret_key_md5",
-    #                          ssekms_key_id:          "key_id")
-    #
-    # The `#presign` method accepts `:server_side_encryption_*` options for
-    # POST presigns, and the same `:sse_*` options as above for PUT presigns.
-    #
-    #     s3.presign("key", server_side_encryption_customer_algorithm: "AES256",
-    #                       server_side_encryption_customer_key:       "secret_key",
-    #                       server_side_encryption_aws_kms_key_id:     "key_id")
-    #
-    # When downloading encrypted S3 objects, the same server-side encryption
-    # parameters need to be passed in.
-    #
-    #     s3.download("key", sse_customer_algorithm: "AES256",
-    #                        sse_customer_key:       "secret_key",
-    #                        sse_customer_key_md5:   "secret_key_md5")
-    #
-    #     s3.open("key", sse_customer_algorithm: "AES256",
-    #                    sse_customer_key:       "secret_key",
-    #                    sse_customer_key_md5:   "secret_key_md5")
-    #
-    # If you want to use client-side encryption instead, you can instantiate
-    # the storage with an `Aws::S3::Encryption::Client` instance.
-    #
-    #     client = Aws::S3::Encryption::Client.new(
-    #       kms_key_id: "alias/my-key"
-    #     )
-    #
-    #     Shrine::Storage::S3(client: client, bucket: "my-bucket")
-    #
-    # ## Accelerate endpoint
-    #
-    # To use Amazon S3's [Transfer Acceleration] feature, you can change the
-    # `:endpoint` of the underlying client to the accelerate endpoint, and this
-    # will be applied both to regular and presigned uploads, as well as
-    # download URLs.
-    #
-    #     Shrine::Storage::S3.new(endpoint: "https://s3-accelerate.amazonaws.com")
-    #
-    # ## Clearing cache
-    #
-    # If you're using S3 as a cache, you will probably want to periodically
-    # delete old files which aren't used anymore. S3 has a built-in way to do
-    # this, read [this article][object lifecycle] for instructions.
-    #
-    # Alternatively you can periodically call the `#clear!` method:
-    #
-    #     # deletes all objects that were uploaded more than 7 days ago
-    #     s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 }
-    #
-    # ## Request Rate and Performance Guidelines
-    #
-    # Amazon S3 automatically scales to high request rates. For example, your
-    # application can achieve at least 3,500 PUT/POST/DELETE and 5,500 GET
-    # requests per second per prefix in a bucket (a prefix is a top-level
-    # "directory" in the bucket). If your app needs to support higher request
-    # rates to S3 than that, you can scale exponentially by using more prefixes.
-    #
-    # [uploading]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
-    # [copying]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#copy_from-instance_method
-    # [presigning]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#presigned_post-instance_method
-    # [aws-sdk-s3]: https://github.com/aws/aws-sdk-ruby/tree/master/gems/aws-sdk-s3
-    # [Transfer Acceleration]: http://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html
-    # [object lifecycle]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Object.html#put-instance_method
-    # [serve private content via CloudFront]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/PrivateContent.html
-    # [`Aws::CloudFront::UrlSigner`]: https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/CloudFront/UrlSigner.html
     class S3
       attr_reader :client, :bucket, :prefix, :host, :upload_options, :signer, :public
 

data/lib/shrine/version.rb

@@ -7,7 +7,7 @@ class Shrine
 
   module VERSION
     MAJOR = 2
-    MINOR = 14
+    MINOR = 15
     TINY  = 0
     PRE   = nil
 

data/shrine.gemspec

@@ -23,7 +23,7 @@ direct uploads for fully asynchronous user experience.
   gem.email        = ["janko.marohnic@gmail.com"]
   gem.license      = "MIT"
 
-  gem.files        = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "shrine.gemspec", "doc/*.md"]
+  gem.files        = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "shrine.gemspec", "doc/**/*.md"]
   gem.require_path = "lib"
 
   gem.add_dependency "down", "~> 4.1"
@@ -52,5 +52,5 @@ direct uploads for fully asynchronous user experience.
 
   gem.add_development_dependency "sequel"
   gem.add_development_dependency "activerecord", "~> 5.2.0"
-  gem.add_development_dependency "sqlite3" unless RUBY_ENGINE == "jruby"
+  gem.add_development_dependency "sqlite3", "~> 1.3.6" unless RUBY_ENGINE == "jruby"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shrine
 version: !ruby/object:Gem::Version
-  version: 2.14.0
+  version: 2.15.0
 platform: ruby
 authors:
 - Janko Marohnić
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-27 00:00:00.000000000 Z
+date: 2019-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: down
@@ -336,16 +336,16 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.6
 description: |
   Shrine is a toolkit for file attachments in Ruby applications. It supports
   uploading, downloading, processing and deleting IO objects, backed by various
@@ -376,11 +376,90 @@ files:
 - doc/migrating_storage.md
 - doc/multiple_files.md
 - doc/paperclip.md
+- doc/plugins/activerecord.md
+- doc/plugins/add_metadata.md
+- doc/plugins/backgrounding.md
+- doc/plugins/backup.md
+- doc/plugins/cached_attachment_data.md
+- doc/plugins/copy.md
+- doc/plugins/data_uri.md
+- doc/plugins/default_storage.md
+- doc/plugins/default_url.md
+- doc/plugins/default_url_options.md
+- doc/plugins/delete_promoted.md
+- doc/plugins/delete_raw.md
+- doc/plugins/derivation_endpoint.md
+- doc/plugins/determine_mime_type.md
+- doc/plugins/direct_upload.md
+- doc/plugins/download_endpoint.md
+- doc/plugins/dynamic_storage.md
+- doc/plugins/hooks.md
+- doc/plugins/included.md
+- doc/plugins/infer_extension.md
+- doc/plugins/keep_files.md
+- doc/plugins/logging.md
+- doc/plugins/metadata_attribues.md
+- doc/plugins/migration_helpers.md
+- doc/plugins/module_include.md
+- doc/plugins/moving.md
+- doc/plugins/multi_delete.md
+- doc/plugins/parallelize.md
+- doc/plugins/parsed_json.md
+- doc/plugins/presign_endpoint.md
+- doc/plugins/pretty_location.md
+- doc/plugins/processing.md
+- doc/plugins/rack_file.md
+- doc/plugins/rack_response.md
+- doc/plugins/recache.md
+- doc/plugins/refresh_metadata.md
+- doc/plugins/remote_url.md
+- doc/plugins/remove_attachment.md
+- doc/plugins/remove_invalid.md
+- doc/plugins/restore_cached_data.md
+- doc/plugins/sequel.md
+- doc/plugins/signature.md
+- doc/plugins/store_dimensions.md
+- doc/plugins/tempfile.md
+- doc/plugins/upload_endpoint.md
+- doc/plugins/upload_options.md
+- doc/plugins/validation_helpers.md
+- doc/plugins/versions.md
 - doc/processing.md
 - doc/refile.md
 - doc/regenerating_versions.md
+- doc/release_notes/1.0.0.md
+- doc/release_notes/1.1.0.md
+- doc/release_notes/1.2.0.md
+- doc/release_notes/1.3.0.md
+- doc/release_notes/1.4.0.md
+- doc/release_notes/1.4.1.md
+- doc/release_notes/1.4.2.md
+- doc/release_notes/2.0.0.md
+- doc/release_notes/2.0.1.md
+- doc/release_notes/2.1.0.md
+- doc/release_notes/2.1.1.md
+- doc/release_notes/2.10.0.md
+- doc/release_notes/2.10.1.md
+- doc/release_notes/2.11.0.md
+- doc/release_notes/2.12.0.md
+- doc/release_notes/2.13.0.md
+- doc/release_notes/2.14.0.md
+- doc/release_notes/2.15.0.md
+- doc/release_notes/2.2.0.md
+- doc/release_notes/2.3.0.md
+- doc/release_notes/2.3.1.md
+- doc/release_notes/2.4.0.md
+- doc/release_notes/2.4.1.md
+- doc/release_notes/2.5.0.md
+- doc/release_notes/2.6.0.md
+- doc/release_notes/2.6.1.md
+- doc/release_notes/2.7.0.md
+- doc/release_notes/2.8.0.md
+- doc/release_notes/2.9.0.md
 - doc/retrieving_uploads.md
 - doc/securing_uploads.md
+- doc/storage/file_system.md
+- doc/storage/s3.md
 - doc/testing.md
 - doc/validation.md
 - lib/shrine.rb
@@ -401,6 +480,7 @@ files:
 - lib/shrine/plugins/default_url_options.rb
 - lib/shrine/plugins/delete_promoted.rb
 - lib/shrine/plugins/delete_raw.rb
+- lib/shrine/plugins/derivation_endpoint.rb
 - lib/shrine/plugins/determine_mime_type.rb
 - lib/shrine/plugins/direct_upload.rb
 - lib/shrine/plugins/download_endpoint.rb