azure 0.0.0 → 0.1.0

data/lib/azure/core/signer.rb

@@ -0,0 +1,32 @@
+require "openssl"
+require "base64"
+require "azure/configuration"
+
+module Azure
+  module Core
+    # Public: Utility class to sign strings with HMAC-256 and then encode the
+    # signed string using Base64.
+    class Signer
+      # The Azure account's access key.
+      attr :access_key
+
+      # Public: Initialize the Signer.
+      #
+      # access_key - The Azure access_key encoded in Base64. Defaults to the one
+      #              in the global configuration.
+      def initialize(access_key=Azure.config.access_key)
+        @access_key = Base64.strict_decode64(access_key)
+      end
+
+      # Public: Generate an HMAC signature.
+      #
+      # body - The string to sign.
+      #
+      # Returns a Base64 String signed with HMAC.
+      def sign(body)
+        signed = OpenSSL::HMAC.digest("sha256", access_key, body)
+        Base64.strict_encode64(signed)
+      end
+    end
+  end
+end

data/lib/azure/core/utils/interval.rb

@@ -0,0 +1,97 @@
+require "delegate"
+
+module Azure
+  module Core
+    module Utils
+      # Public: Helper class to decorate a numeric duration so it can be output
+      # as an ISO8601-compliant Duration. (This class only implements a subset
+      # of the ISO8601 standard, since it's what Microsoft appears to be using.)
+      #
+      # Examples
+      #
+      #   # Initialize an Interval from a Number, or use .try_convert to be
+      #   # intelligent:
+      #
+      #   Interval.new(10)              #=> PT10S
+      #   Interval.try_convert(10)      #=> PT10S
+      #   Interval.try_convert("PT10S") #=> PT10S
+      #   Interval.try_convert(nil)     #=> nil
+      class Interval < SimpleDelegator
+
+        # Public: Attempt to convert an object into an Interval.
+        #
+        # object - An object that might be converted into an Interval.
+        #
+        # Returns an Interval or nil.
+        def self.try_convert(object)
+          if object.respond_to?(:to_interval)
+            object.to_interval
+          elsif object.respond_to?(:to_int)
+            new(object)
+          elsif object.respond_to?(:to_str)
+            parse(object)
+          else
+            nil
+          end
+        end
+
+        # Public: Parse a String into an Interval.
+        #
+        # string - A String in the Interval format.
+        #
+        # Returns an Interval.
+        def self.parse(string)
+          re = /
+                P (?<d>[\d]+D)?     # match days
+                (?:
+                 T (?<h>[\d]+H)?    # match hours
+                   (?<m>[\d]+M)?    # match minutes
+                   (?<s>[\d\.]+S)?  # match seconds
+                )?
+               /x
+
+          match = re.match(string)
+
+          return nil if match.nil?
+
+          days    = match[:d].to_i
+          hours   = match[:h].to_i
+          minutes = match[:m].to_i
+          seconds = match[:s].to_f
+
+          new(seconds + minutes * 60 + hours * 3600 + days * 86400)
+        end
+
+        # Public: Return this amount of seconds formatted as an interval.
+        #
+        # Returns a String.
+        def to_s
+          days    = to_i / 86400
+          hours   = (to_i % 86400) / 3600
+          minutes = (to_i % 3600) / 60
+          seconds = (self % 60)
+
+          days = "%<d>s" % {
+            d: days.zero? ? nil : "#{days}D"
+          }
+
+          time = "%<h>s%<m>s%<s>s" % {
+            h: hours.zero?               ? nil : "#{hours}H",
+            m: minutes.zero?             ? nil : "#{minutes}M",
+            s: nonzero? && seconds.zero? ? nil : "#{seconds}S"
+          }
+
+          "P#{days}" + (time.empty? ? "" : "T#{time}")
+        end
+        alias_method :inspect, :to_s
+
+        # Public: Convert this object into an interval.
+        #
+        # Returns self.
+        def to_interval
+          self
+        end
+      end
+    end
+  end
+end

data/lib/azure/core/utils/queryable.rb

@@ -0,0 +1,74 @@
+require "uri"
+
+module Azure
+  module Core
+    module Utils
+      # Convenience module to build query strings.
+      module Queryable
+        # Public: Build a query from a options hash.
+        #
+        # options - A hash of options.
+        #           :partition_key - Only get entities with this PartitionKey
+        #                            (optional, but :row_key must also be
+        #                            included).
+        #           :row_key       - Only get entities with this RowKey
+        #                            (optional, but :partition_key must also
+        #                            be included).
+        #           :select        - An array with property names. Only these
+        #                            properties are provided from the
+        #                            returned returned set of entities.
+        #           :filter        - A string to filter results.
+        #           :top           - Returns only the top n results from the set.
+        #           :skip          - Skips the first n results from the set.
+        #
+        # Returns a query string
+        def build_query(options)
+          select = options.fetch(:select, nil)
+          select = "$select=#{select.join(",")}" if select
+
+          filter = options.fetch(:filter, nil)
+          filter = "$filter=#{filter}" if filter
+
+          top = options.fetch(:top, nil)
+          top = "$top=#{top}" if top
+
+          skip = options.fetch(:skip, nil)
+          skip = "$skip=#{skip}" if skip
+
+          next_partition_key = options.fetch("NextPartitionKey", nil)
+          next_partition_key = "NextPartitionKey=#{next_partition_key}" if next_partition_key
+
+          next_row_key = options.fetch("NextRowKey", nil)
+          next_row_key = "NextRowKey=#{next_row_key}" if next_row_key
+
+          next_table_name = options.fetch("NextTableName", nil)
+          next_table_name = "NextTableName=#{next_table_name}" if next_table_name
+
+          query = [next_table_name, next_partition_key, next_row_key,
+              select, filter, top, skip].compact.join("&")
+
+          query != "" ? ::URI.encode(query) : nil
+        end
+
+        # Public: Build a Hash with translated keys from a options hash.
+        #
+        # options - A hash of options.
+        #           :top    - Returns only the top n results from the set.
+        #           :skip   - Skips the first n results from the set.
+        #
+        # Returns a query string
+        def translate_options_hash(options)
+          hash = {}
+
+          skip = options.fetch(:skip, nil)
+          hash["$skip"] = skip if skip
+
+          top = options.fetch(:top, nil)
+          hash["$top"] = top if top
+
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/azure/core/utils/storage_service_properties.rb

@@ -0,0 +1,83 @@
+require 'nokogiri'
+
+module Azure
+  module Core
+    module Utils
+      class StorageServiceProperties
+
+        REQUIRED_ELEMENTS = {
+          "Version" => true,
+          "Delete" => true,
+          "Read" => true,
+          "Write" => true,
+          "Enabled" => true,
+          "RetentionPolicy / Enabled" => true,
+          "RetentionPolicy / Days" => true,
+          "IncludeAPIs" => "Metrics"
+        }
+
+        def self.hash_to_xml(hash)
+          doc = Nokogiri::XML::Document.new
+          doc.encoding = "utf-8"
+          root = Nokogiri::XML::Node.new("StorageServiceProperties", doc)
+          iterate_hash(hash, root, doc)
+          doc << root
+          validate(doc)
+          doc
+        end
+
+        def self.hash_to_xml_string(hash)
+          hash_to_xml(hash).to_xml
+        end
+
+        def self.xml_string_to_hash(xml)
+          doc = Nokogiri::XML.parse(xml)
+          iterate_node(doc)["StorageServiceProperties"]
+        end
+
+        private
+
+        def self.iterate_node(node)
+          node.children.each_with_object({}) do |node, hash|
+
+            next if !node.element?
+
+            if node.children.size == 1
+              hash[node.name] = node.text
+            else
+              hash[node.name] = iterate_node(node)
+            end
+          end
+        end
+
+        def self.iterate_hash(hash, root, doc)
+          hash.each do |key, value|
+            if value.is_a?(Hash)
+              node = Nokogiri::XML::Node.new(key, doc)
+              iterate_hash(value, node, doc)
+              root << node
+            else
+              node = Nokogiri::XML::Node.new(key, doc)
+              node.content = value
+              root << node
+            end
+          end
+        end
+
+        def self.validate(doc)
+          missing_keys = []
+
+          REQUIRED_ELEMENTS.each do |key,value|
+            if value == true
+              missing_keys << key if (doc / key).empty?
+            elsif (doc / value).empty? || (doc / key).empty?
+              missing_keys << key
+            end
+          end
+
+          raise StandardError, "StorageServicePropertiesMissing", missing_keys if !missing_keys.empty?
+        end
+      end
+    end
+  end
+end

data/lib/azure/core/utils/string.rb

@@ -0,0 +1,59 @@
+module Azure
+  module Core
+    module Utils
+      # Convenience module to build query strings.
+      module String
+        # The following methods have been borrowed (stolen?) from ActiveSupport
+
+        # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+
+        # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase.
+        #
+        # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces.
+        #
+        # Examples:
+        #   "active_model".camelize                # => "ActiveModel"
+        #   "active_model".camelize(:lower)        # => "activeModel"
+        #   "active_model/errors".camelize         # => "ActiveModel::Errors"
+        #   "active_model/errors".camelize(:lower) # => "activeModel::Errors"
+        #
+        # As a rule of thumb you can think of +camelize+ as the inverse of +underscore+,
+        # though there are cases where that does not hold:
+        #
+        #   "SSLError".underscore.camelize # => "SslError"
+        def camelize(term, uppercase_first_letter = true)
+          string = term.to_s
+          acronyms = {}
+          if uppercase_first_letter
+            string = string.sub(/^[a-z\d]*/) { acronyms[$&] || $&.capitalize }
+          else
+            string = string.sub(/^(?:(?=a)b(?=\b|[A-Z_])|\w)/) { $&.downcase }
+          end
+          string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{acronyms[$2] || $2.capitalize}" }.gsub('/', '::')
+        end
+
+        # Makes an underscored, lowercase form from the expression in the string.
+        #
+        # Changes '::' to '/' to convert namespaces to paths.
+        #
+        # Examples:
+        #   "ActiveModel".underscore         # => "active_model"
+        #   "ActiveModel::Errors".underscore # => "active_model/errors"
+        #
+        # As a rule of thumb you can think of +underscore+ as the inverse of +camelize+,
+        # though there are cases where that does not hold:
+        #
+        #   "SSLError".underscore.camelize # => "SslError"
+        def underscore(camel_cased_word)
+          word = camel_cased_word.to_s.dup
+          word.gsub!(/::/, '/')
+          word.gsub!(/(?:([A-Za-z\d])|^)((?=a)b)(?=\b|[^a-z])/) { "#{$1}#{$1 && '_'}#{$2.downcase}" }
+          word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+          word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+          word.tr!("-", "_")
+          word.downcase!
+          word
+        end
+      end
+    end
+  end
+end

data/lib/azure/error.rb

@@ -0,0 +1,72 @@
+require "xml"
+
+module Azure
+  # Public: Superclass for errors generated from this library, so people can
+  # just rescue this for generic error handling.
+  class Error < StandardError; end
+
+  # Public: FileUploadError
+  class FileUploadError < ::Azure::Error; end
+
+  # Public: Class for handling all HTTP response errors.
+  class HTTPError < ::Azure::Error
+    # Public: The HTTP status code of this error.
+    #
+    # Returns a Fixnum.
+    attr :code
+
+    # Public: The type of error, as described by the Azure documentation.
+    #
+    # Returns a String.
+    attr :type
+
+    # Public: The English description of this error.
+    #
+    # Returns a String.
+    attr :description
+
+    # Public: Initialize an error.
+    #
+    # http_response - An Azure::Response.
+    def initialize(http_response)
+      @http_response = http_response
+      @code = http_response.code
+      parse_response
+      super("#{type} (#{code}): #{description}")
+    end
+
+    # Extract the relevant information from the response's body. If the response
+    # body is not an XML, we return an 'Unknown' error with the entire body as
+    # the description.
+    #
+    # Returns nothing.
+    def parse_response
+      if @http_response.body.include?("<")
+        document = XML::Parser.string(@http_response.body).parse
+
+        # FIXME: For some reason document.find_first("code") (or "//code", etc.)
+        # and document.find_first("message") return nil, while this works. It
+        # makes no sense that this works and that doesn't. Oh well.
+        document.root.children.each do |child|
+          @type = child.content if child.name == "code"
+          @description = child.content if child.name == "message"
+        end
+      else
+        @type = "Unknown"
+        @description = @http_response.body.strip
+      end
+    end
+  end
+
+  # Public: Mixin that gives a few convenience methods for handling errors in
+  # domain objects.
+  module ErrorHandler
+    # Public: Get/Set the current error in this object.
+    attr_accessor :error
+
+    # Public: Check if this object doesn't have any errors.
+    def valid?
+      error.nil?
+    end
+  end
+end

data/lib/azure/queues.rb

@@ -0,0 +1,272 @@
+require "nokogiri"
+require "azure/queues/service"
+require "azure/queues/queue"
+require "azure/queues/message"
+require "azure/queues/service_properties"
+require "azure/queues/uri"
+
+module Azure
+  module Queues
+    # Public: This operation gets the properties of a storage account’s Queue Service.
+    # If the operation is unsuccessful the resulting object will have the error
+    # accessible through the #error method.
+    #
+    # options - Options for this query (default: {}):
+    #           :timeout  - (optional) timeout for the request in seconds
+    # service - The backend service to implement this (optional).
+    #
+    # Returns an Azure::Queues::ServiceProperties object
+    def self.get_service_properties(options = {}, service=Azure::Queues::Services::GetServiceProperties.new)
+      response = service.call(options)
+
+      if response.success?
+        result = Nokogiri::XML(response.body)
+        node = result.xpath('//StorageServiceProperties').first
+        ServiceProperties.from_node(node)
+      else
+        ServiceProperties.from_error(response.error)
+      end
+    end
+
+    # Public: This operation sets the properties of a storage account’s Queue Service.
+    # If the operation is unsuccessful the resulting object will have the error
+    # accessible through the #error method.
+    #
+    # properties  - an Azure::Queues::ServiceProperties object
+    # options     - Options for this query (default: {}):
+    #               :timeout  - (optional) timeout for the request in seconds
+    # service     - The backend service to implement this (optional).
+    #
+    # Returns an Azure::Queues::ServiceProperties object
+    def self.set_service_properties(properties, options = {}, service=Azure::Queues::Services::SetServiceProperties.new)
+      response = service.call(properties, options)
+      properties.error = response.error unless response.success?
+      response.success?
+    end
+
+    # Public: This operation lists all of the queues in a given storage account.
+    # GET http://myaccount.queue.core.windows.net?comp=list
+    #
+    # options - Options for this query (default: {}):
+    #           :prefix           - Filters the results to return only queues with names that begin with the specified prefix.
+    #           :marker           - A string value that identifies the portion of the list to be returned with the next list operation.
+    #           :maxresults       - Specifies the maximum number of queues to return
+    #           :include_metadata - Include this parameter to specify that the container's metadata be returned as part of the response body.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns an Array of Query elements.
+    def self.all(options = {}, service=Azure::Queues::Services::ListQueues.new)
+      response = service.call(options)
+
+      if response.success?
+        result = Nokogiri::XML(response.body)
+        result.xpath('//Queues/Queue').map {|node| Queue.from_node(node) }
+      else
+        []
+      end
+    end
+
+    # Public: Try to create a new queue. If the operation is unsuccessful,
+    # the resulting Queue object will have the error accessible through the
+    # #error method.
+    #
+    # name     - The name of the container.
+    # metadata - User defined metadata for this container (optional).
+    # service  - The backend service to implement this (optional).
+    #
+    # Returns a Queue.
+    def self.create(name, metadata={}, service=Azure::Queues::Services::CreateQueue.new)
+      response = service.call(name, metadata)
+
+      if response.success?
+        Queue.new(name)
+      else
+        Queue.from_error(response.error)
+      end
+    end
+
+    # Public: Delete a Queue from the server. If the delete operation fails,
+    # the queue is invalidated. Otherwise it's frozen.
+    #
+    # queue   - An Azure::Queues::Queue.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns true|false to indicate success.
+    def self.delete(queue, service=Azure::Queues::Services::DeleteQueue.new)
+      response = service.call(queue.name)
+
+      if response.success?
+        queue.freeze
+      else
+        queue.error = response.error
+      end
+
+      response.success?
+    end
+
+    # Public: Obtain the queue metadata. This updates the queue and
+    # changes the metadata internally if successful. If the operation fails, the
+    # queue's metadata does not change, and the queue is invalidated.
+    #
+    # queue   - An Azure::Queues::Queue.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns a Hash.
+    def self.load_metadata(queue, service=Azure::Queues::Services::GetMetadata.new)
+      response = service.call(queue.name)
+
+      if response.success?
+        queue.extract_metadata(response.headers)
+      else
+        queue.error = response.error
+        {}
+      end
+    end
+
+    # Public: Save the current metadata of a queue in the storage service.
+    # If the operation fails, the queue is invalidated.
+    #
+    # queue   - An Azure::Queues::Queue.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns true|false to indicate success.
+    def self.save_metadata(queue, service=Azure::Queues::Services::SetMetadata.new)
+      response = service.call(queue.name, queue.metadata)
+      queue.error = response.error unless response.success?
+      response.success?
+    end
+
+    ## MESSAGES
+
+    # Public: Try to add a new message to the back of the message queue. If the
+    # operation is unsuccessful, the message is invalidated.
+    #
+    # queue   - An Azure::Queues::Queue.
+    # message - An Azure::Queues::Message.
+    # options - A Hash of options for this operation.
+    #           :visibilitytimeout - Time in seconds until the message becomes
+    #                                visible in the queue (default: 0).
+    #           :messagettl        - Time-to-live interval for the message in
+    #                                seconds. Can go up to 7 days (the
+    #                                default).
+    # service - The backend service to implement this (optional).
+    #
+    # Returns the message.
+    def self.put_message(queue, message, options = {}, service=Azure::Queues::Services::PutMessage.new)
+      response = service.call(queue.name, message.text, options)
+
+      if response.success?
+        message.queue = queue
+      else
+        message.error = response.error
+      end
+
+      message
+    end
+
+    # Public: Get one or more messages from the front of the queue.
+    #
+    # FIXME: Handle errors.
+    #
+    # queue   - An Azure::Queues::Queue.
+    # options - A Hash of options for this operation (optional):
+    #           :visibilitytimeout - Update the returned messages'
+    #                                visibilitytimeout to this number (at least
+    #                                1, the default).
+    #           :numofmessages     - A number between 1 and 32 of messages to
+    #                                return (default: 1).
+    # service - The backend service to implement this (optional).
+    #
+    # Returns an Array of Messages.
+    def self.get_messages(queue, options = {}, service = Azure::Queues::Services::GetMessages.new)
+      response = service.call(queue.name, options)
+
+      # FIXME: need error handling
+      document = Nokogiri::XML(response.body)
+      (document / "//QueueMessagesList/QueueMessage").map do |node|
+        Message.from_node(node) { |m| m.queue = queue }
+      end
+    end
+
+    # Public: Peek at one or more messages from the front of the queue.
+    #
+    # queue   - The message queue
+    # options - A Hash of options for this operation (optional):
+    #           :numofmessages - A number between 1 and 32 of messages to return
+    #                            (default: 1).
+    # service - The backend service to implement this (optional).
+    #
+    # Returns an Array of Messages.
+    def self.peek_messages(queue, options = {}, service = Azure::Queues::Services::PeekMessages.new)
+      response = service.call(queue.name, options)
+
+      # FIXME: need error handling
+      document = Nokogiri::XML(response.body)
+      (document / "//QueueMessagesList/QueueMessage").map do |node|
+        Message.from_node(node) { |m| m.queue = queue }
+      end
+    end
+
+    # Public: Delete the specified message from the queue. If the operation
+    # fails, the message is invalidated.
+    #
+    # message - An Azure::Queues::Message.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns true|false to indicate success.
+    def self.delete_message(message, service = Azure::Queues::Services::DeleteMessage.new)
+      response = service.call(
+        message.queue.name,
+        message.id,
+        message.pop_receipt
+      )
+
+      if response.success?
+        message.freeze
+      else
+        message.error = response.error
+      end
+
+      response.success?
+    end
+
+    # Public: Delete all messages from the queue. If the operation fails, the
+    # queue is invalidated.
+    #
+    # queue   - The message queue.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns true|false to indicate success.
+    def self.clear_messages(queue, service = Azure::Queues::Services::ClearMessages.new)
+      response = service.call(queue.name)
+      queue.error = response.error unless response.success?
+      response.success?
+    end
+
+    # Public: Update the specified message. If the operation fails, the message
+    # is invalidated.
+    #
+    # message - An Azure::Queues::Message.
+    # service - The backend service to implement this (optional).
+    #
+    # Returns true|false to indicate success.
+    def self.update_message(message, service=Azure::Queues::Services::UpdateMessage.new)
+      response = service.call(
+        message.queue.name,
+        message.id,
+        message.text,
+        message.visibility_timeout,
+        message.pop_receipt
+      )
+
+      if response.success?
+        message.time_next_visible = response.headers['x-ms-time-next-visible']
+        message.pop_receipt       = response.headers['x-ms-popreceipt']
+      else
+        message.error = response.error
+      end
+
+      response.success?
+    end
+  end
+end