azure-storage-file 1.0.0

data/file/lib/azure/storage/file/file_service.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+#-------------------------------------------------------------------------
+# # Copyright (c) Microsoft and contributors. All rights reserved.
+#
+# The MIT License(MIT)
+
+# 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.
+#--------------------------------------------------------------------------
+require "azure/storage/file/file"
+
+module Azure::Storage
+  include Azure::Storage::Common::Service
+  StorageService = Azure::Storage::Common::Service::StorageService
+
+  module File
+    class FileService < StorageService
+      include Azure::Storage::Common::Core::Utility
+      include Azure::Storage::File::Share
+      include Azure::Storage::File::Directory
+      include Azure::Storage::File
+
+      class << self
+        # Public: Creates an instance of [Azure::Storage::File::FileService]
+        #
+        # ==== Attributes
+        #
+        # * +options+    - Hash. Optional parameters.
+        #
+        # ==== Options
+        #
+        # Accepted key/value pairs in options parameter are:
+        #
+        # * +:use_development_storage+        - TrueClass|FalseClass. Whether to use storage emulator.
+        # * +:development_storage_proxy_uri+  - String. Used with +:use_development_storage+ if emulator is hosted other than localhost.
+        # * +:storage_account_name+           - String. The name of the storage account.
+        # * +:storage_access_key+             - Base64 String. The access key of the storage account.
+        # * +:storage_sas_token+              - String. The signed access signature for the storage account or one of its service.
+        # * +:storage_file_host+              - String. Specified File service endpoint or hostname
+        # * +:storage_dns_suffix+             - String. The suffix of a regional Storage Service, to
+        # * +:default_endpoints_protocol+     - String. http or https
+        # * +:use_path_style_uri+             - String. Whether use path style URI for specified endpoints
+        # * +:ca_file+                        - String. File path of the CA file if having issue with SSL
+        # * +:user_agent_prefix+              - String. The user agent prefix that can identify the application calls the library
+        #
+        # The valid set of options include:
+        # * Storage Emulator: +:use_development_storage+ required, +:development_storage_proxy_uri+ optionally
+        # * Storage account name and key: +:storage_account_name+ and +:storage_access_key+ required, set +:storage_dns_suffix+ necessarily
+        # * Storage account name and SAS token: +:storage_account_name+ and +:storage_sas_token+ required, set +:storage_dns_suffix+ necessarily
+        # * Specified hosts and SAS token: At least one of the service host and SAS token. It's up to user to ensure the SAS token is suitable for the serivce
+        # * Anonymous File: only +:storage_file_host+, if it is to only access files within a container
+        #
+        # Additional notes:
+        # * Specified hosts can be set when use account name with access key or sas token
+        # * +:default_endpoints_protocol+ can be set if the scheme is not specified in hosts
+        # * Storage emulator always use path style URI
+        # * +:ca_file+ is independent.
+        #
+        # When empty options are given, it will try to read settings from Environment Variables. Refer to [Azure::Storage::Common::ClientOptions.env_vars_mapping] for the mapping relationship
+        #
+        # @return [Azure::Storage::File::FileService]
+        def create(options = {}, &block)
+          service_options = { client: Azure::Storage::Common::Client::create(options, &block), api_version: Azure::Storage::File::Default::STG_VERSION }
+          service_options[:user_agent_prefix] = options[:user_agent_prefix] if options[:user_agent_prefix]
+          Azure::Storage::File::FileService.new(service_options, &block)
+        end
+
+        # Public: Creates an instance of [Azure::Storage::File::FileService] with Storage Emulator
+        #
+        # ==== Attributes
+        #
+        # * +proxy_uri+    - String. Used with +:use_development_storage+ if emulator is hosted other than localhost.
+        #
+        # @return [Azure::Storage::File::FileService]
+        def create_development(proxy_uri = nil, &block)
+          service_options = { client: Azure::Storage::Common::Client::create_development(proxy_uri, &block), api_version: Azure::Storage::File::Default::STG_VERSION }
+          Azure::Storage::File::FileService.new(service_options, &block)
+        end
+
+        # Public: Creates an instance of [Azure::Storage::File::FileService] from Environment Variables
+        #
+        # @return [Azure::Storage::File::FileService]
+        def create_from_env(&block)
+          service_options = { client: Azure::Storage::Common::Client::create_from_env(&block), api_version: Azure::Storage::File::Default::STG_VERSION }
+          Azure::Storage::File::FileService.new(service_options, &block)
+        end
+
+        # Public: Creates an instance of [Azure::Storage::File::FileService] from Environment Variables
+        #
+        # ==== Attributes
+        #
+        # * +connection_string+    - String. Please refer to https://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/.
+        #
+        # @return [Azure::Storage::File::FileService]
+        def create_from_connection_string(connection_string, &block)
+          service_options = { client: Azure::Storage::Common::Client::create_from_connection_string(connection_string, &block), api_version: Azure::Storage::File::Default::STG_VERSION }
+          Azure::Storage::File::FileService.new(service_options, &block)
+        end
+      end
+
+      # Public: Initializes an instance of [Azure::Storage::File::FileService]
+      #
+      # ==== Attributes
+      #
+      # * +options+    - Hash. Optional parameters.
+      #
+      # ==== Options
+      #
+      # Accepted key/value pairs in options parameter are:
+      #
+      # * +:use_development_storage+        - TrueClass|FalseClass. Whether to use storage emulator.
+      # * +:development_storage_proxy_uri+  - String. Used with +:use_development_storage+ if emulator is hosted other than localhost.
+      # * +:storage_connection_string+      - String. The storage connection string.
+      # * +:storage_account_name+           - String. The name of the storage account.
+      # * +:storage_access_key+             - Base64 String. The access key of the storage account.
+      # * +:storage_sas_token+              - String. The signed access signature for the storage account or one of its service.
+      # * +:storage_file_host+              - String. Specified File serivce endpoint or hostname
+      # * +:storage_table_host+             - String. Specified Table serivce endpoint or hostname
+      # * +:storage_queue_host+             - String. Specified Queue serivce endpoint or hostname
+      # * +:storage_dns_suffix+             - String. The suffix of a regional Storage Serivce, to
+      # * +:default_endpoints_protocol+     - String. http or https
+      # * +:use_path_style_uri+             - String. Whether use path style URI for specified endpoints
+      # * +:ca_file+                        - String. File path of the CA file if having issue with SSL
+      # * +:user_agent_prefix+              - String. The user agent prefix that can identify the application calls the library
+      # * +:client+                         - Azure::Storage::Common::Client. The common client used to initalize the service.
+      #
+      # The valid set of options include:
+      # * Storage Emulator: +:use_development_storage+ required, +:development_storage_proxy_uri+ optionally
+      # * Storage account name and key: +:storage_account_name+ and +:storage_access_key+ required, set +:storage_dns_suffix+ necessarily
+      # * Storage account name and SAS token: +:storage_account_name+ and +:storage_sas_token+ required, set +:storage_dns_suffix+ necessarily
+      # * Specified hosts and SAS token: At least one of the service host and SAS token. It's up to user to ensure the SAS token is suitable for the serivce
+      # * Azure::Storage::Common::Client: The common client used to initalize the service. This client can be initalized and used repeatedly.
+      # * Anonymous File: only +:storage_file_host+, if it is to only access files within a container
+      #
+      # Additional notes:
+      # * Specified hosts can be set when use account name with access key or sas token
+      # * +:default_endpoints_protocol+ can be set if the scheme is not specified in hosts
+      # * Storage emulator always use path style URI
+      # * +:ca_file+ is independent.
+      #
+      # When empty options are given, it will try to read settings from Environment Variables. Refer to [Azure::Storage::Common::ClientOptions.env_vars_mapping] for the mapping relationship
+      def initialize(options = {}, &block)
+        service_options = options.clone
+        client_config = service_options[:client] ||= Azure::Storage::Common::Client::create(service_options, &block)
+        @user_agent_prefix = service_options[:user_agent_prefix] if service_options[:user_agent_prefix]
+        @api_version = service_options[:api_version] || Azure::Storage::File::Default::STG_VERSION
+        signer = service_options[:signer] || client_config.signer || Azure::Storage::Common::Core::Auth::SharedKey.new(client_config.storage_account_name, client_config.storage_access_key)
+        signer.api_ver = @api_version if signer.is_a? Azure::Storage::Common::Core::Auth::SharedAccessSignatureSigner
+        super(signer, client_config.storage_account_name, service_options, &block)
+        @storage_service_host[:primary] = client.storage_file_host
+        @storage_service_host[:secondary] = client.storage_file_host true
+      end
+
+      def call(method, uri, body = nil, headers = {}, options = {})
+        content_type = get_or_apply_content_type(body, headers[Azure::Storage::Common::HeaderConstants::FILE_CONTENT_TYPE])
+        headers[Azure::Storage::Common::HeaderConstants::FILE_CONTENT_TYPE] = content_type if content_type
+        headers["x-ms-version"] = @api_version ? @api_version : Default::STG_VERSION
+        headers["User-Agent"] = @user_agent_prefix ? "#{@user_agent_prefix}; #{Default::USER_AGENT}" : Default::USER_AGENT
+
+        response = super
+
+        # Force the response.body to the content charset of specified in the header.
+        # Content-Type is echo'd back for the file and is used to store the encoding of the octet stream
+        if !response.nil? && !response.body.nil? && response.headers["Content-Type"]
+          charset = parse_charset_from_content_type(response.headers["Content-Type"])
+          response.body.force_encoding(charset) if charset && charset.length > 0
+        end
+
+        response
+      end
+
+      # Public: Get a list of Shares from the server.
+      #
+      # ==== Attributes
+      #
+      # * +options+                  - Hash. Optional parameters.
+      #
+      # ==== Options
+      #
+      # Accepted key/value pairs in options parameter are:
+      # * +:prefix+                  - String. Filters the results to return only shares
+      #                                whose name begins with the specified prefix. (optional)
+      #
+      # * +:marker+                  - String. An identifier the specifies the portion of the
+      #                                list to be returned. This value comes from the property
+      #                                Azure::Storage::Common::EnumerationResults.continuation_token when there
+      #                                are more shares available than were returned. The
+      #                                marker value may then be used here to request the next set
+      #                                of list items. (optional)
+      #
+      # * +:max_results+             - Integer. Specifies the maximum number of shares to return.
+      #                                If max_results is not specified, or is a value greater than
+      #                                5,000, the server will return up to 5,000 items. If it is set
+      #                                to a value less than or equal to zero, the server will return
+      #                                status code 400 (Bad Request). (optional)
+      #
+      # * +:metadata+                - Boolean. Specifies whether or not to return the share metadata.
+      #                                (optional, Default=false)
+      #
+      # * +:timeout+                 - Integer. A timeout in seconds.
+      #
+      # * +:request_id+              - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
+      #                                in the analytics logs when storage analytics logging is enabled.
+      #
+      # * +:location_mode+           - LocationMode. Specifies the location mode used to decide 
+      #                                which location the request should be sent to.
+      #
+      # See: https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/list-shares
+      #
+      # Returns an Azure::Storage::Common::EnumerationResults
+      #
+      def list_shares(options = {})
+        query = {}
+        if options
+          StorageService.with_query query, "prefix", options[:prefix]
+          StorageService.with_query query, "marker", options[:marker]
+          StorageService.with_query query, "maxresults", options[:max_results].to_s if options[:max_results]
+          StorageService.with_query query, "include", "metadata" if options[:metadata] == true
+          StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
+        end
+
+        options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
+        uri = shares_uri(query, options)
+        response = call(:get, uri, nil, {}, options)
+
+        Serialization.share_enumeration_results_from_xml(response.body)
+      end
+
+      # Protected: Generate the URI for the collection of shares.
+      #
+      # ==== Attributes
+      #
+      # * +query+ - A Hash of key => value query parameters.
+      #
+      # Returns a URI.
+      #
+      protected
+        def shares_uri(query = {}, options = {})
+          query = { "comp" => "list" }.merge(query)
+          generate_uri("", query, options)
+        end
+
+      # Protected: Generate the URI for a specific share.
+      #
+      # ==== Attributes
+      #
+      # * +name+  - The share name. If this is a URI, we just return this.
+      # * +query+ - A Hash of key => value query parameters.
+      #
+      # Returns a URI.
+      #
+      protected
+        def share_uri(name, query = {}, options = {})
+          return name if name.kind_of? ::URI
+          query = { restype: "share" }.merge(query)
+          generate_uri(name, query, options)
+        end
+
+      # Protected: Generate the URI for a specific directory.
+      #
+      # ==== Attributes
+      #
+      # * +share+                 - String representing the name of the share.
+      # * +directory_path+        - String representing the path to the directory.
+      # * +directory+             - String representing the name to the directory.
+      # * +query+                 - A Hash of key => value query parameters.
+      #
+      # Returns a URI.
+      #
+      protected
+        def directory_uri(share, directory_path, query = {}, options = {})
+          path = directory_path.nil? ? share : ::File.join(share, directory_path)
+          query = { restype: "directory" }.merge(query)
+          options = { encode: true }.merge(options)
+          generate_uri(path, query, options)
+        end
+
+      # Protected: Generate the URI for a specific file.
+      #
+      # ==== Attributes
+      #
+      # * +share+                 - String representing the name of the share.
+      # * +directory_path+        - String representing the path to the directory.
+      # * +file+                  - String representing the name to the file.
+      # * +query+                 - A Hash of key => value query parameters.
+      #
+      # Returns a URI.
+      #
+      protected
+        def file_uri(share, directory_path, file, query = {}, options = {})
+          if directory_path.nil?
+            path = ::File.join(share, file)
+          else
+            path = ::File.join(share, directory_path, file)
+          end
+          options = { encode: true }.merge(options)
+          generate_uri(path, query, options)
+        end
+
+      # Get the content type according to the content type header and request body.
+      #
+      # headers      - The request body
+      # content_type - The request content type
+      protected
+        def get_or_apply_content_type(body, content_type = nil)
+          unless body.nil?
+            if (body.is_a? String) && body.encoding.to_s != "ASCII_8BIT" && !body.empty?
+              if content_type.nil?
+                content_type = "text/plain; charset=#{body.encoding}"
+              else
+                # Force the request.body to the content encoding of specified in the header
+                charset = parse_charset_from_content_type(content_type)
+                body.force_encoding(charset) if charset
+              end
+            else
+              # It is either that the body is not a string, or that the body's encoding is ASCII_8BIT, which is a binary
+              # In this case, set the content type to be default content-type
+              content_type = Default::CONTENT_TYPE_VALUE unless content_type
+            end
+          end
+          content_type
+        end
+    end
+  end
+end
+
+Azure::Storage::FileService = Azure::Storage::File::FileService

data/file/lib/azure/storage/file/serialization.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+#-------------------------------------------------------------------------
+# # Copyright (c) Microsoft and contributors. All rights reserved.
+#
+# The MIT License(MIT)
+
+# 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.
+#--------------------------------------------------------------------------
+require "azure/storage/common/service/serialization"
+
+module Azure::Storage
+  module File
+    module Serialization
+      include Azure::Storage::Common::Service::Serialization
+
+      def self.share_enumeration_results_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("EnumerationResults", xml)
+
+        results = enumeration_results_from_xml(xml, Azure::Storage::Common::Service::EnumerationResults.new)
+
+        return results unless (xml > "Shares").any? && ((xml > "Shares") > "Share").any?
+
+        if xml.Shares.Share.count == 0
+          results.push(share_from_xml(xml.Shares.Share))
+        else
+          xml.Shares.Share.each { |share_node|
+            results.push(share_from_xml(share_node))
+          }
+        end
+
+        results
+      end
+
+      def self.share_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("Share", xml)
+
+        Share::Share.new do |share|
+          share.name = xml.Name.text if (xml > "Name").any?
+          share.properties = share_properties_from_xml(xml.Properties) if (xml > "Properties").any?
+          share.metadata = metadata_from_xml(xml.Metadata) if (xml > "Metadata").any?
+        end
+      end
+
+      def self.share_properties_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("Properties", xml)
+
+        props = {}
+        props[:last_modified] = (xml > "Last-Modified").text if (xml > "Last-Modified").any?
+        props[:etag] = xml.ETag.text if (xml > "ETag").any?
+        props[:quota] = xml.Quota.text if (xml > "Quota").any?
+        props
+      end
+
+      def self.share_from_headers(headers)
+        Share::Share.new do |share|
+          share.properties = share_properties_from_headers(headers)
+          share.quota = quota_from_headers(headers)
+          share.metadata = metadata_from_headers(headers)
+        end
+      end
+
+      def self.share_properties_from_headers(headers)
+        props = {}
+        props[:last_modified] = headers["Last-Modified"]
+        props[:etag] = headers["ETag"]
+        props
+      end
+
+      def self.quota_from_headers(headers)
+        headers["x-ms-share-quota"] ? headers["x-ms-share-quota"].to_i : nil
+      end
+
+      def self.share_stats_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("ShareStats", xml)
+        xml.ShareUsage.text.to_i
+      end
+
+      def self.directories_and_files_enumeration_results_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("EnumerationResults", xml)
+
+        results = enumeration_results_from_xml(xml, Azure::Storage::Common::Service::EnumerationResults.new)
+
+        return results unless (xml > "Entries").any?
+
+        if ((xml > "Entries") > "File").any?
+          if xml.Entries.File.count == 0
+            results.push(file_from_xml(xml.Entries.File))
+          else
+            xml.Entries.File.each { |file_node|
+              results.push(file_from_xml(file_node))
+            }
+          end
+        end
+
+        if ((xml > "Entries") > "Directory").any?
+          if xml.Entries.Directory.count == 0
+            results.push(directory_from_xml(xml.Entries.Directory))
+          else
+            xml.Entries.Directory.each { |directory_node|
+              results.push(directory_from_xml(directory_node))
+            }
+          end
+        end
+
+        results
+      end
+
+      def self.file_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("File", xml)
+
+        File.new do |file|
+          file.name = xml.Name.text if (xml > "Name").any?
+          file.properties = file_properties_from_xml(xml.Properties) if (xml > "Properties").any?
+        end
+      end
+
+      def self.file_properties_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("Properties", xml)
+
+        props = {}
+        props[:content_length] = (xml > "Content-Length").text.to_i if (xml > "Content-Length").any?
+        props
+      end
+
+      def self.directory_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("Directory", xml)
+
+        Directory::Directory.new do |directory|
+          directory.name = xml.Name.text if (xml > "Name").any?
+        end
+      end
+
+      def self.directory_from_headers(headers)
+        Directory::Directory.new do |directory|
+          directory.properties = directory_properties_from_headers(headers)
+          directory.metadata = metadata_from_headers(headers)
+        end
+      end
+
+      def self.directory_properties_from_headers(headers)
+        props = {}
+        props[:last_modified] = headers["Last-Modified"]
+        props[:etag] = headers["ETag"]
+        props
+      end
+
+      def self.file_from_headers(headers)
+        File.new do |file|
+          file.properties = file_properties_from_headers(headers)
+          file.metadata = metadata_from_headers(headers)
+        end
+      end
+
+      def self.file_properties_from_headers(headers)
+        props = {}
+
+        props[:last_modified] = headers["Last-Modified"]
+        props[:etag] = headers["ETag"]
+        props[:type] = headers["x-ms-type"]
+
+        props[:content_length] = headers["Content-Length"].to_i unless headers["Content-Length"].nil?
+        props[:content_length] = headers["x-ms-content-length"].to_i unless headers["x-ms-content-length"].nil?
+
+        props[:content_type] =  headers["Content-Type"]
+        props[:content_encoding] = headers["Content-Encoding"]
+        props[:content_language] = headers["Content-Language"]
+        props[:content_disposition] = headers["Content-Disposition"]
+        props[:content_md5] = headers["x-ms-content-md5"] || headers["Content-MD5"]
+        props[:range_md5] = headers["Content-MD5"] if headers["x-ms-content-md5"] && headers["Content-MD5"]
+        props[:cache_control] = headers["Cache-Control"]
+
+        props[:copy_id] = headers["x-ms-copy-id"]
+        props[:copy_status] = headers["x-ms-copy-status"]
+        props[:copy_source] = headers["x-ms-copy-source"]
+        props[:copy_progress] = headers["x-ms-copy-progress"]
+        props[:copy_completion_time] = headers["x-ms-copy-completion-time"]
+        props[:copy_status_description] = headers["x-ms-copy-status-description"]
+
+        props[:accept_ranges] = headers["Accept-Ranges"].to_i if headers["Accept-Ranges"]
+
+        props
+      end
+
+      def self.range_list_from_xml(xml)
+        xml = slopify(xml)
+        expect_node("Ranges", xml)
+
+        range_list = []
+        return range_list unless (xml > "Range").any?
+
+        if xml.Range.count == 0
+          range_list.push [xml.Range.Start.text.to_i, xml.Range.End.text.to_i]
+        else
+          xml.Range.each { |range|
+            range_list.push [range.Start.text.to_i, range.End.text.to_i]
+          }
+        end
+
+        range_list
+      end
+    end
+  end
+end