rbkb-http 0.2.0

data/lib/rbkb/http/headers.rb

@@ -0,0 +1,406 @@
+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_all(k)
+      self.select {|h| h[0].downcase == k.downcase }
+    end
+
+    def get_all_values_for(k)
+      self.get_all(k).collect {|h,v| v }
+    end
+    alias all_values_for get_all_values_for
+
+    def get_header(k)
+      self.find {|h| h[0].downcase == k.downcase }
+    end
+
+    def get_value_for(k)
+      if h=self.get_header(k)
+        return h[1]
+      end
+    end
+    alias get_header_value get_value_for
+    alias value_for get_value_for
+
+    # returns a header value after "fully" parsing it. Any semi-colon separated 
+    # key=value or key parameters after the first value in the header will be 
+    # returned as an extra HeaderParams array in addition to the value. T
+    #
+    # XXX NOTE, the current implementation will incorrectly parse several headers
+    # that may legally contain ';' with no special meaning. 
+    # For example, 'Referer: http://example.com;sometimes_a_url_parameter=1'
+    def get_parameterized_value(k)
+      if v=get_value_for(k)
+        if i=v.index(';')
+          val = v[0,i]
+          parms = v[(i+1)..-1]
+          [ val, HeaderParams.parse( parms ) ]
+        else
+          [ v, HeaderParams.new ]
+        end
+      end
+    end
+    alias parameterized_value get_parameterized_value
+
+
+    def set_parameterized_value(k, v)
+      raise "v is not an array. use set_header()" unless v.kind_of? Array
+      parms = v[1]
+      v = v[0].to_s
+      v << parms.to_raw if parms
+      set_header(k,v)
+    end
+
+
+    def set_header(k,v)
+      sel = get_all(k)
+
+      if sel.empty?
+        self << [k,v]
+        return [[k,v]]
+      else
+        sel.each {|h| h[1] = v }
+        return sel
+      end
+    end
+    alias set_all_for set_header
+
+
+    def delete_header(k)
+      self.delete_if {|h| h[0].downcase == k.downcase }
+    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
+    NO_PARAMETERS = ["Referer", "Host"]
+
+    # 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,220 @@
+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_all_values_for(k)
+      self.get_all(k).collect {|p,v| v }
+    end
+    alias all_values_for get_all_values_for
+
+    def get_param(k)
+      self.find {|p| p[0] == k}
+    end
+
+    def get_value_for(k)
+      if p=self.get_param(k)
+        return p[1]
+      end
+    end
+    alias get_param_value get_value_for
+    alias value_for get_value_for
+
+    def set_param(k, v)
+      if p=self.get_param(k)
+        p[1]=v
+      else
+        p << [k,v]
+      end
+      return [[k,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
+
+  class HeaderParams < Parameters
+    def to_raw(quote_val=false)
+      ret = ([nil] + self).map do |k,v| 
+        if v 
+          "#{k}=#{quote_val ? "\"#{v}\"" : v}"
+        else 
+          "#{k}" 
+        end
+      end.join("; ")
+    end
+    
+    def capture(str)
+      raise "arg 0 must be a string" unless str.is_a? String
+      str.split(/\s*;\s*/).each do |p|
+        var, val = p.split('=', 2)
+        if val =~ /^(['"])(.*)\1$/
+          val = $2
+        end
+        self << [var.strip, val]
+      end
+      return self
+    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(url_enc=false)
+      self.map do |k,v|
+        if url_enc
+          k = k.urlenc
+          v = v.urlenc
+        end
+        if v
+          "#{k}=#{v}" 
+        else 
+          "#{k}"
+        end
+      end.join('&')
+    end
+
+    def capture(str, url_dec=false)
+      raise "arg 0 must be a string" unless str.is_a? String
+      str.split('&').each do |p| 
+        k,v = p.split('=',2)
+        if url_dec
+          k = k.urldec
+          v = v.urldec
+        end
+        self << [k, v]
+      end
+      return self
+    end
+  end
+
+  # The TextPlainParams class is for Parameters values in the 
+  # form of 'text/plain' post data. These are usually simple key=value 
+  # pairs separated by a CR?LF. 
+  #
+  # XXX Note, safari seems to think these should be urlencoded, and not
+  # newline separated. joy!
+  class TextPlainFormParams < Parameters
+    def to_raw
+      self.map do |k,v| 
+        if v
+          "#{k}=#{v.urlenc}" 
+        else 
+          "#{k}"
+        end
+      end.join('\r\n')
+    end
+
+    def capture(str)
+      raise "arg 0 must be a string" unless str.is_a? String
+      str.split(/\r?\n/).each do |p| 
+        var,val = p.split('=',2)
+        self << [var,val]
+      end
+      return self
+    end
+  end
+
+  require 'strscan'
+  
+  # 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
+    attr_accessor :boundary, :part_headers
+
+    # You must specify a boundary somehow when instantiating a new MultipartFormParams
+    # object. The
+    def initialize(*args)
+      _common_init(*args) do |this|
+        yield this if block_given?
+        this.boundary ||=
+          ( this.opts[:boundary] || rand(0xffffffffffffffff).to_s(16).rjust(48,'-') )
+      end
+    end
+    
+    def to_raw
+      ret = ""
+      self.each_with_index do |p,i|
+        name, value = p 
+        ret << "--#{boundary.to_s}\n"
+        hdrs = @part_headers[i]
+        if cd = hdrs.get_parameterized_value("Content-Disposition")
+          v, parms = cd
+          parms.set_value_for("name", name) if name
+          hdrs.set_parameterized_value("Content-Disposition", v, parms)
+        else
+          hdrs.set_value_for("Content-Disposition", "form-data; name=#{name}")
+        end
+
+        ret << hdrs.to_raw
+        ret << "#{value}\n"
+      end
+      ret << "#{boundary}--"
+
+    end
+
+    def capture(str)
+      raise "arg 0 must be a string" unless String === str
+      @part_headers = []
+      self.replace([])
+      
+      s = StringScanner.new(str)
+      bound = /\-\-#{Regexp.escape(@boundary)}\r?\n/
+      unless start=s.scan_until(bound) and start.index(@boundary)==2
+        raise "unexpected start data #{start.inspect}"
+      end
+      
+      while chunk = s.scan_until(bound)
+        part = chunk[0,chunk.index(bound)].chomp
+        phdr, body = part.split(/^\r?\n/, 2)
+        head=Headers.parse(phdr)
+        x, parms = head.get_parameterized_value('Content-Disposition')
+        if parms and name=parms.get_value_for("name")
+          @part_headers << head
+          self << [name, body]
+        else
+          raise "invalid chunk at #{s.pos} bytes"
+        end
+      end
+      unless str[s.pos..-1] =~ /^\-\-#{Regexp.escape(@boundary)}--(?:\r?\n|$)/
+        raise "expected boundary terminator at #{s.pos}"
+      end
+      return self
+    end
+  end
+end
+

data/lib/rbkb/http/request.rb

@@ -0,0 +1,76 @@
+module Rbkb::Http
+
+  # A Request encapsulates all the entities in a HTTP request message
+  # including the action header, general headers, and body.
+  class Request < Base
+    attr_accessor :action
+
+    alias first_entity action
+    alias first_entity= action=
+
+    def action_parameters
+      @action.parameters
+    end
+    
+    def body_parameters
+      ctype, ct_parms = @headers.get_parameterized_value('Content-Type')
+      case ctype
+      when /^application\/(?:x-)?(?:www-form-url|url-)encoded(?:\W|$)/
+        FormUrlencodedParams.new(@body)
+      when /^multipart\/form-data$/
+        MultipartFormParams.new(@body, :boundary => ct_parms.get_value_for('boundary'))
+      when /^text\/plain$/
+        # safari just gives us url-encoded parameters for text/plain.
+        # Joy!
+        if @headers.get_value_for('User-Agent') =~ /\WSafari\W/
+          FormUrlencodedParams.new(@body)
+        else
+          TextPlainFormParams.new(@body)
+        end
+      end
+    end
+
+    # Returns a new Headers object extended as RequestHeaders. This is the 
+    # default object which will be used when composing fresh Request header
+    # entities.
+    def default_headers_obj(*args)
+      Headers.new(*args).extend(RequestHeaders)
+    end
+
+    # Returns a new BoundBody object. This is the default object which will 
+    # be used when composing fresh Request body entities.
+    def default_body_obj(*args)
+      Body.new(*args)
+    end
+
+    # Returns a raw HTTP request for this instance. The instance must have 
+    # an action element defined at the bare minimum.
+    def to_raw(tmp_body=@body)
+      raise "this request has no action entity" unless first_entity()
+      self.headers ||= default_headers_obj()
+      self.body ||= default_body_obj()
+
+      if len=@opts[:static_length]
+        @body = Body.new(@body, @body.opts) {|x| x.base = self}
+        @headers.set_header("Content-Length", len.to_i)
+      elsif @opts[:ignore_content_length]
+        @headers.delete_header("Content-Length")
+      end
+
+      bstr = tmp_body.to_raw
+      hdrs = (@headers).to_raw_array.unshift(first_entity.to_raw)
+      return "#{hdrs.join("\r\n")}\r\n\r\n#{bstr}"
+    end
+
+
+    # Parses a raw HTTP request and captures data into the current instance.
+    def capture(str)
+      raise "arg 0 must be a string" unless String === str
+      hstr, bstr = str.split(/\s*\r?\n\r?\n/, 2)
+      capture_headers(hstr)
+      self.body = content_length ? BoundBody.new : Body.new
+      capture_body(bstr)
+      return self
+    end
+  end
+end