azure-blob 0.5.1 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a83c96b748a5659438b382a79a1af068c1552f4ee895dd16b863b00758d8d1f
-  data.tar.gz: f6def3a97bde3b96ef53618502454b3c3bd0103e07332ed19f817d3298971860
+  metadata.gz: c6c4e076840dd6671c28c99b5fca03057782e81686c0c06890b42cedd3b83788
+  data.tar.gz: '00668582cecce526ad816a5c537469af7e646d6f64d7392655d1c7e60396393c'
 SHA512:
-  metadata.gz: 20f51dbd1ea9661fec78d1371f52459aaf00a4a42e7274f375bd81c7cfc89bac9dfba1546af7cf71f7fea5fd8479fa7ceab9605ea1a8d0ceef7099e0212d4738
-  data.tar.gz: 74939a0d48677079ac46585276369a4d090d8bcbdd4e0ab84d37a8a48d2e54977dec5541b823f0a08c7642787ce13041a54311963010a5449424f13a181e72de
+  metadata.gz: fdd32b7f8547ac428bf0eb19d884860e94d1ab9471df0022356119c5ec28aca8589d1b1925d0085b2361c4c16d5898123a1fc18f57b5b2cb9ae7e53dbc4b4379
+  data.tar.gz: 44a4592046d5d33432762cfd4d3636500f9c13db00cf5c705fbc2f472b7c322bd37bc05d9765e03079e0966dcb44d0e5cc844db303906aaa18435c8db7ee422f

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+
+## [0.5.3] 2024-10-31
+
+- Add support for setting tags when uploading a blob
+- Add get_blob_tags
+
+## [0.5.2] 2024-09-12
+
+- Add get_container_properties
+- Add create_container
+- Add delete_container
+- Support for Azure China, US Gov and Germany
+
 ## [0.5.1] 2024-09-09
 
 - Remove dev files from the release

data/README.md

@@ -1,6 +1,8 @@
 # AzureBlob
 
-This gem was built to replace azure-storage-blob (deprecated) in Active Storage, but was written to be Rails agnostic.
+Azure Blob client and Active Storage adapter to replace the now abandoned azure-storage-blob
+
+An Active Storage is supplied, but the gem is Rails agnostic and can be used in any Ruby project.
 
 ## Active Storage
 
@@ -12,6 +14,16 @@ To migrate from azure-storage-blob to azure-blob:
 3. Change the `AzureStorage` service to `AzureBlob`  in your Active Storage config (`config/storage.yml`)
 4. Restart or deploy the app.
 
+Example config:
+
+```
+microsoft:
+  service: AzureBlob
+  storage_account_name: account_name
+  storage_access_key: SECRET_KEY
+  container: container_name
+```
+
 ### Managed Identity (Entra ID)
 
 AzureBlob supports managed identities on :
@@ -22,9 +34,7 @@ AzureBlob supports managed identities on :
 
 AKS support will likely require more work. Contributions are welcome.
 
-To authenticate through managed identities instead of a shared key, omit `storage_access_key` from your `storage.yml` file.
-
-It is recommended to add the identity's `principal_id` to the config.
+To authenticate through managed identities instead of a shared key, omit `storage_access_key` from your `storage.yml` file and pass in the identity `principal_id`.
 
 ActiveStorage config example:
 
@@ -79,11 +89,12 @@ A dev environment is supplied through Nix with [devenv](https://devenv.sh/).
 
 To test with Entra ID, the `AZURE_ACCESS_KEY` environment variable must be unset and the code must be ran or proxied through a VPS with the proper roles.
 
-For cost saving, the terraform variable `create_vm` is false by default.
-To create the VPS, Create a var file `var.tfvars` containing:
+For cost saving, the terraform variable `create_vm` and `create_app_service` are false by default.
+To create the VPS and App service, Create a var file `var.tfvars` containing:
 
 ```
 create_vm = true
+create_app_service = true
 ```
 and re-apply terraform: `terraform apply -var-file=var.tfvars`.
 

data/lib/azure_blob/blob.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module AzureBlob
-  # AzureBlob::Blob holds the metada for a given Blob.
+  # AzureBlob::Blob holds the metadata for a given Blob.
   class Blob
     # You should not instanciate this object directly,
     # but obtain one when calling relevant methods of AzureBlob::Client.
@@ -32,7 +32,7 @@ module AzureBlob
       response.code == "200"
     end
 
-    # Returns the custom Azure metada tagged on the blob.
+    # Returns the custom Azure metadata tagged on the blob.
     def metadata
       @metadata || response
         .to_hash

data/lib/azure_blob/client.rb

@@ -3,6 +3,8 @@
 require_relative "block_list"
 require_relative "blob_list"
 require_relative "blob"
+require_relative "container"
+require_relative "tags"
 require_relative "http"
 require_relative "shared_key_signer"
 require_relative "entra_id_signer"
@@ -13,13 +15,22 @@ 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:, **options)
+    def initialize(account_name:, access_key: nil, principal_id: nil, container:, **options)
       @account_name = account_name
       @container = container
+      @cloud_regions = options[:cloud_regions]&.to_sym || :global
 
-      @signer = !access_key.nil? && !access_key.empty?  ?
-        AzureBlob::SharedKeySigner.new(account_name:, access_key:) :
-        AzureBlob::EntraIdSigner.new(account_name:, **options.slice(:principal_id))
+      no_access_key = access_key.nil? || access_key&.empty?
+      using_managed_identities = no_access_key && !principal_id.nil? || options[:use_managed_identities]
+
+      if !using_managed_identities && no_access_key
+        raise AzureBlob::Error.new(
+          "`access_key` cannot be empty. To use managed identities instead, pass a `principal_id` or set `use_managed_identities` to true."
+        )
+      end
+      @signer = using_managed_identities ?
+        AzureBlob::EntraIdSigner.new(account_name:, host:, principal_id:) :
+        AzureBlob::SharedKeySigner.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.
@@ -138,7 +149,7 @@ module AzureBlob
     #
     # 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.
+    # This can be used to see if the blob exist or obtain metadata such as content type, disposition, checksum or Azure custom metadata.
     def get_blob_properties(key, options = {})
       uri = generate_uri("#{container}/#{key}")
 
@@ -147,6 +158,51 @@ module AzureBlob
       Blob.new(response)
     end
 
+    # Returns the tags associated with a blob
+    #
+    # Calls to the {Get Blob Tags}[https://learn.microsoft.com/en-us/rest/api/storageservices/get-blob-tags] endpoint.
+    #
+    # Takes a key (path) of the blob.
+    #
+    # Returns a hash of the blob's tags.
+    def get_blob_tags(key)
+      uri = generate_uri("#{container}/#{key}?comp=tags")
+      response = Http.new(uri, signer:).get
+
+      Tags.from_response(response).to_h
+    end
+
+    # Returns a Container object.
+    #
+    # Calls to {Get Container Properties}[https://learn.microsoft.com/en-us/rest/api/storageservices/get-container-properties]
+    #
+    # This can be used to see if the container exist or obtain metadata.
+    def get_container_properties(options = {})
+      uri = generate_uri(container)
+      uri.query = URI.encode_www_form(restype: "container")
+      response = Http.new(uri, signer:, raise_on_error: false).head
+
+      Container.new(response)
+    end
+
+    # Create the container
+    #
+    # Calls to {Create Container}[https://learn.microsoft.com/en-us/rest/api/storageservices/create-container]
+    def create_container(options = {})
+      uri = generate_uri(container)
+      uri.query = URI.encode_www_form(restype: "container")
+      response = Http.new(uri, signer:).put
+    end
+
+    # Delete the container
+    #
+    # Calls to {Delete Container}[https://learn.microsoft.com/en-us/rest/api/storageservices/delete-container]
+    def delete_container(options = {})
+      uri = generate_uri(container)
+      uri.query = URI.encode_www_form(restype: "container")
+      response = Http.new(uri, signer:).delete
+    end
+
     # Return a URI object to a resource in the container. Takes a path.
     #
     # Example: +generate_uri("#{container}/#{key}")+
@@ -189,7 +245,7 @@ module AzureBlob
         "x-ms-blob-content-disposition": options[:content_disposition],
       }
 
-      Http.new(uri, headers, metadata: options[:metadata], signer:).put(nil)
+      Http.new(uri, headers, signer:, **options.slice(:metadata, :tags)).put(nil)
     end
 
     # Append a block to an Append Blob
@@ -264,7 +320,7 @@ module AzureBlob
         "x-ms-blob-content-disposition": options[:content_disposition],
       }
 
-      Http.new(uri, headers, metadata: options[:metadata], signer:).put(content)
+      Http.new(uri, headers, signer:, **options.slice(:metadata, :tags)).put(content)
     end
 
     private
@@ -296,13 +352,13 @@ module AzureBlob
         "x-ms-blob-content-disposition": options[:content_disposition],
       }
 
-      Http.new(uri, headers, metadata: options[:metadata], signer:).put(content.read)
+      Http.new(uri, headers, signer:, **options.slice(:metadata, :tags)).put(content.read)
     end
 
-    attr_reader :account_name, :signer, :container, :http
-
     def host
-      "https://#{account_name}.blob.core.windows.net"
+      @host ||= "https://#{account_name}.blob.#{CLOUD_REGIONS_SUFFIX[cloud_regions]}"
     end
+
+    attr_reader :account_name, :signer, :container, :http, :cloud_regions
   end
 end

data/lib/azure_blob/const.rb

@@ -2,7 +2,13 @@
 
 module AzureBlob
   API_VERSION = "2024-05-04"
-  MAX_UPLOAD_SIZE = 256 * 1024 * 1024
-  DEFAULT_BLOCK_SIZE = 128 * 1024 * 1024
+  MAX_UPLOAD_SIZE = 256 * 1024 * 1024 # 256 Megabytes
+  DEFAULT_BLOCK_SIZE = 128 * 1024 * 1024 # 128 Megabytes
   BLOB_SERVICE = "b"
+  CLOUD_REGIONS_SUFFIX = {
+    global: "core.windows.net",
+    cn: "core.chinacloudapi.cn",
+    de: "core.cloudapi.de",
+    usgovt: "core.usgovcloudapi.net",
+  }
 end

data/lib/azure_blob/container.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module AzureBlob
+  # AzureBlob::Container holds the metadata for a given Container.
+  class Container
+    # 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 container uri.
+    def initialize(response)
+      @response = response
+    end
+
+
+    def present?
+      response.code == "200"
+    end
+
+    # Returns the custom Azure metadata tagged on the container.
+    def metadata
+      @metadata || response
+        .to_hash
+        .select { |key, _| key.start_with?("x-ms-meta") }
+        .transform_values(&:first)
+        .transform_keys { |key| key.delete_prefix("x-ms-meta-").to_sym }
+    end
+
+    private
+
+    attr_reader :response
+  end
+end

data/lib/azure_blob/entra_id_signer.rb

@@ -12,10 +12,12 @@ module AzureBlob
   class EntraIdSigner # :nodoc:
     attr_reader :token
     attr_reader :account_name
+    attr_reader :host
 
-    def initialize(account_name:, principal_id: nil)
+    def initialize(account_name:, host:, principal_id: nil)
       @token = AzureBlob::IdentityToken.new(principal_id:)
       @account_name = account_name
+      @host = host
     end
 
     def authorization_header(uri:, verb:, headers: {})

data/lib/azure_blob/http.rb

@@ -12,7 +12,10 @@ module AzureBlob
       def initialize(body: nil, status: nil)
         @body = body
         @status = status
-        super(body)
+      end
+
+      def inspect
+        @body
       end
     end
     class FileNotFoundError < Error; end
@@ -21,11 +24,16 @@ module AzureBlob
 
     include REXML
 
-    def initialize(uri, headers = {}, signer: nil, metadata: {}, debug: false)
+    def initialize(uri, headers = {}, signer: nil, metadata: {}, tags: {}, debug: false, raise_on_error: true)
+      @raise_on_error = raise_on_error
       @date = Time.now.httpdate
       @uri = uri
       @signer = signer
-      @headers = headers.merge(Metadata.new(metadata).headers)
+      @headers = headers.merge(
+        Metadata.new(metadata).headers,
+        Tags.new(tags).headers,
+      )
+
       sanitize_headers
 
       @http = Net::HTTP.new(uri.hostname, uri.port)
@@ -42,7 +50,7 @@ module AzureBlob
       response.body
     end
 
-    def put(content)
+    def put(content = "")
       sign_request("PUT") if signer
       @response = http.start do |http|
         http.put(uri, content, headers)
@@ -51,7 +59,7 @@ module AzureBlob
       true
     end
 
-    def post(content)
+    def post(content = "")
       sign_request("POST") if signer
       @response = http.start do |http|
         http.post(uri, content, headers)
@@ -107,6 +115,7 @@ module AzureBlob
     end
 
     def raise_error
+      return unless raise_on_error
       raise error_from_response.new(body: @response.body, status: @response.code&.to_i)
     end
 
@@ -115,13 +124,13 @@ module AzureBlob
     end
 
     def azure_error_code
-      Document.new(response.body).get_elements("//Error/Code").first.get_text.to_s
+      Document.new(response.body).get_elements("//Error/Code").first.get_text.to_s if response.body
     end
 
     def error_from_response
       ERROR_MAPPINGS[status] || ERROR_CODE_MAPPINGS[azure_error_code] || Error
     end
 
-    attr_accessor :host, :http, :signer, :response, :headers, :uri, :date
+    attr_accessor :host, :http, :signer, :response, :headers, :uri, :date, :raise_on_error
   end
 end

data/lib/azure_blob/tags.rb

@@ -0,0 +1,35 @@
+require "rexml/document"
+
+module AzureBlob
+  class Tags # :nodoc:
+    def self.from_response(response)
+      document = REXML::Document.new(response)
+      tags = {}
+      document.elements.each("Tags/TagSet/Tag") do |tag|
+        key = tag.elements["Key"].text
+        value = tag.elements["Value"].text
+        tags[key] = value
+      end
+      new(tags)
+    end
+
+    def initialize(tags = nil)
+      @tags = tags || {}
+    end
+
+    def headers
+      return {} if @tags.empty?
+
+      {
+        "x-ms-tags":
+        @tags.map do |key, value|
+          %(#{key}=#{value})
+        end.join("&"),
+      }
+    end
+
+    def to_h
+      @tags
+    end
+  end
+end

data/lib/azure_blob/user_delegation_key.rb

@@ -6,7 +6,7 @@ module AzureBlob
     EXPIRATION_BUFFER = 3600 # 1 hours
     def initialize(account_name:, signer:)
       @uri = URI.parse(
-        "https://#{account_name}.blob.core.windows.net/?restype=service&comp=userdelegationkey"
+        "#{signer.host}/?restype=service&comp=userdelegationkey"
       )
 
       @signer = signer

data/lib/azure_blob/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: azure-blob
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.5.3
 platform: ruby
 authors:
 - Joé Dupuis
@@ -44,12 +44,14 @@ files:
 - lib/azure_blob/canonicalized_resource.rb
 - lib/azure_blob/client.rb
 - lib/azure_blob/const.rb
+- lib/azure_blob/container.rb
 - lib/azure_blob/entra_id_signer.rb
 - lib/azure_blob/errors.rb
 - lib/azure_blob/http.rb
 - lib/azure_blob/identity_token.rb
 - lib/azure_blob/metadata.rb
 - lib/azure_blob/shared_key_signer.rb
+- lib/azure_blob/tags.rb
 - lib/azure_blob/user_delegation_key.rb
 - lib/azure_blob/version.rb
 homepage: https://github.com/testdouble/azure-blob
@@ -78,5 +80,5 @@ requirements: []
 rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
-summary: Azure blob client
+summary: Azure Blob client and Active Storage adapter
 test_files: []