waz-storage 0.5.0

data/lib/waz-blobs.rb

@@ -0,0 +1,20 @@
+require 'time'
+require 'cgi'
+require 'base64'
+require 'rexml/document'
+require 'rexml/xpath'
+require 'restclient'
+require 'hmac-sha2'
+
+$:.unshift(File.dirname(__FILE__))
+require 'waz/storage/base'
+require 'waz/storage/core_service'
+require 'waz/storage/exceptions'
+require 'waz/storage/version'
+require 'waz/blobs/blob_object'
+require 'waz/blobs/container'
+require 'waz/blobs/exceptions'
+require 'waz/blobs/service'
+require 'waz/blobs/version'
+
+

data/lib/waz-queues.rb

@@ -0,0 +1,21 @@
+require 'time'
+require 'cgi'
+require 'base64'
+require 'rexml/document'
+require 'rexml/xpath'
+
+require 'restclient'
+require 'hmac-sha2'
+
+$:.unshift(File.dirname(__FILE__))
+require 'waz/storage/base'
+require 'waz/storage/core_service'
+require 'waz/storage/exceptions'
+require 'waz/storage/version'
+require 'waz/queues/exceptions'
+require 'waz/queues/message'
+require 'waz/queues/queue'
+require 'waz/queues/service'
+require 'waz/queues/version'
+
+

data/lib/waz-storage.rb

@@ -0,0 +1,5 @@
+$:.unshift(File.dirname(__FILE__))
+require 'waz/storage/base'
+require 'waz/storage/core_service'
+require 'waz/storage/exceptions'
+require 'waz/storage/version'

data/lib/waz/blobs/blob_object.rb

@@ -0,0 +1,90 @@
+module WAZ
+  module Blobs
+    # This class is used to model the Blob inside Windows Azure Blobs the usage
+    # it's pretty simple, here you can see a couple of samples. These are the implemented methods of the blob API up to now. 
+    # The basics are implemented although blocks management is not yet completed, I consider that the API is pretty usable since 
+    # it covers the basics
+    #
+    #   # retrieve blob name, uri and content-type
+    #   blob.name
+    #   blob.url
+    #   blob.content_type
+    #
+    # 	# retrieve blob value 
+    #   blob.value #=> lazy loaded payload of the blob
+    #
+    #   # retrieve blob metadata (+ properties)
+    #   blob.metadata #=> hash containing beautified metadata (:x_ms_meta_name)
+    #   
+    #   # put blob metadata
+    #   blob.put_properties(:x_ms_meta_MyProperty => "my value") 
+    #
+    # 	# update value
+    #   blob.value = "my new value" #=> this will update the blob content on WAZ
+    #
+    # *REMARKS*: This class is not meant to be manually instanciated it's basicaly an internal 
+    # representation returned by the WAZ::Blobs::Container.
+    class BlobObject      
+      class << self
+        # This method is internally used by this class. It's the way we keep a single instance of the 
+        # service that wraps the calls the Windows Azure Blobs API. It's initialized with the values
+        # from the default_connection on WAZ::Storage::Base initialized thru establish_connection!
+        def service_instance
+          @service_instance ||= Service.new(WAZ::Storage::Base.default_connection.merge(:type_of_service => "blob"))
+        end        
+      end
+      
+      attr_accessor :name, :url, :content_type
+      
+      # Creates a new instance of the Blob object. This constructor is internally used by the Container
+      # it's initialized thru a hash that's received as parameter. It has the following requirements:
+      # <em>:name</em> which is the blob name (usually the file name), <em>:url</em> that is the url of the blob (used to download or access it via browser) 
+      # and <em>:content_type</em> which is the content type of the blob and is a required parameter by the Azure API
+      def initialize(options = {})
+        raise WAZ::Storage::InvalidOption, :name unless options.keys.include?(:name) and !options[:name].empty?
+        raise WAZ::Storage::InvalidOption, :url unless options.keys.include?(:url) and !options[:url].empty?
+        raise WAZ::Storage::InvalidOption, :content_type unless options.keys.include?(:content_type) and !options[:content_type].empty?
+        self.name = options[:name]
+        self.url = options[:url]
+        self.content_type = options[:content_type]
+      end
+      
+      # Returns the blob properties from Windows Azure. This properties always come as HTTP Headers and they include standard headers like
+      # <em>Content-Type</em>, <em>Content-Length</em>, etc. combined with custom properties like with <em>x-ms-meta-Name</em>.
+      def metadata
+        self.class.service_instance.get_blob_properties(path)
+      end
+      
+      # Returns the actual blob content, this method is specially used to avoid retrieving the whole blob
+      # while iterating and retrieving the blob collection from the Container.
+      def value
+        @value ||= self.class.service_instance.get_blob(path)
+      end
+      
+      # Assigns the given value to the blob content. It also stores a local copy of it in order to avoid round trips 
+      # on scenarios when you do Save and Display on the same context.
+      def value=(new_value)
+        self.class.service_instance.put_blob(path, new_value, content_type, metadata)
+        @value = new_value
+      end
+
+      # Stores the blob properties. Those properties are sent as HTTP Headers it's really important that you name your custom 
+      # properties with the <em>x-ms-meta</em> prefix, if not the won't be persisted by the Windows Azure Blob Storage API.
+      def put_properties!(properties = {})
+        self.class.service_instance.set_blob_properties(path, properties)
+      end
+      
+      # Removes the blob from the container.
+      def destroy!
+        self.class.service_instance.delete_blob(path)
+      end
+      
+      # Returns the blob path. This is specially important when simulating containers inside containers
+      # by enabling the API to point to the appropiated resource.
+      def path
+        url.gsub(/https?:\/\/[^\/]+\//i, '').scan(/([^&]+)/i).first().first()
+      end
+    end
+  end
+end
+  

data/lib/waz/blobs/container.rb

@@ -0,0 +1,135 @@
+module WAZ
+  module Blobs
+    # This class is used to model the Container inside Windows Azure Blobs the usage
+    # it's pretty simple, here you can see a couple of samples. Here you can find Microsoft's REST API description available on MSDN 
+    # at http://msdn.microsoft.com/en-us/library/dd179361.aspx
+    #
+    #  # list available containers
+  	#  WAZ::Blobs::Container.list
+    #
+  	#  # create a container
+  	#  WAZ::Blobs::Container.create('my-container')
+    #
+  	#  # get a specific container 
+  	#  my_container = WAZ::Blobs::Container.find('my-container')
+    #
+  	#  # get container properties (including default headers)
+  	#  my_container.metadata #=> hash containing beautified metadata (:x_ms_meta_name)
+    #
+  	#  # set container properties (should follow x-ms-meta to be persisted)
+  	#  my_container.put_properties(:x_ms_meta_MyProperty => "my value")
+    #
+  	#  # get a the value indicating whether the container is public or not
+  	#  my_container.public_access? #=> true or false based on x-ms-prop-publicaccess
+  	#
+  	#  # set a value indicating whether the container is public or not
+  	#  my_container.public_access = false
+    #
+  	#  # delete container
+  	#  my_container.destroy!
+  	#
+  	#  # store a blob on the given container
+  	#  my_container.store('my-blob', blob_content, 'application/xml')
+  	#
+  	#  # retrieve a particular blob from a container
+    #  my_container['my-blob']
+    #
+  	#  # retrieve a blob list from a container
+  	#  my_container.blobs #=> WAZ::Blobs::BlobObject collection
+  	#
+    class Container
+      class << self 
+        # Creates a new container with the given name.
+        def create(name)
+          service_instance.create_container(name)
+          return Container.new(:name => name)
+        end
+        
+        # Finds a container by name. It will return nil if no container was found.
+        def find(name)
+          begin 
+            properties = service_instance.get_container_properties(name)
+            return Container.new(properties.merge(:name => name))
+          rescue RestClient::ResourceNotFound
+            return nil
+          end
+        end
+        
+        # Returns all the containers on the given account.
+        def list(options = {})
+          service_instance.list_containers(options).map { |container| Container.new(container) }
+        end
+        
+        # This method is internally used by this class. It's the way we keep a single instance of the 
+        # service that wraps the calls the Windows Azure Blobs API. It's initialized with the values
+        # from the default_connection on WAZ::Storage::Base initialized thru establish_connection!
+        def service_instance
+          @service_instance ||= Service.new(WAZ::Storage::Base.default_connection.merge(:type_of_service => "blob"))
+        end        
+      end
+      
+      attr_accessor :name
+      
+      # Creates a new instance of the WAZ::Blobs::Container. This class isn't intended for external use
+      # to access or create a container you should use the class methods provided like list, create, or find.
+      def initialize(options = {})
+        raise WAZ::Storage::InvalidOption, :name unless options.keys.include?(:name) and !options[:name].empty?
+        self.name = options[:name]
+      end
+      
+      # Returns the container metadata.
+      def metadata
+        self.class.service_instance.get_container_properties(self.name)
+      end
+      
+      # Adds metadata for the container.Those properties are sent as HTTP Headers it's really important that you name your custom 
+      # properties with the <em>x-ms-meta</em> prefix, if not the won't be persisted by the Windows Azure Blob Storage API.
+      def put_properties!(properties = {})
+        self.class.service_instance.set_container_properties(self.name, properties)
+      end
+      
+      # Removes the container from the current account.
+      def destroy!
+        self.class.service_instance.delete_container(self.name)
+      end
+      
+      # Retuns a value indicating whether the container is public accessible (i.e. from a Web Browser) or not.
+      def public_access?
+        self.class.service_instance.get_container_acl(self.name)
+      end
+      
+      # Sets a value indicating whether the container is public accessible (i.e. from a Web Browser) or not.      
+      def public_access=(value)
+        self.class.service_instance.set_container_acl(self.name, value)
+      end
+      
+      # Returns a list of blobs (WAZ::Blobs::BlobObject) contained on the current container.
+      def blobs
+        self.class.service_instance.list_blobs(name).map { |blob| WAZ::Blobs::BlobObject.new(blob) }
+      end
+      
+      # Stores a blob on the container with under the given name, with the given content and 
+      # the required <em>content_type</em>. <strong>The <em>options</em> parameters if provided
+      # will set the default metadata properties for the blob</strong>.
+      def store(blob_name, payload, content_type, options = {})
+        self.class.service_instance.put_blob("#{self.name}/#{blob_name}", payload, content_type, options)
+        return BlobObject.new(:name => blob_name, 
+                              :url => self.class.service_instance.generate_request_uri("#{self.name}/#{blob_name}"),
+                              :content_type => content_type)
+      end
+      
+      # Retrieves the blob by the given name. If the blob isn't found on the current container
+      # it will return nil instead of throwing an exception.
+      def [](blob_name)
+        begin
+          properties = self.class.service_instance.get_blob_properties("#{self.name}/#{blob_name}")
+          return BlobObject.new(:name => blob_name, 
+                                :url => self.class.service_instance.generate_request_uri("#{self.name}/#{blob_name}"),
+                                :content_type => properties[:content_type])
+        rescue RestClient::ResourceNotFound
+          return nil
+        end
+      end
+    end
+  end
+end

data/lib/waz/blobs/service.rb

@@ -0,0 +1,129 @@
+module WAZ
+  module Blobs
+    # This is internally used by the waz-blobs part of the gem and it exposes the Windows Azure Blob API REST methods 
+    # implementation. You can use this class to perform an specific operation that isn't provided by the current API.
+    class Service
+      include WAZ::Storage::SharedKeyCoreService
+      
+      # Creates a container on the current Windows Azure Storage account.
+      def create_container(container_name)
+        url = generate_request_uri(container_name)
+        request = generate_request("PUT", url)
+        request.execute()
+      end
+      
+      # Retrieves all the properties existing on the container.
+      def get_container_properties(container_name)
+        url = generate_request_uri(container_name)
+        request = generate_request("GET", url)
+        request.execute().headers
+      end
+      
+      # Set the container properties (metadata). 
+      #
+      # Remember that custom properties should be named as :x_ms_meta_{propertyName} in order
+      # to have Windows Azure to persist them.
+      def set_container_properties(container_name, properties = {})
+        url = generate_request_uri(container_name, :comp => 'metadata')
+        request = generate_request("PUT", url, properties)
+        request.execute()
+      end
+      
+      # Retrieves the value of the :x_ms_prop_publicaccess header from the
+      # container properties indicating whether the container is publicly 
+      # accessible or not.
+      def get_container_acl(container_name)
+        url = generate_request_uri(container_name, :comp => 'acl')
+        request = generate_request("GET", url)
+        request.execute().headers[:x_ms_prop_publicaccess].downcase == true.to_s
+      end
+
+      # Sets the value of the :x_ms_prop_publicaccess header from the
+      # container properties indicating whether the container is publicly 
+      # accessible or not.
+      #
+      # Default is _false_
+      def set_container_acl(container_name, public_available = false)
+        url = generate_request_uri(container_name, :comp => 'acl')
+        request = generate_request("PUT", url, "x-ms-prop-publicaccess" => public_available.to_s)
+        request.execute()
+      end
+
+      # Lists all the containers existing on the current storage account.
+      def list_containers(options = {})
+        url = generate_request_uri( nil, options.merge(:comp => 'list'))
+        request = generate_request("GET", url)
+        doc = REXML::Document.new(request.execute())
+        containers = []
+        REXML::XPath.each(doc, '//Container/') do |item|
+          containers << { :name => REXML::XPath.first(item, "Name").text,
+                          :url => REXML::XPath.first(item, "Url").text,
+                          :last_modified => REXML::XPath.first(item, "LastModified").text}
+        end
+        return containers
+      end
+
+      # Deletes the given container from the Windows Azure Storage account.
+      def delete_container(container_name)
+        url = generate_request_uri(container_name)
+        request = generate_request("DELETE", url)
+        request.execute()
+      end
+
+      # Lists all the blobs inside the given container.
+      def list_blobs(container_name)
+        url = generate_request_uri(container_name, :comp => 'list')
+        request = generate_request("GET", url)
+        doc = REXML::Document.new(request.execute())
+        containers = []
+        REXML::XPath.each(doc, '//Blob/') do |item|
+          containers << { :name => REXML::XPath.first(item, "Name").text,
+                          :url => REXML::XPath.first(item, "Url").text,
+                          :content_type =>  REXML::XPath.first(item, "ContentType").text }
+        end
+        return containers
+      end
+
+      # Stores a blob on the given container.
+      # 
+      # Remarks path and payload are just text.
+      # 
+      # content_type is required by the blobs api, but on this method is defaulted to "application/octect-stream"
+      #
+      # metadata is a hash that stores all the properties that you want to add to the blob when creating it.
+      def put_blob(path, payload, content_type = "application/octet-stream", metadata = {})
+        url = generate_request_uri( path)
+        request = generate_request("PUT", url, metadata.merge("Content-Type" => content_type), payload)
+        request.execute()
+      end
+      
+      # Retrieves a blob (content + headers) from the current path.
+      def get_blob(path)
+        url = generate_request_uri( path)
+        request = generate_request("GET", url)
+        request.execute()
+      end
+
+      # Deletes the blob existing on the current path.
+      def delete_blob(path)
+        url = generate_request_uri( path)
+        request = generate_request("DELETE", url)
+        request.execute()
+      end
+            
+      # Retrieves the properties associated with the blob at the given path.
+      def get_blob_properties(path)
+        url = generate_request_uri( path)
+        request = generate_request("HEAD", url)
+        request.execute().headers
+      end
+
+      # Sets the properties (metadata) associated to the blob at given path.
+      def set_blob_properties(path, properties ={})
+        url = generate_request_uri( path, :comp => 'metadata')
+        request = generate_request("PUT", url, properties)
+        request.execute()
+      end
+    end
+  end
+end

data/lib/waz/queues/exceptions.rb

@@ -0,0 +1,29 @@
+module WAZ
+  module Queues    
+    # This exception is raised while trying when calling WAZ::Queues::Queue.create('queue_name') and
+    # the metadata existing on the Queues Storage subsytem on the cloud contains different metadata from 
+    # the given one.
+    class QueueAlreadyExists < WAZ::Storage::StorageException
+      def initialize(name)
+        super("The queue #{name} already exists on your account.")
+      end
+    end
+    
+    # This exception is raised when an initialization parameter of any of the WAZ::Queues classes falls of 
+    # the specified values.
+    class OptionOutOfRange < WAZ::Storage::StorageException
+      def initialize(args = {})
+        super("The #{args[:name]} parameter is out of range allowed values go from #{args[:min]} to  #{args[:max]}.")
+      end
+    end
+    
+    # This exception is raised when the user tries to perform a delete operation over a peeked message. Since
+    # peeked messages cannot by deleted given the fact that there's no pop_receipt associated with it 
+    # this exception will be raised.
+    class InvalidOperation < WAZ::Storage::StorageException
+      def initialize()
+        super("A peeked message cannot be delete, you need to lock it first (pop_receipt required).")
+      end
+    end
+  end
+end

data/lib/waz/queues/message.rb

@@ -0,0 +1,63 @@
+module WAZ
+  module Queues
+    # This class is used to model a Message inside Windows Azure Queues the usage
+    # it's pretty simple, here you can see a couple of samples. Messages consist on an UTF-8 string up-to 8KB and some metadata
+    # regarding its status and visibility. Here are all the things that you can do with a message:
+    #
+    #  message.message_id #=> returns message id
+    #
+  	#  # this is the most important method regarding messages
+  	#  message.message_text #=> returns message contents
+    #  
+  	#  message.pop_receipt #=> used for correlating your dequeue request + a delete operation
+    #  
+  	#  message.expiration_time #=> returns when the message will be removed from the queue
+    #
+  	#  message.time_next_visible #=> when the message will be visible to other users
+    #
+  	#  message.insertion_time #=> when the message will be visible to other users
+    #
+  	#  message.queue_name #=> returns the queue name where the message belongs
+    #
+  	#  # remove the message from the queue
+  	#  message.destroy! 
+  	#
+    class Message      
+      class << self
+        # This method is internally used by this class. It's the way we keep a single instance of the 
+        # service that wraps the calls the Windows Azure Queues API. It's initialized with the values
+        # from the default_connection on WAZ::Storage::Base initialized thru establish_connection!
+        def service_instance
+          @service_instance ||= Service.new(WAZ::Storage::Base.default_connection.merge(:type_of_service => 'queue'))
+        end
+      end
+      
+      attr_accessor :message_id, :message_text, :pop_receipt, :expiration_time, :insertion_time, :time_next_visible
+       
+      # Creates an instance of Message class, this method is intended to be used internally from the 
+      # Queue.
+      def initialize(params = {})
+        self.message_id = params[:message_id]
+        self.message_text = params[:message_text]
+        self.pop_receipt = params[:pop_receipt] 
+        self.expiration_time = params[:expiration_time]
+        self.insertion_time = params[:insertion_time]
+        self.time_next_visible = params[:time_next_visible]
+        @queue_name = params[:queue_name]
+      end
+      
+      # Returns the Queue name where the Message belongs to
+      def queue_name
+        return @queue_name
+      end
+      
+      # Marks the message for deletion (to later be removed from the queue by the garbage collector). If the message
+      # where the message is being actually called was peeked from the queue instead of locked it will raise the 
+      # WAZ::Queues:InvalidOperation exception since it's not a permited operation.
+      def destroy!
+        raise WAZ::Queues::InvalidOperation if pop_receipt.nil?
+        self.class.service_instance.delete_message(queue_name, message_id, pop_receipt)
+      end            
+    end
+  end
+end

data/lib/waz/queues/queue.rb

@@ -0,0 +1,154 @@
+module WAZ
+  module Queues
+    # This class represents a Queue on Windows Azure Queues API. These are the methods implemented from Microsoft's API description 
+    # available on MSDN at http://msdn.microsoft.com/en-us/library/dd179363.aspx
+    #
+    #	# list available queues
+    #	WAZ::Queues::Queue.list
+    #
+    #	# create a queue (here you can also send hashed metadata)
+    #	WAZ::Queues::Queue.create('my-container')
+    #
+    #	# get a specific queue
+    #	queue = WAZ::Queues::Container.find('my-container')
+    #
+    #	# get queue properties (including default headers)
+    #	queue.metadata #=> hash containing beautified metadata (:x_ms_meta_name)
+    #
+    #	# set container properties (should follow x-ms-meta to be persisted)
+    #	# if you specify the optional parameter overwrite, existing metadata 
+    #	# will be deleted else merged with new one.
+    #	queue.put_properties!(:x_ms_meta_MyProperty => "my value")
+    #
+    #	# delete queue
+    #	queue.destroy!
+    #
+    #	# clear queue contents
+    #	queue.clear
+    #
+    #	# enqueue a message 
+    #	queue.enqueue!("payload of the message")
+    #
+    #	# peek a message/s (do not alter visibility, it can't be deleted neither)
+    #	# num_of_messages (1 to 32) to be peeked (default 1)
+    #	message = queue.peek
+    #
+    #	# lock a message/s.
+    #	# num_of_messages (1 to 32) to be peeked (default 1)
+    #	# visiblity_timeout (default 60 sec. max 7200 [2hrs])
+    #	message = queue.lock
+    #
+    class Queue
+      class << self
+        # Returns an array of the queues (WAZ::Queues::Queue) existing on the current 
+        # Windows Azure Storage account.
+        def list
+          service_instance.list_queues.map do |queue|
+            WAZ::Queues::Queue.new(queue)
+          end
+        end
+        
+        # Creates a queue on the current account. If provided the metadata hash will specify additional 
+        # metadata to be stored on the queue. (Remember that metadata on the storage account must start with 
+        # :x_ms_metadata_{yourCustomPropertyName}, if not it will not be persisted).
+        def create(queue_name, metadata = {})
+          service_instance.create_queue(queue_name, metadata)
+          WAZ::Queues::Queue.new(:name => queue_name, :url => service_instance.generate_request_uri(queue_name))
+        end
+        
+        # Finds a queue by it's name, in case that it isn't found on the current storage account it will 
+        # return nil shilding the user from a ResourceNotFound exception.
+        def find(queue_name)
+          begin 
+            service_instance.get_queue_metadata(queue_name)
+            WAZ::Queues::Queue.new(:name => queue_name, :url => service_instance.generate_request_uri(queue_name))
+          rescue RestClient::ResourceNotFound
+            return nil
+          end
+        end
+        
+        # This method is internally used by this class. It's the way we keep a single instance of the 
+        # service that wraps the calls the Windows Azure Queues API. It's initialized with the values
+        # from the default_connection on WAZ::Storage::Base initialized thru establish_connection!
+        def service_instance
+          @service_instance ||= Service.new(WAZ::Storage::Base.default_connection.merge(:type_of_service => 'queue'))
+        end
+      end
+      
+      attr_accessor :name, :url
+
+      def initialize(options = {})
+        raise WAZ::Storage::InvalidOption, :name unless options.keys.include?(:name)
+        raise WAZ::Storage::InvalidOption, :url unless options.keys.include?(:url)
+        self.name = options[:name]
+        self.url = options[:url]
+      end
+      
+      # Deletes the queue from the current storage account.
+      def destroy!
+        self.class.service_instance.delete_queue(self.name)
+      end
+      
+      # Retrieves the metadata headers associated with the quere.
+      def metadata
+        self.class.service_instance.get_queue_metadata(self.name)
+      end
+      
+      # Sets the metadata given on the new_metadata, when overwrite passed different 
+      # than true it overrides the metadata for the queue  (removing all existing metadata)
+      def put_properties!(new_metadata = {}, overwrite = false)
+        new_metadata.merge!(metadata.reject { |k, v| !k.to_s.start_with? "x_ms_meta"} ) unless overwrite
+        self.class.service_instance.set_queue_metadata(new_metadata)
+      end
+      
+      # Enqueues a message on current queue. message is just a string that should be 
+      # UTF-8 serializable and ttl specifies the time-to-live of the message in the queue 
+      # (in seconds).
+      def enqueue!(message, ttl = 604800)
+        self.class.service_instance.enqueue(self.name, message, ttl)
+      end
+      
+      # Returns the approximated queue size.
+      def size
+        metadata[:x_ms_approximate_messages_count].to_i
+      end
+      
+      # Since Windows Azure Queues implement a Peek-Lock pattern 
+      # the method lock will lock a message preventing other users from 
+      # picking/locking the current message from the queue. 
+      #
+      # The API supports multiple message processing by specifiying num_of_messages (up to 32)
+      # 
+      # The visibility_timeout parameter (optional) specifies for how long the message will be 
+      # hidden from other users.
+      def lock(num_of_messages = 1, visibility_timeout = nil)
+        options = {}
+        options[:num_of_messages] = num_of_messages
+        options[:visiblity_timeout] = visibility_timeout unless visibility_timeout.nil?
+        messages = self.class.service_instance.get_messages(self.name, options).map do |raw_message|
+                    WAZ::Queues::Message.new(raw_message.merge(:queue_name => self.name))
+                  end
+        return messages.first() if num_of_messages == 1
+        return messages
+      end
+      
+      # Returns top N (default 1, up to 32) message from the queue without performing 
+      # any modification on the message. Since the message it's retrieved read-only
+      # users cannot delete the peeked message.
+      def peek(num_of_messages = 1)
+        options = {}
+        options[:num_of_messages] = num_of_messages
+        messages = self.class.service_instance.peek(self.name, options).map do |raw_message|
+                    WAZ::Queues::Message.new(raw_message.merge(:queue_name => self.name))
+                  end
+        return messages.first() if num_of_messages == 1
+        return messages
+      end
+      
+      # Marks every message on the queue for deletion (to be later garbage collected).
+      def clear
+        self.class.service_instance.clear_queue(self.name)
+      end
+    end
+  end
+end

data/lib/waz/queues/service.rb

@@ -0,0 +1,114 @@
+module WAZ
+  module Queues
+    # This is internally used by the waz-queues part of the gem and it exposes the Windows Azure Queue API REST methods 
+    # implementation. You can use this class to perform an specific operation that aren't provided by the current API.
+    class Service
+      include WAZ::Storage::SharedKeyCoreService
+      
+      # Lists the queues on the given storage account.
+      def list_queues(options ={})
+        url = generate_request_uri(nil, :comp => 'list')
+        request = generate_request("GET", url)
+        doc = REXML::Document.new(request.execute())
+        queues = []
+         REXML::XPath.each(doc, '//Queue/') do |item|
+            queues << { :name => REXML::XPath.first(item, "QueueName").text,
+                        :url => REXML::XPath.first(item, "Url").text }
+          end
+        return queues
+      end
+      
+      # Creates a queue on the current storage account. Throws WAZ::Queues::QueueAlreadyExists when 
+      # existing metadata and given metadata differ.
+      def create_queue(queue_name, metadata = {})
+        begin
+          url = generate_request_uri(queue_name)
+          request = generate_request("PUT", url, metadata)
+          request.execute()
+        rescue RestClient::RequestFailed
+          raise WAZ::Queues::QueueAlreadyExists, queue_name if $!.http_code == 409
+        end
+      end
+      
+      # Deletes the given queue from the current storage account.
+      def delete_queue(queue_name)
+        url = generate_request_uri(queue_name)
+        request = generate_request("DELETE", url)
+        request.execute()
+      end
+      
+      # Gets the given queue metadata.
+      def get_queue_metadata(queue_name)
+        url = generate_request_uri(queue_name, :comp => 'metadata')
+        request = generate_request("HEAD", url)
+        request.execute().headers
+      end
+      
+      # Sets the given queue metadata.
+      def set_queue_metadata(queue_name, metadata = {})
+        url = generate_request_uri(queue_name, :comp => 'metadata')
+        request = generate_request("PUT", url, metadata)
+        request.execute()
+      end
+      
+      # Enqueues a message on the current queue.
+      #
+      # ttl Specifies the time-to-live interval for the message, in seconds. The maximum time-to-live allowed is 7 days. If this parameter
+      # is omitted, the default time-to-live is 7 days.
+      def enqueue(queue_name, message_payload, ttl = 604800)
+        url = generate_request_uri("#{queue_name}/messages", "messagettl" => ttl)
+        payload = "<?xml version=\"1.0\" encoding=\"utf-8\"?><QueueMessage><MessageText>#{message_payload}</MessageText></QueueMessage>"
+        request = generate_request("POST", url, { "Content-Type" => "application/xml" }, payload)
+        request.execute()
+      end
+      
+      # Locks N messages (1 default) from the given queue.
+      #
+      # :num_of_messages option specifies the max number of messages to get (maximum 32)
+      #
+      # :visibility_timeout option specifies the timeout of the message locking in seconds (max two hours)
+      def get_messages(queue_name, options = {})
+        raise WAZ::Queues::OptionOutOfRange, {:name => :num_of_messages, :min => 1, :max => 32} if (options.keys.include?(:num_of_messages) && (options[:num_of_messages].to_i < 1 || options[:num_of_messages].to_i > 32))
+        raise WAZ::Queues::OptionOutOfRange, {:name => :visibility_timeout, :min => 1, :max => 7200} if (options.keys.include?(:visibility_timeout) && (options[:visibility_timeout].to_i < 1 || options[:visibility_timeout].to_i > 7200))
+        url = generate_request_uri("#{queue_name}/messages", options)
+        request = generate_request("GET", url)
+        doc = REXML::Document.new(request.execute())
+        messages = []
+        REXML::XPath.each(doc, '//QueueMessage/') do |item|
+          message = { :message_id => REXML::XPath.first(item, "MessageId").text,
+                      :message_text => REXML::XPath.first(item, "MessageText").text,
+                      :expiration_time => Time.httpdate(REXML::XPath.first(item, "ExpirationTime").text),
+                      :insertion_time => Time.httpdate(REXML::XPath.first(item, "InsertionTime").text) }
+
+          # This are only valid when peek-locking messages
+          message[:pop_receipt] = REXML::XPath.first(item, "PopReceipt").text unless REXML::XPath.first(item, "PopReceipt").nil?
+          message[:time_next_visible] = Time.httpdate(REXML::XPath.first(item, "TimeNextVisible").text) unless REXML::XPath.first(item, "TimeNextVisible").nil?
+          messages << message
+        end
+        return messages
+      end
+      
+      # Peeks N messages (default 1) from the given queue.
+      # 
+      # Implementation is the same of get_messages but differs on an additional parameter called :peek_only.
+      def peek(queue_name, options = {})
+        return get_messages(queue_name, {:peek_only => true}.merge(options))
+      end
+      
+      # Deletes the given message from the queue, correlating the operation with the pop_receipt
+      # in order to avoid eventually inconsistent scenarios.
+      def delete_message(queue_name, message_id, pop_receipt)
+        url = generate_request_uri("#{queue_name}/messages/#{message_id}", :pop_receipt => pop_receipt)
+        request = generate_request("DELETE", url)
+        request.execute()
+      end
+      
+      # Marks every message on the given queue for deletion.
+      def clear_queue(queue_name)
+        url = generate_request_uri("#{queue_name}/messages")
+        request = generate_request("DELETE", url)
+        request.execute()
+      end
+    end
+  end
+end

data/lib/waz/storage/base.rb

@@ -0,0 +1,38 @@
+module WAZ
+	module Storage
+    # This class is used to handle a general connection with Windows Azure Storage Account and it 
+    # should be used at least once on the application bootstrap or configuration file.
+    # 
+    # The usage is pretty simple as it's depicted on the following sample
+    #  WAZ::Storage::establish_connection!(:account_name => "my_account_name", 
+    #                                      :access_key => "your_base64_key", 
+    #                                      :use_ssl => false)
+    #
+		class Base
+			class << self
+				# Sets the basic configuration parameters to use the API on the current context
+				# required parameters are :account_name, :access_key. 
+        #
+				# All other parameters are optional.
+				def establish_connection!(options = {})
+					raise InvalidOption, :account_name unless options.keys.include? :account_name
+					raise InvalidOption, :access_key unless options.keys.include? :access_key
+					options[:use_ssl] = false unless options.keys.include? :use_ssl
+					@connection = options
+				end
+				
+				# Returns the default connection (last set) parameters. It will raise an exception WAZ::Storage::NotConnected
+				# when there's no connection information registered.
+				def default_connection
+          raise NotConnected unless connected?
+					return @connection
+				end
+				
+				# Returns a value indicating whether the current connection information has been set or not.
+				def connected?
+					return !@connection.nil?
+				end
+			end
+		end
+	end
+end

data/lib/waz/storage/core_service.rb

@@ -0,0 +1,70 @@
+module WAZ
+  module Storage
+    # This module is imported by the specific services that use Shared Key authentication profile. On the current implementation
+    # this module is imported from WAZ::Queues::Service and WAZ::Blobs::Service.
+    module SharedKeyCoreService
+      attr_accessor :account_name, :access_key, :use_ssl, :base_url
+      
+      # Creates an instance of the implementor service (internally used by the API).
+      def initialize(options = {})
+        self.account_name = options[:account_name]
+        self.access_key = options[:access_key]
+        self.use_ssl = options[:use_ssl] or false
+        self.base_url = "#{options[:type_of_service] or "blobs"}.#{options[:base_url] or "core.windows.net"}"
+      end
+      
+      # Generates a request based on Adam Wiggings' rest-client, including all the required headers
+      # for interacting with Windows Azure Storage API (except for Tables). This methods embeds the 
+      # authorization key signature on the request based on the given access_key.
+      def generate_request(verb, url, headers = {}, payload = nil)
+        http_headers = {}
+        headers.each{ |k, v| http_headers[k.to_s.gsub(/_/, '-')] = v} unless headers.nil?
+        request = RestClient::Request.new(:method => verb.downcase.to_sym, :url => url, :headers => http_headers, :payload => payload)
+        request.headers["x-ms-Date"] = Time.new.httpdate
+        request.headers["Content-Length"] = (request.payload or "").length
+        request.headers["Authorization"] = "SharedKey #{account_name}:#{generate_signature(request)}"
+        return request
+      end
+      
+      # Generates the request uri based on the resource path, the protocol, the account name and the parameters passed
+      # on the options hash. 
+      def generate_request_uri(path = nil, options = {})
+        protocol = use_ssl ? "https" : "http"
+        query_params = options.keys.sort{ |a, b| a.to_s <=> b.to_s}.map{ |k| "#{k.to_s.gsub(/_/, '')}=#{options[k]}"}.join("&") unless options.nil? or options.empty?
+        uri = "#{protocol}://#{account_name}.#{base_url}#{(path or "").start_with?("/") ? "" : "/"}#{(path or "")}"
+        uri << "?#{query_params}" if query_params
+        return uri
+      end
+      
+      # Canonicalizes the request headers by following Microsoft's specification on how those headers have to be sorted 
+      # and which of the given headers apply to be canonicalized.
+      def canonicalize_headers(headers)
+        cannonicalized_headers = headers.keys.select {|h| h.to_s.start_with? 'x-ms'}.map{ |h| "#{h.downcase.strip}:#{headers[h].strip}" }.sort{ |a, b| a <=> b }.join("\x0A")
+        return cannonicalized_headers
+      end
+      
+      # Creates a canonical representation of the message by combining account_name/resource_path.
+      def canonicalize_message(url)
+        uri_component = url.gsub(/https?:\/\/[^\/]+\//i, '').gsub(/\?.*/i, '')
+        comp_component = url.scan(/(comp=[^&]+)/i).first()
+        uri_component << "?#{comp_component}" if comp_component
+        canonicalized_message = "/#{self.account_name}/#{uri_component}"
+        return canonicalized_message
+      end
+      
+      # Generates the signature based on Micosoft specs for the REST API. It includes some special headers, 
+      # the canonicalized header line and the canonical form of the message, all of the joined by \n character. Encoded with 
+      # Base64 and encrypted with SHA256 using the access_key as the seed.
+      def generate_signature(request)
+         signature = request.method.to_s.upcase + "\x0A" +
+                     (request.headers["Content-MD5"] or "") + "\x0A" +
+                     (request.headers["Content-Type"] or "") + "\x0A" +
+                     (request.headers["Date"] or "")+ "\x0A" +
+                     canonicalize_headers(request.headers) + "\x0A" +
+                     canonicalize_message(request.url)
+                     
+         return Base64.encode64(HMAC::SHA256.new(Base64.decode64(self.access_key)).update(signature.toutf8).digest)
+       end
+    end
+  end
+end

data/lib/waz/storage/exceptions.rb

@@ -0,0 +1,25 @@
+module WAZ
+  module Storage
+    # This class is the base exception from where all the exceptions raised from this API 
+    # inherit from. If you want to handle an exception that your code may throw and you don't
+    # know which specific type you should handle, handle this type of exception.
+    class StorageException < StandardError
+    end
+    
+    # This exception raises whenever a required parameter for initializing any class isn't provided. From
+    # WAZ::Storage::Base up to WAZ::Queues::Queue all of them use this exception.
+    class InvalidOption < StorageException
+      def initialize(missing_option)
+        super("You did not provide one of the required parameters. Please provide the #{missing_option}.")
+      end
+    end
+    
+    # This exception is raised when the user tries to perform an operation on any Storage API class
+    # without previously specificying the connection options.
+    class NotConnected < StorageException
+      def initialize
+        super("You should establish connection before using the services, the connection configuration is required.")
+      end
+    end
+  end
+end

data/lib/waz/storage/version.rb

@@ -0,0 +1,11 @@
+module WAZ
+  module Storage
+    module VERSION #:nodoc:
+      MAJOR    = '0'
+      MINOR    = '5'
+      TINY     = '0' 
+    end
+    
+    Version = [VERSION::MAJOR, VERSION::MINOR, VERSION::TINY].compact * '.'
+  end
+end

data/rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'rubygems'
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'lib/waz-storage'
+
+
+namespace :test do
+  Spec::Rake::SpecTask.new('run_with_rcov') do |t|
+    puts "running tests and code coverage"    
+    t.spec_files = FileList['tests/waz/queues/*.rb', 'tests/waz/blobs/*.rb', 'tests/waz/storage/*.rb']
+    t.rcov = true
+    t.rcov_opts = ['--text-report', '--exclude', "exclude.*/.gem,test,Library,#{ENV['GEM_HOME']}", '--sort', 'coverage' ]
+    t.spec_opts = ['-cfn']
+  end
+end
+
+namespace :dist do  
+  spec = Gem::Specification.new do |s|
+    s.name              = 'waz-storage'
+    s.version           = Gem::Version.new(WAZ::Storage::Version)
+    s.summary           = "Client library for Windows Azure's Storage Service REST API"
+    s.description       = "A simple implementation of Windows Azure Storage API for Ruby, inspired by the S3 gems and self experience of dealing with queues. The major goal of the whole gem is to enable ruby developers [like me =)] to leverage Windows Azure Storage features and have another option for cloud storage."
+    s.email             = 'johnny.halife@me.com'
+    s.author            = 'Johnny G. Halife'
+    s.homepage          = 'http://waz-storage.heroku.com'
+    s.require_paths     = ["lib"]
+    s.files             = FileList['rakefile', 'lib/**/*.rb']
+    s.test_files        = Dir['test/**/*']
+    s.has_rdoc          = true
+    s.rdoc_options      << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+    
+    # Dependencies
+    s.add_runtime_dependency 'rest-client', '>= 1.0.3'
+    s.add_dependency 'ruby-hmac'
+  end
+  
+  Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.need_tar = true
+  end
+end
+
+namespace :docs do
+  Rake::RDocTask.new do |t|
+  	t.rdoc_dir = 'rdoc'
+  	t.title    = "Windows Azure Storage library — simple gem for accessing WAZ‘s Storage REST API"
+  	t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+  	t.options << '--charset' << 'utf-8'
+  	t.rdoc_files.include('README.rdoc')
+  	t.rdoc_files.include('lib/**/*.rb')
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: waz-storage
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+platform: ruby
+authors: 
+- Johnny G. Halife
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-15 00:00:00 -03:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ruby-hmac
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A simple implementation of Windows Azure Storage API for Ruby, inspired by the S3 gems and self experience of dealing with queues. The major goal of the whole gem is to enable ruby developers [like me =)] to leverage Windows Azure Storage features and have another option for cloud storage.
+email: johnny.halife@me.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- rakefile
+- lib/waz/blobs/blob_object.rb
+- lib/waz/blobs/container.rb
+- lib/waz/blobs/service.rb
+- lib/waz/queues/exceptions.rb
+- lib/waz/queues/message.rb
+- lib/waz/queues/queue.rb
+- lib/waz/queues/service.rb
+- lib/waz/storage/base.rb
+- lib/waz/storage/core_service.rb
+- lib/waz/storage/exceptions.rb
+- lib/waz/storage/version.rb
+- lib/waz-blobs.rb
+- lib/waz-queues.rb
+- lib/waz-storage.rb
+has_rdoc: true
+homepage: http://waz-storage.heroku.com
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- -A cattr_accessor=object
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Client library for Windows Azure's Storage Service REST API
+test_files: []
+