azure-blob 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90475e3257d1e948d48fa4a1853b82bfc7772621b09c36f20c484d80b741b4f9
-  data.tar.gz: 6b9d32989195d20d188b7aa94b300ef8e0920b87f69672fa06d9b830f598130d
+  metadata.gz: 1e0ce3229ce4281799f9d78b8f5b95343ac3fced270f902f07215630568bec93
+  data.tar.gz: ce76f13f260cdc59684ccfe0f655730c6fa03859bfa98264678d111b49999cfb
 SHA512:
-  metadata.gz: cfcabeac2710f4e13342ea1e74ff9f9c28310ba4b5b9056ff170f6dd63dae3adfed2644264a5678c889c693abf0f20c2b33080787f96acf3a090eea22ff226d2
-  data.tar.gz: a6af09d2f73af9e7cfe11e0402fa490a1f1d8dd40a7659dc3aa3047111dbb452aaca654b914d0987ded53923e447bceb3611a777656ee09a878e13478e1f4911
+  metadata.gz: d663e5fb344c55fc2a8efb9247f6207866c9f5676e9e64e028a1bde2c6762fa5bc5dd5ecf9864b41a44176eb7d7782524424a4dc29df1bf3bf716abb47e56d2b
+  data.tar.gz: 58663d45654f161db667d2bc5def5a36c7d5202038cf107322805b7f15b12cc03a7b455b058ee11385233a3c1dff70037ffe43118a848e2427e14e177d84920f

data/CHANGELOG.md

@@ -1,10 +1,25 @@
 ## [Unreleased]
 
-## [0.8.0] 2025-01-18
+## [0.9.0] 2026-10-11
+
+- Drop support for Ruby 3.1 and 3.2. Ruby 3.3 or newer is now required
+- Drop support for Rails 7.x. The Active Storage service now supports Rails 8.0 or newer
+- Fix `copy_blob` failing on append blobs and on blobs larger than 256 MiB
+- Fix `compose` failing when its source is a composed blob (#48)
+- Add `put_blob_block_from_url`
+- Add `AzureBlob::Blob#blob_type` and `AzureBlob::Blob#block_blob?`
+- Fix the content type being dropped when a blob is uploaded in multiple blocks
+- Add optional `delegation_key_expiration` to `AzureBlob::Client.new` and the ActiveStorage config to set the minimum lifetime of the Entra ID user delegation key in seconds (default 7 hours, maximum 7 days)
+- Fix Entra ID signed URLs that stopped working before their expiry because the user delegation key expired first
+- Raise `ArgumentError` when signing an Entra ID URL that expires more than 7 days from now
+- Include the HTTP status and Azure error code in `AzureBlob::Http::Error` messages (e.g. `500 InternalError`) and add `AzureBlob::Http::Error#code`
+- Fix error responses without an XML body raising `NoMethodError` instead of `AzureBlob::Http::Error`, which skipped the managed identity token retries
+
+## [0.8.0] 2026-01-18
 
 - Add cgi gem dependency for Ruby 4.0 compatibility
 
-## [0.7.0] 2025-01-05
+## [0.7.0] 2026-01-05
 
 - Add optional `timeout` parameter to all API methods
 - Add `AzureBlob::Http::TimeoutError` for handling Azure `OperationTimedOut` errors

data/README.md

@@ -4,6 +4,8 @@ Azure Blob client and Active Storage adapter to replace the now abandoned azure-
 
 An Active Storage is supplied, but the gem is Rails agnostic and can be used in any Ruby project.
 
+Requires Ruby 3.3 or newer. The Active Storage service supports Rails 8.0 or newer.
+
 ## Active Storage
 
 ### Migration
@@ -45,6 +47,35 @@ prod:
   principal_id: 71b34410-4c50-451d-b456-95ead1b18cce
 ```
 
+#### User delegation key expiration
+
+When authenticating through Entra ID, signed URLs are signed with a user delegation key
+that AzureBlob requests and renews as needed. `delegation_key_expiration` (in seconds)
+sets how long each key lasts: 7 hours by default, up to Azure's maximum of 7 days. Set it
+above the longest URL lifetime your app issues.
+
+```ruby
+client = AzureBlob::Client.new(
+  account_name: "account_name",
+  container: "container_name",
+  principal_id: "71b34410-4c50-451d-b456-95ead1b18cce",
+  delegation_key_expiration: 86400, # 1 day
+)
+```
+
+ActiveStorage config example:
+
+```
+prod:
+  service: AzureBlob
+  container: container_name
+  storage_account_name: account_name
+  principal_id: 71b34410-4c50-451d-b456-95ead1b18cce
+  delegation_key_expiration: 86400 # 1 day
+```
+
+The option is ignored when authenticating with a shared key.
+
 #### AKS with Workload Identity
 
 ActiveStorage config example:

data/lib/azure_blob/blob.rb

@@ -28,6 +28,15 @@ module AzureBlob
       response.content_length
     end
 
+    # Returns the blob type: +"BlockBlob"+, +"AppendBlob"+ or +"PageBlob"+.
+    def blob_type
+      response["x-ms-blob-type"]
+    end
+
+    def block_blob?
+      blob_type == "BlockBlob"
+    end
+
     def present?
       response.code == "200"
     end

data/lib/azure_blob/client.rb

@@ -24,6 +24,7 @@ module AzureBlob
       @access_key = access_key
       @principal_id = principal_id
       @use_managed_identities = options[:use_managed_identities]
+      @delegation_key_expiration = options[:delegation_key_expiration]
       signer unless options[:lazy]
     end
 
@@ -81,7 +82,13 @@ module AzureBlob
 
     # Copy a blob between containers or within the same container
     #
-    # Calls to {Copy Blob From URL}[https://learn.microsoft.com/en-us/rest/api/storageservices/copy-blob-from-url]
+    # Calls to {Copy Blob From URL}[https://learn.microsoft.com/en-us/rest/api/storageservices/copy-blob-from-url],
+    # which copies a block blob of at most 256 MiB in a single request. When Azure refuses the source
+    # (an append blob, or a bigger block blob) the blob is copied block by block with
+    # {Put Block From URL}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-from-url] instead.
+    #
+    # Either way the copy is a block blob that keeps the content type, content disposition and checksum
+    # of the source, and its metadata unless +:metadata+ is given.
     #
     # Parameters:
     # - key: destination blob path
@@ -89,9 +96,11 @@ module AzureBlob
     # - options: additional options
     #   - source_client: AzureBlob::Client instance for the source container (optional)
     #     If not provided, copies from within the same container
+    #   - metadata: metadata of the copy (optional). Defaults to the metadata of the source
+    #   - block_size: block size of a block by block copy. Defaults to +AzureBlob::DEFAULT_BLOCK_SIZE+
     #
     def copy_blob(key, source_key, options = {})
-      source_client = options.delete(:source_client) || self
+      source_client = options[:source_client] || self
       uri = generate_uri("#{container}/#{key}")
       uri.query = URI.encode_www_form(timeout: options[:timeout]) if options[:timeout]
 
@@ -103,6 +112,9 @@ module AzureBlob
       }.merge(additional_headers(options))
 
       Http.new(uri, headers, signer:, **options.slice(:metadata, :tags)).put
+    rescue Http::Error => error
+      raise unless error.status == 409
+      copy_blob_blocks(key, source_key, source_client, options)
     end
 
     # Delete a blob
@@ -361,6 +373,35 @@ module AzureBlob
       block_id
     end
 
+    # Copies a block from a URL into a blob.
+    #
+    # Calls to {Put Block From URL}[https://learn.microsoft.com/en-us/rest/api/storageservices/put-block-from-url]
+    #
+    # Returns the id of the block. Required to commit the list of blocks to a blob.
+    #
+    # Options:
+    #
+    # [+:source_range+]
+    #   Range of bytes to copy from the source, for example +0..(block_size - 1)+. Defaults to the whole source.
+    def put_blob_block_from_url(key, index, source_uri, options = {})
+      block_id = generate_block_id(index)
+      uri = generate_uri("#{container}/#{key}")
+      query = { comp: "block", blockid: block_id }
+      query[:timeout] = options[:timeout] if options[:timeout]
+      uri.query = URI.encode_www_form(**query)
+
+      source_range = options[:source_range]
+      headers = {
+        "Content-Length": 0,
+        "x-ms-copy-source": source_uri.to_s,
+        "x-ms-source-range": source_range && "bytes=#{source_range.min}-#{source_range.max}",
+      }.merge(additional_headers(options))
+
+      Http.new(uri, headers, signer:).put
+
+      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]
@@ -382,7 +423,7 @@ module AzureBlob
 
       headers = {
         "Content-Length": content_size(content),
-        "Content-Type": options[:content_type],
+        "x-ms-blob-content-type": options[:content_type],
         "x-ms-blob-content-md5": options[:content_md5],
         "x-ms-blob-content-disposition": options[:content_disposition],
       }.merge(additional_headers(options))
@@ -428,6 +469,34 @@ module AzureBlob
       Http.new(uri, headers, signer:, **options.slice(:metadata, :tags)).put(content.read)
     end
 
+    # One Put Block From URL request per block, then one Put Block List to commit them.
+    # Works with any source blob type and size, and carries the properties and metadata over itself.
+    def copy_blob_blocks(key, source_key, source_client, options)
+      source = source_client.get_blob_properties(source_key, options.slice(:timeout))
+      block_size = options[:block_size] || DEFAULT_BLOCK_SIZE
+      # Every block reads the source through this URI, so it has to outlive the whole copy.
+      source_uri = source_client.signed_uri(source_key, permissions: "r", expiry: Time.at(Time.now.to_i + 3600).utc.iso8601)
+
+      block_ids = (source.size.to_f / block_size).ceil.times.map do |index|
+        first = index * block_size
+        last = [ first + block_size, source.size ].min - 1
+        put_blob_block_from_url(key, index, source_uri, source_range: first..last, **options.slice(:timeout, :headers))
+      end
+
+      metadata = options[:metadata]
+      metadata = source.metadata if metadata.nil? || metadata.empty?
+
+      commit_blob_blocks(
+        key,
+        block_ids,
+        content_type: source.content_type,
+        content_md5: source.checksum,
+        content_disposition: source.content_disposition,
+        metadata: metadata,
+        **options.slice(:tags, :timeout, :headers),
+      )
+    end
+
     def content_size(content)
       if content.respond_to?(:bytesize)
         content.bytesize
@@ -453,11 +522,11 @@ module AzureBlob
           end
 
           using_managed_identities ?
-            AzureBlob::EntraIdSigner.new(account_name:, host:, principal_id:) :
+            AzureBlob::EntraIdSigner.new(account_name:, host:, principal_id:, delegation_key_expiration:) :
             AzureBlob::SharedKeySigner.new(account_name:, access_key:, host:)
         end
     end
 
-    attr_reader :account_name, :container, :http, :cloud_regions, :access_key, :principal_id, :use_managed_identities
+    attr_reader :account_name, :container, :http, :cloud_regions, :access_key, :principal_id, :use_managed_identities, :delegation_key_expiration
   end
 end

data/lib/azure_blob/entra_id_signer.rb

@@ -14,7 +14,8 @@ module AzureBlob
     attr_reader :account_name
     attr_reader :host
 
-    def initialize(account_name:, host:, principal_id: nil)
+    def initialize(account_name:, host:, principal_id: nil, delegation_key_expiration: nil)
+      @delegation_key_expiration = parse_delegation_key_expiration(delegation_key_expiration)
       @token = AzureBlob::IdentityToken.new(principal_id:)
       @account_name = account_name
       @host = host
@@ -25,7 +26,7 @@ module AzureBlob
     end
 
     def sas_token(uri, options = {})
-      delegation_key.refresh
+      delegation_key.refresh(valid_until: options[:expiry])
       to_sign = [
         options[:permissions],
         options[:start],
@@ -82,8 +83,25 @@ module AzureBlob
 
     private
 
+    attr_reader :delegation_key_expiration
+
+    def parse_delegation_key_expiration(value)
+      return if value.nil?
+
+      seconds = Integer(value, exception: false)
+      unless seconds&.positive?
+        raise ArgumentError, "delegation_key_expiration must be a positive number of seconds, got #{value.inspect}"
+      end
+
+      if seconds > UserDelegationKey::MAX_EXPIRATION
+        raise ArgumentError, "delegation_key_expiration cannot be greater than #{UserDelegationKey::MAX_EXPIRATION} seconds (7 days), got #{value.inspect}"
+      end
+
+      seconds
+    end
+
     def delegation_key
-      @delegation_key ||= UserDelegationKey.new(account_name:, signer: self)
+      @delegation_key ||= UserDelegationKey.new(account_name:, signer: self, expiration: delegation_key_expiration || UserDelegationKey::EXPIRATION)
     end
 
     def sign(body, key:)

data/lib/azure_blob/http.rb

@@ -8,10 +8,12 @@ require "rexml"
 module AzureBlob
   class Http # :nodoc:
     class Error < AzureBlob::Error
-      attr_reader :body, :status
-      def initialize(body: nil, status: nil)
+      attr_reader :body, :status, :code
+      def initialize(body: nil, status: nil, code: nil)
         @body = body
         @status = status
+        @code = code
+        super(status && [ status, code ].compact.join(" "))
       end
 
       def inspect
@@ -118,7 +120,7 @@ module AzureBlob
 
     def raise_error
       return unless raise_on_error
-      raise error_from_response.new(body: @response.body, status: @response.code&.to_i)
+      raise error_from_response.new(body: @response.body, status: @response.code&.to_i, code: azure_error_code)
     end
 
     def status
@@ -126,7 +128,9 @@ module AzureBlob
     end
 
     def azure_error_code
-      Document.new(response.body).get_elements("//Error/Code").first.get_text.to_s if response.body
+      response["x-ms-error-code"] || Document.new(response.body.to_s).get_elements("//Error/Code").first&.text
+    rescue ParseException
+      nil
     end
 
     def error_from_response

data/lib/azure_blob/user_delegation_key.rb

@@ -1,15 +1,20 @@
+require "time"
+
 require_relative "http"
 
 module AzureBlob
   class UserDelegationKey # :nodoc:
     EXPIRATION = 25200 # 7 hours
+    MAX_EXPIRATION = 604800 # 7 days
     EXPIRATION_BUFFER = 3600 # 1 hours
-    def initialize(account_name:, signer:)
+
+    def initialize(account_name:, signer:, expiration: EXPIRATION)
       @uri = URI.parse(
         "#{signer.host}/?restype=service&comp=userdelegationkey"
       )
 
       @signer = signer
+      @expiration_duration = expiration
 
       refresh
     end
@@ -19,14 +24,22 @@ module AzureBlob
       user_delegation_key
     end
 
-    def refresh
-      return unless expired?
+    # Requests a new key when this one is about to expire, or when it expires
+    # before +valid_until+ (the expiry of the SAS about to be signed with it).
+    def refresh(valid_until: nil)
+      valid_until = Time.parse(valid_until) if valid_until.is_a?(String)
       now = Time.now.utc
 
+      if valid_until && valid_until > now + MAX_EXPIRATION
+        raise ArgumentError, "signed URL expiry #{valid_until.getutc.iso8601} is more than #{MAX_EXPIRATION} seconds (7 days) away, " \
+          "Azure cannot sign a user delegation SAS that lasts longer than 7 days"
+      end
+
+      return unless expired? || (valid_until && valid_until > expiration)
 
       start = now.iso8601
-      @expiration = (now + EXPIRATION)
-      expiry = @expiration.iso8601
+      new_expiration = [ now + expiration_duration, valid_until ].compact.max
+      expiry = new_expiration.getutc.iso8601
 
       content = <<-XML.gsub!(/[[:space:]]+/, " ").strip!
         <?xml version="1.0" encoding="utf-8"?>
@@ -47,6 +60,7 @@ module AzureBlob
       @signed_service = doc.get_elements("/UserDelegationKey/SignedService").first.get_text.to_s
       @signed_version = doc.get_elements("/UserDelegationKey/SignedVersion").first.get_text.to_s
       @user_delegation_key = Base64.decode64(doc.get_elements("/UserDelegationKey/Value").first.get_text.to_s)
+      @expiration = new_expiration
     end
 
     attr_reader :signed_oid,
@@ -60,9 +74,13 @@ module AzureBlob
     private
 
     def expired?
-      expiration.nil? || Time.now >= (expiration - EXPIRATION_BUFFER)
+      expiration.nil? || Time.now >= (expiration - refresh_buffer)
+    end
+
+    def refresh_buffer
+      [ EXPIRATION_BUFFER, expiration_duration / 2 ].min
     end
 
-    attr_reader :uri, :user_delegation_key, :signer, :expiration
+    attr_reader :uri, :user_delegation_key, :signer, :expiration, :expiration_duration
   end
 end

data/lib/azure_blob/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: azure-blob
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Joé Dupuis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-01 00:00:00.000000000 Z
+date: 2026-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -86,14 +86,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Azure Blob client and Active Storage adapter