ruby-atmos 0.6.0

data/lib/atmos/exceptions.rb

@@ -0,0 +1,28 @@
+module Atmos
+   module Exceptions
+
+      class AtmosException < Exception
+      end
+   
+      class ArgumentException < AtmosException
+      end
+
+      class AuthException < AtmosException
+      end
+   
+      class InvalidStateException < AtmosException
+      end
+   
+      class NoSuchObjectException < AtmosException
+      end
+   
+      class ServerException < AtmosException
+      end
+
+      class NotImplementedException < AtmosException
+      end
+   
+      class InternalLibraryException < AtmosException
+      end
+   end
+end

data/lib/atmos/object.rb

@@ -0,0 +1,263 @@
+module Atmos
+
+   #
+   # == Object
+   # This class represents an object in an Atmos store.
+   #
+   # === Object Data
+   # When an object is instantiated, it's data is not loaded
+   # due to memory considerations. You can access an object's
+   # data as a ruby String or as a progressive download via a block.
+   #
+   # ==== all at once
+   #
+   #   obj.data
+   #
+   # ==== progressive download
+   #
+   #   obj.data_as_stream do |chunk|
+   #      datafile.write(chunk)
+   #   end
+   #
+   # ==== partial data
+   #
+   #   obj.data_as_stream(0...59) do |chunk|
+   #      readin.concat(chunk)
+   #   end
+   #
+   #
+   # === System Metadata
+   # Each object has some information about it stored by the system.
+   # This information is read only, and available as a hash on the object:
+   #
+   #  obj.system_metadata => Hash
+   #
+   #  obj.system_metadata.each do |key,value|
+   #    puts "#{key}=#{value}"
+   #  end
+   #
+   # See Atmos::Metadata for more detailed information.
+   #
+   #
+   # === User Metadata
+   # There are two kinds of user metadata, listable and non-listable.
+   # Each of these is available as a hash
+   # on the object class.  These can both be modified.
+   #
+   #  obj.listable_metadata => Hash
+   #
+   #  obj.listable_metadata.each do |key,value|
+   #    puts "#{key}=#{value}"
+   #  end
+   #
+   #  obj.metadata => Hash
+   #
+   #  obj.metadata.each do |key,value|
+   #    puts "#{key}=#{value}"
+   #  end
+   #
+   # See Atmos::Metadata for more detailed information.
+   #
+   #
+   # === Access Control Lists (ACLs)
+   #
+   # There are two hashes for access control available as properties
+   # on the object: +user_acl+ and +group_acl+.  
+   # The keys are the Atmos usernames and the values are one of
+   # <tt>:none</tt>, <tt>:read</tt>, <tt>:write</tt>, <tt>:full</tt>.
+   #
+   #    puts obj.user_acl.inspect => {user => :full}
+   #    puts obj.group_acl.inspect => {other => :none}
+   #
+   # See Atmos::ACL for more detailed information.
+   #
+   #
+   class Object
+      attr_reader :aoid, :request, :user # :nodoc:
+      
+      # Hash-like object containing user access control properties of the object.
+      attr_reader :user_acl
+
+      # Hash-like object containing group access control properties of the object.
+      attr_reader :group_acl
+
+      # Hash-like object containing non-listable metadata associated with the object.
+      attr_reader :metadata
+
+      # Hash-like object containing listable metadata associated with the object.
+      attr_reader :listable_metadata
+
+      # Hash-like object containing read-only system metadata associated with the object.
+      attr_reader :system_metadata
+      
+      @request    = nil
+      @checksum   = nil
+    
+    
+      #
+      # This constructor is only meant for internal use.  Get or create an object
+      # with an Atmos::Store object:
+      #
+      #    obj = store.create
+      #    obj = store.get(obj_id)
+      #
+      def initialize(store, aoid, options = {})
+         Atmos::LOG.debug("obj.new options: #{options.inspect}")   
+         validate_options(options)
+
+         @deleted    = false
+         @aoid       = aoid
+         @store      = store
+         @request    = Atmos::Request.new(:store => @store)
+         @user       = @store.user
+
+         # this means we're creating a new object, 
+         # not representing an existing one
+         if (@aoid.nil?)
+            response = @request.do(:create_object, options)
+            @aoid = response.id
+         end
+
+         @system_metadata   = Atmos::Metadata.new(self, Atmos::Metadata::SYSTEM)
+
+         # These guys need the object to have a valid id, so we do it after the create
+         @user_acl          = Atmos::ACL.new(self, Atmos::ACL::USER)
+         @group_acl         = Atmos::ACL.new(self, Atmos::ACL::GROUP)
+         @metadata          = Atmos::Metadata.new(self, Atmos::Metadata::NON_LISTABLE)
+         @listable_metadata = Atmos::Metadata.new(self, Atmos::Metadata::LISTABLE)
+      end
+      
+      
+      #
+      # Truncates the object to size 0 without changing any of the Metadata or ACLs.
+      #
+      def truncate
+         do_delete_check
+         response = @request.do(:trunc_object, :id => @aoid, :data => nil, :length => 0)
+      end
+      
+      #
+      # Deletes the object from Atmos and invalidates the object.
+      #
+      #    obj = store.create
+      #    obj.delete
+      #
+      def delete
+         do_delete_check
+         response = @request.do(:delete_object, :id => @aoid)
+         @deleted = true
+      end
+      
+      
+      #
+      # Returns all the object data in a single string.  Be judicious about
+      # use of this method, since it can load the entire blob into memory.
+      #
+      # Optional:
+      # * <tt>:range</tt> - range of bytes to retrieve (e.g. 0...10000)
+      #
+      def data(range = nil)
+         do_delete_check
+         response = @request.do(:read_object, :id => @aoid, 'Range' => range)
+         response.http_response.body
+      end
+      
+      
+      #
+      # Allows progressive download of the object's data.  Takes a block:
+      #
+      #   obj.data_as_stream do |chunk|
+      #      datafile.write(chunk)
+      #   end
+      #
+      # Optional:
+      # * <tt>:range</tt> - range of bytes to retrieve (e.g. 0...10000)
+      #
+      def data_as_stream(range = nil, &block)
+         do_delete_check
+         @request.do(:read_object, :id => @aoid, 'Range' => range) do |response|
+            response.read_body do |chunk| 
+               block.call(chunk)
+            end
+         end
+      end
+      
+      
+      def update(data, range=nil)    
+         response = @request.do(:update_object, :id => @aoid, :data => data, 'Range' => range)
+      end
+    
+    
+      #
+      # Checks to see if the represented object exists on Atmos
+      # by requesting it's system metadata.  
+      #
+      # Returns boolean +true+ or +false+.
+      #
+      def exists?
+         rv = true
+         begin
+            @request.do(:list_system_metadata, :id => @aoid)
+         rescue Atmos::Exceptions::NoSuchObjectException
+            rv = false
+         end
+         rv
+      end
+    
+    
+      def copy #:nodoc:
+         do_delete_check
+      end
+
+
+      def headers #:nodoc:
+         do_delete_check
+         headers = {}
+         [@user_acl, @group_acl, @tags, @listable_tags, @metadata, @listable_metadata].each do |attr|
+            val = attr.header_value
+            next if (val.nil? || val.empty?)
+            headers[attr.header_name] = attr.header_value
+         end
+         headers
+      end
+      
+      
+      private
+         def do_delete_check
+            raise Atmos::Exceptions::InvalidStateException if (@deleted)
+         end
+         
+         def validate_options(options)
+            invalid_values = []
+
+            valid_options = [:checksum, :user_acl, :group_acl, :metadata, :listable_metadata, :mimetype, :length, :data].freeze
+            invalid_options = options.keys - valid_options
+            raise Atmos::Exceptions::ArgumentException, "Unrecognized options: #{invalid_options.inspect}" if (!invalid_options.empty?)
+            
+            options.each do |k,v|
+               case k
+               when :checksum
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Boolean))
+               when :user_acl
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Hash))
+               when :group_acl
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Hash))
+               when  :metadata
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Hash))
+               when  :listable_metadata
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Hash))
+               when  :mimetype
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(String))
+               when  :length 
+                  invalid_values.push(k) if (options[k].nil? || !options[k].kind_of?(Integer))
+               when  :data
+                  invalid_values.push(k) if (options[k].nil? || (!options[k].kind_of?(String) && !options[k].class.ancestors.include?(IO)))
+               end
+            end
+
+            raise Atmos::Exceptions::ArgumentException, "Options of invalid type: #{invalid_values.inspect}" if (!invalid_values.empty?)
+         end
+
+  end
+  
+end 

data/lib/atmos/parser.rb

@@ -0,0 +1,110 @@
+module Atmos
+   class Parser
+      
+      NOKOGIRI   = "nokogiri"
+      REXML      = "rexml"
+      @@parser   = nil
+
+   
+      def self.parser
+         @@parser
+      end
+      
+      
+      def self.parser=(which)
+         
+         @@parser = which
+         if (@@parser == NOKOGIRI)
+            require 'nokogiri'
+         elsif (@@parser == REXML)
+            require 'rexml/document'
+         else
+            raise Atmos::Exceptions::ArgumentException, "The XML parser has not been set to a known parser."
+         end
+      end
+      
+      
+      def self.response_get_array(response, string)
+         rv = nil
+         
+         if (parser == NOKOGIRI)
+            
+            doc = Nokogiri::XML(response.body)
+            rv  = doc.xpath(string).map do |elt|
+               elt.content
+            end
+        
+         elsif (parser == REXML)
+
+            doc = ::REXML::Document.new(response.body)
+            rv  = doc.elements.to_a(string).map do |elt|
+               elt.text
+            end
+            
+         end
+
+         rv
+      end
+      
+
+      def self.response_get_string(response, string)
+         response_get_array(response,string)[0]
+      end
+      
+      
+      #
+      # Utility method to check the atmos server XML response for errors.
+      # Throws exception on error.
+      #
+      def self.response_check_action_error(action, response)
+         doc     = nil
+         code    = nil
+         msg     = nil
+         exclass = Atmos::Exceptions::AtmosException
+         
+         Atmos::LOG.info("body: #{response.body}")
+         if (!response.body.nil? && response.body.match(/<\?xml/))
+            if (parser == NOKOGIRI)
+            
+               doc  = Nokogiri::XML(response.body)
+            
+               code = doc.xpath('//Error/Code')[0]  
+               code = code.content if (!code.nil?)
+            
+               msg  = doc.xpath('//Error/Message')[0]
+               msg  = msg.content if (!msg.nil?)
+                               
+            elsif (parser == REXML)
+           
+               code = response_get_string(response, '//Error/Code')
+               msg  = response_get_string(response, '//Error/Message')
+
+            else
+               raise Atmos::Exceptions::InvalidStateException, "The XML parser has not been set to a known parser."
+            end
+         end
+         
+         if (!code.nil?)
+            
+            Atmos::LOG.info("code: #{code}")
+            Atmos::LOG.info("msg: #{msg}")
+
+            if (!REST[action][:errors].nil? && !REST[action][:errors][code].nil?)
+               tmp = REST[action][:errors][code][:message]
+               msg = tmp if (!tmp.nil?)
+
+               tmp = REST[action][:errors][code][:class]
+               exclass = tmp if (!tmp.nil?)
+            end
+                        
+            raise exclass, msg
+            
+         end
+         
+         true
+      end
+
+
+
+   end
+end 

data/lib/atmos/request.rb

@@ -0,0 +1,188 @@
+module Atmos
+      class Request # :nodoc:
+      
+      def initialize(options = {})
+         valid = [:store, :default_tag].freeze
+         invalid = options.keys - valid
+         raise Atmos::Exceptions::ArgumentException,
+               "Unrecognized options: #{invalid.inspect}" if (!invalid.empty?)
+         Atmos::LOG.debug("Request.initialize: options: #{options.inspect}")
+      
+         @baseurl = options[:store].uri
+         @uid     = options[:store].uid
+         @secret  = options[:store].secret
+         @http    = options[:store].http
+         @tag     = options[:default_tag]
+      end
+
+      
+      def do(actionname, options = {}, &block)
+         verbs = [:head, :get, :put, :post, :delete].freeze
+         Atmos::LOG.info("do #{actionname} options: #{options.inspect}")
+         raise Atmos::Exceptions::InternalLibraryException,
+               "Invalid REST action: #{actionname}" if (REST[actionname].nil?)
+         
+         action  = REST[actionname]
+         uri     = (options[:id].nil?) ? action[:uri] : action[:uri].sub(/:id/, options[:id])         
+         url     = URI::join(@baseurl.to_s, uri.to_s)
+         verb    = action[:verb]         
+         
+         if (options[:id].nil? && !action[:uri].index(':id').nil?)
+            raise Atmos::Exceptions::ArgumentException, "An id is required for this action (#{actionname})."
+         end
+
+         request = (verbs.include?(verb)) ? Net::HTTP.const_get(verb.to_s.capitalize).new(uri) : nil
+         raise Atmos::Exceptions::AtmosException,
+               "Couldn't create Net::HTTP request object for #{verb}" if (request.nil?)
+         
+         headers = {}
+         headers['Date'] = Time.now().httpdate()
+         headers['x-emc-date'] = Time.now().httpdate()
+         headers['x-emc-uid'] = @uid
+
+         if (!action[:required_headers].nil?)
+            action[:required_headers].each do |header|
+               case header
+               when 'Content-Type' then
+                  headers[header] = (!options[:mimetype].nil?) ? options[:mimetype] : 'binary/octet-stream'
+               when 'Content-Length' then
+                  headers[header] = (!options[:length].nil?) ? options[:length] : 0
+               when 'x-emc-tags' then
+                  headers[header] = (!options[header].nil?) ? options[header] : ""
+               else
+                  if (options[header])                  
+                     headers[header] = options[header]
+                  else
+                     raise "Value not supplied for required header: '#{header}'"
+                  end
+               end
+            end
+         end
+         
+         if (!action[:optional_headers].nil?)
+            action[:optional_headers].each do |header|
+               if (header.eql?('Range') && options.has_key?('Range') && !options['Range'].nil?)
+                  r = options['Range']
+                  options.delete('Range')
+                  #headers[header] = (r.kind_of?(Range)) ? "Bytes=#{r.first}-#{r.last}" : "Bytes=#{r.to_s}"
+                  if (r.kind_of?(Range)) 
+                     headers[header] = "Bytes=#{r.first}-#{r.last}"
+                     Atmos::LOG.info("Request.initialize: given Range object: #{headers[header]}")
+                  else 
+                     Atmos::LOG.info("Request.initialize: given range string: #{headers[header]}")
+                     headers[header] =  "Bytes=#{r.to_s}"
+                  end
+                  if ((!options[:data].nil?) and ((r.end-r.begin+1) != options[:data].length))
+                     raise Atmos::Exceptions::ArgumentException, "The range length (#{r.end - r.begin + 1}) doesn't match the data length (#{options[:data].length})."
+                  end
+               end
+               key = (action[:header2sym] && action[:header2sym][header]) ? action[:header2sym][header] : header
+                  
+               if (!options[key].nil?)
+                  if (options[key].kind_of?(Hash))
+                     headers[header] = ""
+                     options[key].each do |key,val|
+                        headers[header] += "#{key}=#{val}, "
+                     end
+                     headers[header].chop!
+                     headers[header].chop!
+                  elsif (options[key].kind_of?(Array))
+                     headers[header] = ""
+                     options[key].each do |val|
+                        headers[header] += "#{val}, "
+                     end
+                     headers[header].chop!
+                     headers[header].chop!
+                  elsif (options[key].respond_to?(:to_s))
+                     headers[header] = options[key]
+                  else
+                     raise "value for optional header '#{header}' id bad type: #{options[header].class}"
+                  end
+               end
+            end
+         end
+
+         if (!@tag.nil? && !action[:optional_headers].nil? && action[:optional_headers].include?('x-emc-listable-meta'))
+            if (headers.has_key?('x-emc-listable-meta'))
+               headers['x-emc-listable-meta'] += ", #{@tag}=atmos-ruby-default"
+            else 
+               headers['x-emc-listable-meta'] = "#{@tag}=atmos-ruby-default"
+            end
+         end
+
+         headers['x-emc-signature'] = calculate_signature(action[:verb], @secret, url, headers)
+         
+         if (options[:data])
+            Atmos::LOG.info("there is data: [#{options[:data]}]")
+            if (options[:data].respond_to?(:read))
+               request.body_stream = options[:data]         
+            else
+               request.body = options[:data]
+            end
+            headers['Content-Length'] = 
+               options[:data].respond_to?(:lstat) ? options[:data].stat.size : options[:data].size  
+            Atmos::LOG.info("set Content-Length to: #{headers['Content-Length']}\n")
+
+         end
+         
+         headers.each do |key,val|
+            request[key] = val
+         end
+                  
+        @http.set_debug_output($stdout) if (Atmos::LOG.level == Log4r::DEBUG)
+
+         
+         #
+         # so this is weird.  because some of these atmos request may be
+         # insanely long, we need to allow a mechanism for our API layer
+         # to read progressively, not only all at once
+         #
+         if (block)
+            @http.request(request) do |response|
+               block.call(response)
+            end
+            return
+         end
+         
+         response = @http.request(request)
+         Atmos::Parser::response_check_action_error(actionname, response)
+         
+         Atmos::Response.new(response, actionname)
+      end
+
+      
+      def calculate_signature(verb, secret, url, headers)        
+        headers_copy = headers.clone
+
+        # normalize emc headers
+        headers_copy.each do |header, value|
+           if (header.start_with?('x-emc-'))
+              headers.delete(header)
+              headers[header.to_s.strip.downcase] = value.to_s.strip.sub(/\s+/, ' ').sub(/\n/, '')
+           end
+        end
+      
+        # string together all emc headers, no newline at end
+        emc = ""
+        headers.keys.sort.each do |header|
+           if (header.start_with?('x-emc-'))
+              emc += "#{header}:#{headers[header]}\n"
+           end
+        end
+        emc.chomp!
+        
+        hashstring = verb.to_s.upcase+"\n"
+        ['Content-Type', 'Range', 'Date'].each do |key|
+           hashstring += headers[key] if (!headers[key].nil?)
+           hashstring += "\n"
+        end
+               
+        hashstring += url.path
+        hashstring += '?'+url.query if (!url.query.nil?)
+        hashstring += "\n"+ emc
+                               
+        Atmos::LOG.debug("calculate_signature: hashstring: #{hashstring}")
+        Base64.encode64(HMAC::SHA1.digest(Base64.decode64(secret), hashstring)).chomp()
+     end
+  end
+end