shrine-storage-azure-blob 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2474798e685e8b9e30617e60baf5080e0e6cc067a5bd6e90405ac8974764dc6
+  data.tar.gz: fdf8a79b46ad3bac570b7f8edfe11018959d7643fd5f64c19f0cc7cee3fd5dcd
+SHA512:
+  metadata.gz: 781b3b173790f2a53f971c0ebf866a53991f56272457cd4d67b386ae30c1210917e21d760ea5c3335d2cd8133a10e9994f8c128f199e5a331b477a5005c3109b
+  data.tar.gz: 2ac7731ca4a4c52595f7cece4cd1836c84cfacc4befc848f837f3322ae4214d8253b88ff6f7f9f2717411814b84b7dab48f9e1bc6af37d33496c46dbf1ecef56

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-22
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Galiia Fattakhova
+
+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/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Galiia Fattakhova
+
+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,156 @@
+# shrine-storage-azure-blob
+
+`shrine-storage-azure-blob` is a Shrine storage adapter for Azure Blob Storage.
+
+It supports:
+
+- direct uploads via short-lived SAS URLs
+- signed private read URLs
+- configurable container prefixes such as `cache/` and `store/`
+- private or public URL generation
+
+This adapter is built on top of the [`azure-blob`](https://rubygems.org/gems/azure-blob) gem.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add shrine-storage-azure-blob
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install shrine-storage-azure-blob
+```
+
+## Usage
+
+Require the adapter:
+
+```ruby
+require "shrine/storage/azure_blob"
+```
+
+Configure Shrine storages:
+
+```ruby
+Shrine.storages = {
+  cache: Shrine::Storage::AzureBlob.new(
+    account_name: ENV.fetch("STORAGE_ACCOUNT_NAME"),
+    access_key: ENV.fetch("STORAGE_ACCESS_KEY"),
+    container: ENV.fetch("STORAGE_CONTAINER", "uploads"),
+    prefix: "cache"
+  ),
+  store: Shrine::Storage::AzureBlob.new(
+    account_name: ENV.fetch("STORAGE_ACCOUNT_NAME"),
+    access_key: ENV.fetch("STORAGE_ACCESS_KEY"),
+    container: ENV.fetch("STORAGE_CONTAINER", "uploads"),
+    prefix: "store"
+  )
+}
+```
+
+### Direct uploads
+
+Use `#presign` to generate a short-lived SAS URL for browser uploads:
+
+```ruby
+presign = Shrine.storages[:cache].presign(
+  "example.png",
+  content_type: "image/png",
+  metadata: { filename: "example.png" }
+)
+```
+
+The return value is a hash with:
+
+- `:method`
+- `:url`
+- `:headers`
+
+The browser should upload the file directly to the returned Azure Blob URL with the returned headers.
+
+### Private file URLs
+
+By default, `#url` returns a signed private read URL:
+
+```ruby
+Shrine.storages[:store].url("avatars/user.png")
+```
+
+To generate public URLs instead, initialize the storage with `public: true`.
+
+### Container creation
+
+The adapter exposes `#ensure_container!`:
+
+```ruby
+Shrine.storages[:cache].ensure_container!
+```
+
+That is useful for bootstrapping empty environments, but in most deployments container creation should be handled by infrastructure or a deployment task.
+
+### Initialization options
+
+Supported initializer options:
+
+- `account_name:` Azure Storage Account name
+- `access_key:` Azure Storage Account access key
+- `container:` blob container name
+- `prefix:` optional blob key prefix
+- `host:` optional blob host override
+- `public:` if `true`, `#url` returns unsigned public URLs
+
+Additional keyword arguments are forwarded to `AzureBlob::Client`.
+
+## Notes
+
+- This adapter currently uses account key authentication.
+- Upload presigning uses Azure SAS URLs with create/write permissions.
+- Private read URLs use signed SAS URLs with read permission.
+- `ActionDispatch::Http::ContentDisposition` is used to format download disposition headers, so `actionpack` is a runtime dependency.
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bin/setup
+bundle exec rake test
+```
+
+You can also run:
+
+```bash
+bin/console
+```
+
+to experiment with the adapter interactively.
+
+To install this gem locally:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version in `lib/shrine/storage/azure_blob/version.rb`
+2. Commit the change
+3. Run:
+
+```bash
+bundle exec rake release
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub:
+
+- https://github.com/galiyafatt2/shrine-storage-azure-blob
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/shrine/storage/azure_blob/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Shrine
+  module Storage
+    class AzureBlob
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/shrine/storage/azure_blob.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "azure_blob"
+require "action_dispatch/http/content_disposition"
+require "shrine"
+require "stringio"
+require_relative "azure_blob/version"
+
+class Shrine
+  module Storage
+    class AzureBlob
+      DEFAULT_URL_TTL = 15 * 60
+
+      attr_reader :client, :container, :prefix
+
+      def initialize(account_name:, container:, access_key: nil, host: nil, prefix: nil, public: false, **options)
+        @container = container
+        @prefix = prefix
+        @public = public
+        @client = ::AzureBlob::Client.new(
+          account_name: account_name,
+          access_key: access_key,
+          container: container,
+          host: host,
+          **options
+        )
+      end
+
+      def upload(io, id, shrine_metadata: {}, **options)
+        client.create_block_blob(
+          path_for(id),
+          io.respond_to?(:rewind) ? rewindable(io) : io,
+          **upload_options(shrine_metadata, options)
+        )
+      end
+
+      def open(id, **options)
+        StringIO.new(fetch_blob(path_for(id), options)).tap(&:binmode)
+      rescue ::AzureBlob::Http::FileNotFoundError => e
+        raise Shrine::FileNotFound, e.message
+      end
+
+      def url(id, expires_in: DEFAULT_URL_TTL, filename: nil, disposition: nil, content_type: nil, public: @public, **)
+        return client.generate_uri("#{container}/#{path_for(id)}").to_s if public
+
+        client.signed_uri(
+          path_for(id),
+          permissions: "r",
+          expiry: format_expiry(expires_in),
+          content_disposition: content_disposition(disposition, filename),
+          content_type: content_type
+        ).to_s
+      end
+
+      def exists?(id)
+        client.blob_exist?(path_for(id))
+      end
+
+      def delete(id)
+        client.delete_blob(path_for(id))
+      rescue ::AzureBlob::Http::FileNotFoundError
+        nil
+      end
+
+      def delete_prefixed(prefix)
+        client.delete_prefix(path_for(prefix))
+      end
+
+      def clear!
+        delete_prefixed("")
+      end
+
+      def presign(id, method: "PUT", expires_in: DEFAULT_URL_TTL, content_type: nil, filename: nil, disposition: nil,
+                  metadata: {}, **)
+        headers = {
+          "x-ms-blob-type" => "BlockBlob"
+        }
+        headers["Content-Type"] = content_type if present?(content_type)
+
+        custom_metadata_headers(metadata).each do |header, value|
+          headers[header.to_s] = value
+        end
+
+        if (blob_content_disposition = content_disposition(disposition, filename))
+          headers["x-ms-blob-content-disposition"] = blob_content_disposition
+        end
+
+        {
+          method: method,
+          url: client.signed_uri(path_for(id), permissions: "cw", expiry: format_expiry(expires_in)).to_s,
+          headers: headers
+        }
+      end
+
+      def ensure_container!
+        return if client.container_exist?
+
+        client.create_container
+      end
+
+      private
+
+      def path_for(id)
+        [prefix, id].compact.reject { |part| blank?(part) }.join("/")
+      end
+
+      def fetch_blob(path, options)
+        blob = client.get_blob(path, extract_range_options(options)).dup
+        blob.force_encoding(Encoding::BINARY)
+      end
+
+      def extract_range_options(options)
+        {}.tap do |range_options|
+          range_options[:start] = options[:start] if options.key?(:start)
+          range_options[:end] = options[:end] if options.key?(:end)
+          range_options[:timeout] = options[:timeout] if options.key?(:timeout)
+        end
+      end
+
+      def rewindable(io)
+        io.rewind
+        io
+      end
+
+      def upload_options(shrine_metadata, options)
+        metadata = stringify_metadata(options.fetch(:metadata, {}))
+        metadata["filename"] ||= shrine_metadata["filename"] || shrine_metadata[:filename]
+
+        {
+          content_type: shrine_metadata["mime_type"] || shrine_metadata[:mime_type],
+          metadata: metadata
+        }.merge(compact_hash(reject_keys(options, :metadata)))
+      end
+
+      def stringify_metadata(metadata)
+        compact_hash(metadata.to_h.transform_keys(&:to_s).transform_values(&:to_s))
+      end
+
+      def format_expiry(expires_in)
+        (Time.now.utc + (expires_in || DEFAULT_URL_TTL)).iso8601
+      end
+
+      def content_disposition(disposition, filename)
+        return if blank?(disposition) || blank?(filename)
+
+        ActionDispatch::Http::ContentDisposition.format(disposition: disposition, filename: filename)
+      end
+
+      def custom_metadata_headers(metadata)
+        ::AzureBlob::Metadata.new(stringify_metadata(metadata)).headers
+      end
+
+      def compact_hash(hash)
+        hash.reject { |_, value| value.nil? }
+      end
+
+      def reject_keys(hash, *keys)
+        hash.reject { |key, _| keys.include?(key) }
+      end
+
+      def blank?(value)
+        !present?(value)
+      end
+
+      def present?(value)
+        case value
+        when nil then false
+        when String then !value.empty?
+        else true
+        end
+      end
+    end
+  end
+end

data/lib/shrine-storage-azure-blob.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "shrine/storage/azure_blob"

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: shrine-storage-azure-blob
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Galiia Fattakhova
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: azure-blob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: shrine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Provides a Shrine storage adapter for Azure Blob Storage with signed
+  upload and download URLs.
+email:
+- elizabeth.mor324@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/shrine-storage-azure-blob.rb
+- lib/shrine/storage/azure_blob.rb
+- lib/shrine/storage/azure_blob/version.rb
+homepage: https://github.com/galiyafatt2/shrine-storage-azure-blob
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/galiyafatt2/shrine-storage-azure-blob
+  changelog_uri: https://github.com/galiyafatt2/shrine-storage-azure-blob/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Azure Blob Storage adapter for Shrine
+test_files: []