emonti-rbkb 0.6.2.1 → 0.6.6

data/lib/rbkb/http/common.rb

@@ -0,0 +1,74 @@
+module Rbkb::Http
+  DEFAULT_HTTP_VERSION = "HTTP/1.1"
+
+  module CommonInterface
+    # This provides a common method for use in 'initialize' to slurp in 
+    # opts parameters and optionally capture a raw blob. This method also 
+    # accepts a block to which it yields 'self'
+    def _common_init(raw=nil, opts=nil)
+      self.opts = opts
+      yield self if block_given?
+      capture(raw) if raw
+      return self
+    end
+
+    # Implements a common interface for an opts hash which is stored internally
+    # as the class variable @opts.
+    #
+    # The opts hash is designed to contain various named values for 
+    # configuration, etc. The values and names are determined entirely
+    # by the class that uses it.
+    def opts
+      @opts
+    end
+
+    # Implements a common interface for setting a new opts hash containing
+    # various named values for configuration, etc. This also performs a 
+    # minimal sanity check to ensure the object is a Hash.
+    def opts=(o=nil)
+      raise "opts must be a hash" unless (o ||= {}).is_a? Hash
+      @opts = o
+    end
+  end
+
+
+  # A generic cheat for an Array of named value pairs to pretend to 
+  # be like Hash when using [] and []=
+  class NamedValueArray < Array
+
+    # Act like a hash with named values. Return the named value if a string
+    # or Symbol is supplied as the index argument.
+    #
+    # Note, this doesn't do any magic with String / Symbol conversion.
+    def [](*args)
+      if args.size == 1 and (String === args[0] or Symbol === args[0])
+        if h=find {|x| x[0] == args[0]}
+          return h[1]
+        end
+      else
+        super(*args)
+      end
+    end
+
+    # Act like a hash with named values. Set the named value if a String
+    # or Symbol is supplied as the index argument.
+    #
+    # Note, this doesn't do any magic with String / Symbol conversion.
+    def []=(*args)
+      if args.size > 1 and (String === args[0] or Symbol === args[0])
+        if h=find {|x| x[0] == args[0]}
+          h[1] = args[1]
+        else
+          self << args[0,2]
+        end
+      else
+        super(*args)
+      end
+    end
+
+    def delete_key(key)
+      delete_if {|x| x[0] == key }
+    end
+  end
+
+end

data/lib/rbkb/http/headers.rb

@@ -0,0 +1,356 @@
+require 'uri'
+
+module Rbkb::Http
+
+  # A base class for RequestHeaders and ResponseHeaders
+  #
+  # Includes common implementations of to_raw, to_raw_array, capture, and
+  # the class method parse
+  #
+  # The Headers array are stored internally as an named value pairs array.
+  #
+  # The headers are generally name/value pairs in the form of:
+  #
+  #   [  ["Name1", "value1"], ["Name2", "value2"], ...  ]
+  #
+  # Which will be rendered with to_raw() to (or captured with capture() from):
+  #
+  #   Name1: value1
+  #   Name2: value2
+  #   ...
+  #
+  # This has the benefit of letting the data= accessor automatically render a 
+  # Hash or any other Enumerable to a Headers object through the use of to_a.
+  # However it has the caveat that named pairs are expected on various 
+  # operations.
+  class Headers < Array
+    include CommonInterface
+
+    # Class method to instantiate a new RequestHeaders object
+    def self.request_hdr(*args)
+      Headers.new(*args).extend(RequestHeaders)
+    end
+
+    # Class method to instantiate a new ResponseHeaders object
+    def self.response_hdr(*args)
+      Headers.new(*args).extend(ResponseHeaders)
+    end
+
+    # Instantiates a new Headers object and returns the result of capture(str)
+    # Note, this method does not distinguish between ResponseHeaders or
+    # RequestHeaders, and so the object may need to be extended with one
+    # or the other, if you need access to specific behviors from either.
+    def self.parse(str)
+      new().capture(str)
+    end
+
+    # Instantiates a new Headers object and returns the result of 
+    # capture_full_headers(str, first_obj)
+    def self.parse_full_headers(str, first_obj)
+      new().capture_full_headers(str, first_obj)
+    end
+
+    # Instantiates a new Headers object. 
+    #
+    # Arguments:
+    #   raw:  String or Enumerable. Strings are parsed with capture. 
+    #         Enumerables are converted with 'to_a' and stored directly.
+    #
+    #   opts: Options which affect the behavior of the Headers object.
+    #         (none currently defined)
+    #
+    def initialize(*args)
+      super()
+      if args.first.kind_of? Enumerable
+        raw=args.first
+        args[0]=nil
+        _common_init(*args)
+        self.data = raw.to_a
+      else
+        _common_init(*args)
+      end
+    end
+
+    attr_reader :base
+
+    # Conditionally sets the @base class variable if it is a kind of Base
+    # object.
+    def base=(b)
+      if b.nil? or b.kind_of? Base
+        @base = b
+      else
+        raise "base must be a kind of Base object or nil" 
+      end
+    end
+
+    # The data method provides a common interface to access internal
+    # non-raw information stored in the object.
+    #
+    # The Headers incarnation returns the internal headers array 
+    # (actually self).
+    def data
+      self
+    end
+
+    # The data= method provides a common interface to access internal
+    # non-raw information stored in the object.
+    #
+    # This method stores creates a shallow copy for anything but another 
+    # Headers object which it references directly. A few rules are enforced:
+    #   * 1-dimensional elements will be expanded to tuples with 'nil' as the 
+    #     second value. 
+    #
+    #   * Names which are enumerables will be 'join()'ed, but not values.
+    def data=(d)
+      if d.kind_of? Headers
+        self.replace d
+      else
+        self.replace []
+        d.to_a.each do |k, v| 
+          k = k.to_s if k.is_a? Numeric
+          self << [k,v]
+        end
+      end
+      return self
+    end
+
+    # The to_raw_array method returns an interim formatted array of raw 
+    # "Cookie: Value" strings.
+    def to_raw_array
+      self.map {|h,v| "#{h}: #{v}" }
+    end
+
+    def get_header(k)
+      self.select {|h| h[0].downcase == k.downcase }
+    end
+
+    def get_header_value(k)
+      get_header(k).map {|h| h[1]}
+    end
+    
+    def delete_header(k)
+      self.delete_if {|h| h[0].downcase == k.downcase }
+    end
+    
+    def set_header(k,v)
+      sel = get_header(k)
+
+      if sel.empty?
+        self << [k,v]
+        return [[k,v]]
+      else
+        sel.each {|h| h[1] = v }
+        return sel
+      end
+    end
+
+    # The to_raw method returns a raw string of headers as they appear
+    # on the wire.
+    def to_raw
+      to_raw_array.join("\r\n") << "\r\n"
+    end
+
+    # Captures a raw string of headers into this instance's internal array.
+    # Note: This method expects not to include the first element such as a
+    # RequestAction or ResponseStatus. See capture_full_headers for a version
+    # that can handle this.
+    def capture(str)
+
+      raise "arg 0 must be a string" unless str.is_a?(String)
+      heads = str.split(/\s*\r?\n/)
+
+      # pass interim parsed headers to a block if given
+      yield(self, heads) if block_given?
+
+      self.replace [] if capture_complete? 
+      heads.each do |s| 
+        k,v = s.split(/\s*:\s*/, 2) 
+        self << [k,v]
+      end
+      return self
+    end
+
+    # See capture_full_headers. This method is used to resolve the parser
+    # for the first entity above the HTTP headers. This instance is designed
+    # to raise an exception when capturing.
+    def get_first_obj; raise "get_first_obj called on base stub"; end
+
+    # This method parses a full set of raw headers from the 'str' argument. 
+    # Unlike the regular capture method, the string is expected to start
+    # with a line which will be parsed by first_obj using its own capture 
+    # method. For example, first_obj would parse something like 
+    # "GET / HTTP/1.1" for RequestAction or "HTTP/1.1 200 OK" for 
+    # ResponseStatus. If first_obj is not defined, there will be an attempt 
+    # to resolve it by calling get_first_obj which should return the 
+    # appropriate type of object or raise an exception.
+    #
+    # Returns a 2 element array containing [first_entity, headers]
+    # where first entity is the instantiated first_obj object and headers
+    # is self.
+    def capture_full_headers(str, first_obj=nil)
+      first_obj ||= get_first_obj() {|x|}
+
+      first = nil
+      capture(str) do |this, heads|
+        first = first_obj.capture(heads.shift)
+        yield(heads) if block_given?
+      end
+      return [first, self]
+    end
+
+    # This method will non-destructively reset the capture state on this object.
+    # The existing headers are maintained when this is called.
+    # See also: capture_complete? reset_capture!
+    def reset_capture
+      @capture_state = nil
+      self
+    end
+
+    # This method will destructively reset the capture state on this object.
+    # The existing headers array is emptied when this is called.
+    # See also: capture_complete?, reset_capture
+    def reset_capture!
+      @capture_state = nil
+      self.data = []
+    end
+
+    # Indicates whether this object is ready to capture fresh data, or is
+    # waiting for additional data or a reset from a previous incomplete or 
+    # otherwise broken capture. See also: reset_capture, reset_capture!
+    def capture_complete?
+      not @capture_state
+    end
+  end
+
+
+  # A mixin for HTTP Request headers to add specific request header
+  # behaviors and features.
+  #
+  # To instantiate a new request header, use Headers.request_hdr
+  module RequestHeaders
+    # This method is used to resolve the parser for the first entity above the 
+    # HTTP headers. The incarnation for ResponseHeaders returns ResponseStatus
+    # See Headers.capture_full_headers for more information.
+    def get_first_obj(*args)
+      RequestAction.new(*args)
+    end
+  end
+
+
+  # A mixin for HTTP Response headers to add specific response header
+  # behaviors and features.
+  #
+  # To instantiate a new response header, use Headers.response_hdr
+  module ResponseHeaders
+
+    # This method is used to resolve the parser for the first entity above the 
+    # HTTP headers. The incarnation for ResponseHeaders returns ResponseStatus
+    # See Headers.capture_full_headers for more information.
+    def get_first_obj(*args)
+      ResponseStatus.new(*args)
+    end
+  end
+
+
+  # A class for HTTP request actions, i.e. the first 
+  # header sent in an HTTP request, as in "GET / HTTP/1.1"
+  class RequestAction
+    include CommonInterface
+
+    def self.parse(str)
+      new().capture(str)
+    end
+
+    attr_accessor :verb, :uri, :version
+
+    def initialize(*args)
+      _common_init(*args)
+      @verb ||= "GET"
+      @uri ||= URI.parse("/")
+      @version ||= "HTTP/1.1"
+    end
+
+    def to_raw
+      ary = [ @verb, @uri ]
+      ary << @version if @version
+      ary.join(" ")
+    end
+
+    # This method parses a request action String into the current instance.
+    def capture(str)
+      raise "arg 0 must be a string" unless str.is_a?(String)
+      unless m=/^([^\s]+)\s+([^\s]+)(?:\s+([^\s]+))?\s*$/.match(str)
+        raise "invalid action #{str.inspect}"
+      end
+      @verb = m[1]
+      @uri = URI.parse m[2]
+      @version = m[3]
+      return self
+    end
+
+    # Returns the URI path as a String if defined
+    def path
+      @uri.path if @uri
+    end
+
+    # Returns the URI query as a String if it is defined
+    def query
+      @uri.query if @uri
+    end
+
+    # Returns the URI query parameters as a FormUrlencodedParams object if 
+    # the query string is defined.
+    # XXX note parameters cannot currently be modified in this form.
+    def parameters
+      FormUrlencodedParams.parse(query) if query
+    end
+
+    attr_reader :base
+
+    def base=(b)
+      raise "base must be a kind of Base object" if not b.is_a? Base
+      @base = b
+    end
+  end
+
+
+  # A class for HTTP response status messages, i.e. the first 
+  # header returned by a server, as in "HTTP/1.0 200 OK"
+  class ResponseStatus
+    include CommonInterface
+
+    def self.parse(str)
+      new().capture(str)
+    end
+
+    attr_accessor :version, :code, :text
+
+    def initialize(*args)
+      _common_init(*args)
+      @version ||= DEFAULT_HTTP_VERSION
+    end
+
+    def to_raw
+      [@version, @code, @text].join(" ")
+    end
+
+    def capture(str)
+      raise "arg 0 must be a string" unless str.is_a?(String)
+      unless m=/^([^\s]+)\s+(\d+)(?:\s+(.*))?$/.match(str)
+        raise "invalid status #{str.inspect}"
+      end
+      @version = m[1]
+      @code = m[2] =~ /^\d+$/ ? m[2].to_i : m[2]
+      @text = m[3]
+      return self
+    end
+
+    attr_reader :base
+
+    def base=(b)
+      raise "base must be a kind of Base object" if not b.is_a? Base
+      @base = b
+    end
+  end
+end
+

data/lib/rbkb/http/parameters.rb

@@ -0,0 +1,101 @@
+module Rbkb::Http
+
+  # The Parameters class is for handling named parameter values. This is a
+  # stub base class from which to derive specific parameter parsers such as:
+  #
+  #   FormUrlencodedParams for request query string parameters and POST 
+  #   content using application/www-form-urlencoded format.
+  #
+  #   MultiPartFormParams for POST content using multipart/form-data
+  class Parameters < Array
+    include CommonInterface
+
+    def self.parse(str)
+      new().capture(str)
+    end
+
+    def initialize(*args)
+      _common_init(*args)
+    end
+    
+    def get_all(k)
+      self.select {|p| p[0] == k}
+    end
+
+    def get_param(k)
+      self.find {|p| p[0] == k}
+    end
+
+    def get_value_for(k)
+      if v=self.get(k)
+        return v[1]
+      end
+    end
+
+    def get_all_values_for(k)
+      self.get_all(k).map {|p,v| v }
+    end
+
+    def set_param(k, v)
+      if p=self.get_param(k)
+        p[1]=v
+      else
+        p << 
+      end
+      return v
+    end
+
+    def set_all_for(k, v)
+      sel=self.get_all(k)
+      if sel.empty?
+        self << [k,v]
+        return [[k,v]]
+      else
+        sel.each {|p| p[1] = v}
+        return sel
+      end
+    end
+
+    def delete_param(k)
+      self.delete_if {|p| p[0] == k }
+    end
+  end
+
+  # The FormUrlencodedParams class is for Parameters values in the 
+  # form of 'q=foo&l=1&z=baz' as found in GET query strings and
+  # application/www-form-urlencoded or application/x-url-encoded POST 
+  # contents.
+  class FormUrlencodedParams < Parameters
+    def to_raw
+      self.map {|k,v| "#{k}=#{v}"}.join('&')
+    end
+
+    def capture(str)
+      raise "arg 0 must be a string" unless String === str
+      str.split('&').each do |p| 
+        var,val = p.split('=',2)
+        self << [var,val]
+      end
+      return self
+    end
+  end
+
+
+  # The MultipartFormParams class is for Parameters in POST data when using
+  # the multipart/form-data content type. This is often used for file uploads.
+  class MultipartFormParams < Parameters
+    def to_raw
+      self.map {|k,v| "#{k}=#{v}"}.join('&')
+    end
+
+    def capture(str)
+      raise "arg 0 must be a string" unless String === str
+      str.split('&').each do |p| 
+        var,val = p.split('=',2)
+        self << [var,val]
+      end
+      return self
+    end
+  end
+end
+