azure-blob 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f2d1c40dbc979782d017b025e5369f21e8ec9c1de02e50ef030648b8fd557b
-  data.tar.gz: d818c311fb5a55db068d1b6d7e8d112d0fc44aa5f862144ec789ce3e3cd97a99
+  metadata.gz: 7eab2543de0e2e4663211095fd459507761bf270038308464723270506f63ac5
+  data.tar.gz: 1c0b7016bf21df9c1134be50eb2555f14f9f4b76e9a8664e70e003cee5b04208
 SHA512:
-  metadata.gz: 9f58536a8295aa300c0be73a4654e2a888a51db9c7acc0bb793297c3878c39947aef7bf25c4231ab30e2ee764bd65a3f5c5863d0a2b5b555bf9c7bd976abeb13
-  data.tar.gz: ae0f1e93eaff5c7f196fa78b6cf230f6be2a3c05cb4ba9635eb19828539cf381c8c23415453678ea19e790d860b65180260e9175ad1c825cb904047b09893047
+  metadata.gz: 6f03e61001c0c41ed31661116d5f7ed5d5f95f91e8ded26d40aa72d446119e835c281d852904e00b02f68fd536d0451e4e71401410ab41ec68f7ff97fb030a88
+  data.tar.gz: b0b1beb93ad7b3950bddb41dfb6e04354e08b46e29f5f3db5d474ddd4964cd09d65776a1f57625d103d1e56e9a0d235579372c74a867fa2080beabcfc757395f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
-## [0.1.0] - 2024-04-05
+## [0.4.2] 2024-06-06
 
-- Initial release
+Documentation
+
+## [0.4.1] 2024-05-27
+
+First working release.
+
+- Re-implemented the required parts of the azure-storage-blob API to make Active Storage work.
+- Extracted the AzureStorage adapter from Rails.

data/README.md

@@ -2,9 +2,45 @@
 
 This gem was built to replace azure-storage-blob (deprecated) in Active Storage, but was written to be Rails agnostic.
 
+## Active Storage
+
+## Migration
+To migrate from azure-storage-blob to azure-blob:
+
+1. Replace `azure-storage-blob` in your Gemfile with `azure-blob`
+2. Run `bundle install`
+3. Change the `AzureStorage` service to `AzureBlob`  in your Active Storage config (`config/storage.yml`)
+4. Restart or deploy the app.
+
+
+## Standalone
+
+Instantiate a client with your account name, an access key and the container name:
+
+```ruby
+client = AzureBlob::Client.new(
+      account_name: @account_name,
+      access_key: @access_key,
+      container: @container,
+    )
+
+path = "some/new/file"
+
+# Upload
+client.create_block_blob(path, "Hello world!")
+
+# Download
+client.get_blob(path) #=> "Hello world!"
+
+# Delete
+client.delete_blob(path)
+```
+
+For the full list of methods: https://www.rubydoc.info/gems/azure-blob/AzureBlob/Client
+
 ## Contributing
 
-### dev environment
+### Dev environment
 
 Ensure your version of Ruby fit the minimum version in `azure-blob.gemspec`
 
@@ -19,24 +55,14 @@ and setup those Env variables:
 A dev environment setup is also supplied through Nix with [devenv](https://devenv.sh/).
 
 To use the Nix environment:
-1- install [devenv](https://devenv.sh/)
-2- Copy `devenv.local.nix.example` to `devenv.local.nix`
-3- Insert your azure credentials into `devenv.local.nix`
-4- Start the shell with `devenv shell` or with [direnv](https://direnv.net/).
+1. install [devenv](https://devenv.sh/)
+2. Copy `devenv.local.nix.example` to `devenv.local.nix`
+3. Insert your azure credentials into `devenv.local.nix`
+4. Start the shell with `devenv shell` or with [direnv](https://direnv.net/).
 
 ### Tests
 
-`bin/rake test`.
-
-# Active Storage
-
-## Migration
-To migrate from azure-storage-blob to azure-blob:
-
-1- Replace `azure-storage-blob` in your Gemfile with `azure-blob`
-2- Run `bundle install`
-3- change the `AzureStorage` service to `AzureBlob`  in your Active Storage config (`config/storage.yml`)
-4- Restart or deploy the app.
+`bin/rake test`
 
 ## License
 

data/Rakefile

@@ -2,7 +2,21 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
+require 'azure_blob'
 
 Minitest::TestTask.create
 
 task default: %i[test]
+
+task :flush_test_container do |t|
+  AzureBlob::Client.new(
+    account_name: ENV["AZURE_ACCOUNT_NAME"],
+    access_key: ENV["AZURE_ACCESS_KEY"],
+    container: ENV["AZURE_PRIVATE_CONTAINER"],
+  ).delete_prefix ''
+  AzureBlob::Client.new(
+    account_name: ENV["AZURE_ACCOUNT_NAME"],
+    access_key: ENV["AZURE_ACCESS_KEY"],
+    container: ENV["AZURE_PUBLIC_CONTAINER"],
+  ).delete_prefix ''
+end

data/azure-blob.gemspec

@@ -9,13 +9,13 @@ Gem::Specification.new do |spec|
   spec.email = [ "joe@dupuis.io" ]
 
   spec.summary = "Azure blob client"
-  spec.homepage = "https://github.com/JoeDupuis/azure-blob"
+  spec.homepage = "https://github.com/testdouble/azure-blob"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.1"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["changelog_uri"] = "https://github.com/JoeDupuis/azure-blob/blob/main/CHANGELOG.md"
+  spec.metadata["changelog_uri"] = "https://github.com/testdouble/azure-blob/blob/main/CHANGELOG.md"
 
   spec.add_dependency "rexml"
 

data/lib/active_storage/service/azure_blob_service.rb

@@ -25,13 +25,13 @@
 require "active_support/core_ext/numeric/bytes"
 require "active_storage/service"
 
-require 'azure_blob'
+require "azure_blob"
 
 module ActiveStorage
-  # = Active Storage \Azure Storage \Service
+  # = Active Storage \Azure Blob \Service
   #
   # Wraps the Microsoft Azure Storage Blob Service as an Active Storage service.
-  # See ActiveStorage::Service for the generic API documentation that applies to all services.
+  # See {ActiveStorage::Service}[https://api.rubyonrails.org/classes/ActiveStorage/Service.html] for more details.
   class Service::AzureBlobService < Service
     attr_reader :client, :container, :signer
 

data/lib/azure_blob/blob.rb

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 
 module AzureBlob
+  # AzureBlob::Blob holds the metada for a given Blob.
   class Blob
+    # You should not instanciate this object directly,
+    # but obtain one when calling relevant methods of AzureBlob::Client.
+    #
+    # Expects a Net::HTTPResponse object from a
+    # HEAD or GET request to a blob uri.
     def initialize(response)
       @response = response
     end
@@ -26,6 +32,7 @@ module AzureBlob
       response.code == "200"
     end
 
+    # Returns the custom Azure metada tagged on the blob.
     def metadata
       @metadata || response
         .to_hash

data/lib/azure_blob/blob_list.rb

@@ -3,10 +3,28 @@
 require "rexml"
 
 module AzureBlob
+  # Enumerator class to lazily iterate over a list of Blob keys.
   class BlobList
     include REXML
     include Enumerable
 
+    # You should not instanciate this object directly,
+    # but obtain one when calling relevant methods of AzureBlob::Client.
+    #
+    # Expects a callable object that takes an Azure API page marker as an
+    # argument and returns the raw body response of a call to the list blob endpoint.
+    #
+    # Example:
+    #
+    #   fetcher = ->(marker) do
+    #     uri.query = URI.encode_www_form(
+    #       marker: marker,
+    #       ...
+    #     )
+    #     response = Http.new(uri, signer:).get
+    #   end
+    #   AzureBlob::BlobList.new(fetcher)
+    #
     def initialize(fetcher)
       @fetcher = fetcher
     end

data/lib/azure_blob/block_list.rb

@@ -3,7 +3,9 @@
 require "rexml"
 
 module AzureBlob
-  class BlockList
+  class BlockList # :nodoc:
+    # Internal
+    # BlockList builds the XML list of blocks to commit to a blob
     include REXML
     def initialize(blocks)
       @blocks = blocks

data/lib/azure_blob/canonicalized_headers.rb

@@ -1,5 +1,5 @@
 module AzureBlob
-  class CanonicalizedHeaders
+  class CanonicalizedHeaders # :nodoc:
     STANDARD_HEADERS = [
       :"x-ms-version",
     ]

data/lib/azure_blob/canonicalized_resource.rb

@@ -1,7 +1,7 @@
 require "cgi"
 
 module AzureBlob
-  class CanonicalizedResource
+  class CanonicalizedResource # :nodoc:
     def initialize(uri, account_name, service_name: nil, url_safe: true)
       # This next line is needed because CanonicalizedResource
       # need to be escaped for auhthorization headers, but not SAS tokens

data/lib/azure_blob/client.rb

@@ -9,6 +9,8 @@ require "time"
 require "base64"
 
 module AzureBlob
+  # AzureBlob Client class. You interact with the Azure Blob api
+  # through an instance of this class.
   class Client
     def initialize(account_name:, access_key:, container:)
       @account_name = account_name
@@ -16,6 +18,27 @@ module AzureBlob
       @signer = Signer.new(account_name:, access_key:)
     end
 
+    # Create a blob of type block. Will automatically split the the blob in multiple block and send the blob in pieces (blocks) if the blob is too big.
+    #
+    # When the blob is small enough this method will send the blob through {Put Blob}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob]
+    #
+    # If the blob is too big, the blob is split in blocks sent through a series of {Put Block}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block] requests
+    # followed by a {Put Block List}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-list] to commit the block list.
+    #
+    # Takes a key (path), the content (String or IO object), and options.
+    #
+    # Options:
+    #
+    # [+:content_type+]
+    #   Will be saved on the blob in Azure.
+    # [+:content_disposition+]
+    #   Will be saved on the blob in Azure.
+    # [+:content_md5+]
+    #   Will ensure integrity of the upload. The checksum must be a base64 digest. Can be produced with +OpenSSL::Digest::MD5.base64digest+.
+    #   The checksum is only checked on a single upload! To verify checksum when uploading multiple blocks, call directly put_blob_block with
+    #   a checksum for each block, then commit the blocks with commit_blob_blocks.
+    # [+:block_size+]
+    #   Block size in bytes, can be used to force the method to split the upload in smaller chunk. Defaults to +AzureBlob::DEFAULT_BLOCK_SIZE+ and cannot be bigger than +AzureBlob::MAX_UPLOAD_SIZE+
     def create_block_blob(key, content, options = {})
       if content.size > (options[:block_size] || DEFAULT_BLOCK_SIZE)
         put_blob_multiple(key, content, **options)
@@ -24,6 +47,18 @@ module AzureBlob
       end
     end
 
+    # Returns the full or partial content of the blob
+    #
+    # Calls to the {Get Blob}[https://learn.microsoft.com/en-us/rest/api/storageservices/get-blob] endpoint.
+    #
+    # Takes a key (path) and options.
+    #
+    # Options:
+    #
+    # [+:start+]
+    #   Starting point in bytes
+    # [+:end+]
+    #   Ending point in bytes
     def get_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
 
@@ -34,6 +69,15 @@ module AzureBlob
       Http.new(uri, headers, signer:).get
     end
 
+    # Delete a blob
+    #
+    # Calls to {Delete Blob}[https://learn.microsoft.com/en-us/rest/api/storageservices/delete-blob]
+    #
+    # Takes a key (path) and options.
+    #
+    # Options:
+    # [+:delete_snapshots+]
+    #   Sets the value of the x-ms-delete-snapshots header. Default to +include+
     def delete_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
 
@@ -44,11 +88,28 @@ module AzureBlob
       Http.new(uri, headers, signer:).delete
     end
 
+    # Delete all blobs prefixed by the given prefix.
+    #
+    # Calls to {List blobs}[https://learn.microsoft.com/en-us/rest/api/storageservices/list-blobs]
+    # followed to a series of calls to {Delete Blob}[https://learn.microsoft.com/en-us/rest/api/storageservices/delete-blob]
+    #
+    # Takes a prefix and options
+    #
+    # Look delete_blob for the list of options.
     def delete_prefix(prefix, options = {})
       results = list_blobs(prefix:)
       results.each { |key| delete_blob(key) }
     end
 
+    # Returns a BlobList containing a list of keys (paths)
+    #
+    # Calls to {List blobs}[https://learn.microsoft.com/en-us/rest/api/storageservices/list-blobs]
+    #
+    # Options:
+    # [+:prefix+]
+    #   Prefix of the blobs to be listed. Defaults to listing everything in the container.
+    # [:+max_results+]
+    #   Maximum number of results to return per page.
     def list_blobs(options = {})
       uri = generate_uri(container)
       query = {
@@ -69,6 +130,11 @@ module AzureBlob
       BlobList.new(fetcher)
     end
 
+    # Returns a Blob object without the content.
+    #
+    # Calls to {Get Blob Properties}[https://learn.microsoft.com/en-us/rest/api/storageservices/get-blob-properties]
+    #
+    # This can be used to see if the blob exist or obtain metada such as content type, disposition, checksum or Azure custom metadata.
     def get_blob_properties(key, options = {})
       uri = generate_uri("#{container}/#{key}")
 
@@ -77,16 +143,37 @@ module AzureBlob
       Blob.new(response)
     end
 
+    # Return a URI object to a resource in the container. Takes a path.
+    #
+    # Example: +generate_uri("#{container}/#{key}")+
     def generate_uri(path)
       URI.parse(URI::DEFAULT_PARSER.escape(File.join(host, path)))
     end
 
+    # Returns an SAS signed URI
+    #
+    # Takes a
+    # - key (path)
+    # - A permission string (+"r"+, +"rw"+)
+    # - expiry as a UTC iso8601 time string
+    # - options
     def signed_uri(key, permissions:, expiry:, **options)
       uri = generate_uri("#{container}/#{key}")
       uri.query = signer.sas_token(uri, permissions:, expiry:, **options)
       uri
     end
 
+    # Creates a Blob of type append.
+    #
+    # Calls to {Put Blob}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob]
+    #
+    # You are expected to append blocks to the blob with append_blob_block after creating the blob.
+    # Options:
+    #
+    # [+:content_type+]
+    #   Will be saved on the blob in Azure.
+    # [+:content_disposition+]
+    #   Will be saved on the blob in Azure.
     def create_append_blob(key, options = {})
       uri = generate_uri("#{container}/#{key}")
 
@@ -101,6 +188,15 @@ module AzureBlob
       Http.new(uri, headers, metadata: options[:metadata], signer:).put(nil)
     end
 
+    # Append a block to an Append Blob
+    #
+    # Calls to {Append Block}[https://learn.microsoft.com/en-us/rest/api/storageservices/append-block]
+    #
+    # Options:
+    #
+    # [+:content_md5+]
+    #   Will ensure integrity of the upload. The checksum must be a base64 digest. Can be produced with +OpenSSL::Digest::MD5.base64digest+.
+    #   The checksum must be the checksum of the block not the blob.
     def append_blob_block(key, content, options = {})
       uri = generate_uri("#{container}/#{key}")
       uri.query = URI.encode_www_form(comp: "appendblock")
@@ -114,6 +210,16 @@ module AzureBlob
       Http.new(uri, headers, signer:).put(content)
     end
 
+    # Uploads a block to a blob.
+    #
+    # Calls to {Put Block}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block]
+    #
+    # Returns the id of the block. Required to commit the list of blocks to a blob.
+    #
+    # Options:
+    #
+    # [+:content_md5+]
+    #   Must be the checksum for the block not the blob. The checksum must be a base64 digest. Can be produced with +OpenSSL::Digest::MD5.base64digest+.
     def put_blob_block(key, index, content, options = {})
       block_id = generate_block_id(index)
       uri = generate_uri("#{container}/#{key}")
@@ -130,6 +236,17 @@ module AzureBlob
       block_id
     end
 
+    # Commits the list of blocks to a blob.
+    #
+    # Calls to {Put Block List}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-list]
+    #
+    # Takes a key (path) and an array of block ids
+    #
+    # Options:
+    #
+    # [+:content_md5+]
+    #   This is the checksum for the whole blob. The checksum is saved on the blob, but it is not validated!
+    #   Add a checksum for each block if you want Azure to validate integrity.
     def commit_blob_blocks(key, block_ids, options = {})
       block_list = BlockList.new(block_ids)
       content = block_list.to_s
@@ -139,7 +256,7 @@ module AzureBlob
       headers = {
         "Content-Length": content.size,
         "Content-Type": options[:content_type],
-        "Content-MD5": options[:content_md5],
+        "x-ms-blob-content-md5": options[:content_md5],
         "x-ms-blob-content-disposition": options[:content_disposition],
       }
 
@@ -171,7 +288,7 @@ module AzureBlob
         "x-ms-blob-type": "BlockBlob",
         "Content-Length": content.size,
         "Content-Type": options[:content_type],
-        "Content-MD5": options[:content_md5],
+        "x-ms-blob-content-md5": options[:content_md5],
         "x-ms-blob-content-disposition": options[:content_disposition],
       }
 

data/lib/azure_blob/http.rb

@@ -6,7 +6,7 @@ require "net/http"
 require "rexml"
 
 module AzureBlob
-  class Http
+  class Http # :nodoc:
     class Error < AzureBlob::Error; end
     class FileNotFoundError < Error; end
     class ForbidenError < Error; end

data/lib/azure_blob/metadata.rb

@@ -1,5 +1,5 @@
 module AzureBlob
-  class Metadata
+  class Metadata # :nodoc:
     def initialize(metadata = nil)
       @metadata = metadata || {}
       @headers = @metadata.map do |key, value|

data/lib/azure_blob/signer.rb

@@ -6,7 +6,7 @@ require_relative "canonicalized_headers"
 require_relative "canonicalized_resource"
 
 module AzureBlob
-  class Signer
+  class Signer # :nodoc:
     def initialize(account_name:, access_key:)
       @account_name = account_name
       @access_key = Base64.decode64(access_key)
@@ -83,9 +83,9 @@ module AzureBlob
       headers
     end
 
-    module SAS
+    module SAS # :nodoc:
       Version = "2024-05-04"
-      module Fields
+      module Fields # :nodoc:
         Permissions = :sp
         Version = :sv
         Expiry = :se
@@ -94,7 +94,7 @@ module AzureBlob
         Disposition = :rscd
         Type = :rsct
       end
-      module Resources
+      module Resources # :nodoc:
         Blob = :b
       end
     end

data/lib/azure_blob/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AzureBlob
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: azure-blob
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Joé Dupuis
@@ -57,13 +57,13 @@ files:
 - lib/azure_blob/metadata.rb
 - lib/azure_blob/signer.rb
 - lib/azure_blob/version.rb
-homepage: https://github.com/JoeDupuis/azure-blob
+homepage: https://github.com/testdouble/azure-blob
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/JoeDupuis/azure-blob
-  source_code_uri: https://github.com/JoeDupuis/azure-blob
-  changelog_uri: https://github.com/JoeDupuis/azure-blob/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/testdouble/azure-blob
+  source_code_uri: https://github.com/testdouble/azure-blob
+  changelog_uri: https://github.com/testdouble/azure-blob/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: