azure-blob 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a83c96b748a5659438b382a79a1af068c1552f4ee895dd16b863b00758d8d1f
-  data.tar.gz: f6def3a97bde3b96ef53618502454b3c3bd0103e07332ed19f817d3298971860
+  metadata.gz: 72003b15ad78aeab66adc7aca2e6786ae2921ad1469cf94145e049705f52c33c
+  data.tar.gz: a77f87dff2f59a22476f0c5e490540a73166cf88dbf3616de8a15a87132aaa5f
 SHA512:
-  metadata.gz: 20f51dbd1ea9661fec78d1371f52459aaf00a4a42e7274f375bd81c7cfc89bac9dfba1546af7cf71f7fea5fd8479fa7ceab9605ea1a8d0ceef7099e0212d4738
-  data.tar.gz: 74939a0d48677079ac46585276369a4d090d8bcbdd4e0ab84d37a8a48d2e54977dec5541b823f0a08c7642787ce13041a54311963010a5449424f13a181e72de
+  metadata.gz: 910c2d759b83d7b56168fd42a239ffb5da1b4aced25b8f39bc84a1beb63e736690a72586f64313d5fcebf7250808b27d15e23450e850635e24558891eed375ff
+  data.tar.gz: 2d4ecfb6e3e5318d8c6cb07569da7b83bccd49ee3a7d153d43c41e655474dcd43d7a73d28d68fb2baa4124326a1b41562275314348730250610420640c3dc3bd

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+
+## [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,7 @@
 require_relative "block_list"
 require_relative "blob_list"
 require_relative "blob"
+require_relative "container"
 require_relative "http"
 require_relative "shared_key_signer"
 require_relative "entra_id_signer"
@@ -13,13 +14,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 +148,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 +157,37 @@ module AzureBlob
       Blob.new(response)
     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}")+
@@ -299,10 +340,10 @@ module AzureBlob
       Http.new(uri, headers, metadata: options[:metadata], signer:).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,7 +24,8 @@ module AzureBlob
 
     include REXML
 
-    def initialize(uri, headers = {}, signer: nil, metadata: {}, debug: false)
+    def initialize(uri, headers = {}, signer: nil, metadata: {}, debug: false, raise_on_error: true)
+      @raise_on_error = raise_on_error
       @date = Time.now.httpdate
       @uri = uri
       @signer = signer
@@ -42,7 +46,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 +55,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 +111,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 +120,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/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.2"
 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.2
 platform: ruby
 authors:
 - Joé Dupuis
@@ -44,6 +44,7 @@ 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
@@ -78,5 +79,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: []