rbkb-http 0.2.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/History.txt

@@ -0,0 +1,4 @@
+== 0.2.0 / 2009-10-06
+  * split off rbkb/http from rbkb core.
+  * added MultiPartFormParams support and TextPlainFormParams
+  * added request body parameter interfaces to rbkb/http

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2009 Eric Monti
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,18 @@
+= rbkb-http
+
+HTTP protocol addons for the Ruby BlackBag (rbkb-http)
+
+* http://github.com/emonti/rbkb-http
+
+== DESCRIPTION
+
+This library various includes HTTP protocol tools and libraries based on and 
+complementary to the Ruby BlackBag library.
+
+== REQUIREMENTS
+
+* ruby blackbag (rbkb) - http://emonti.github.com/rbkb
+
+== Copyright
+
+Copyright (c) 2009 Eric Monti. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rbkb-http"
+    gem.summary = %Q{HTTP protocol add-ons for Ruby BlackBag}
+    gem.description = %Q{HTTP libraries and tools based on and complementary to Ruby BlackBag}
+    gem.email = "emonti@matasano.com"
+    gem.homepage = "http://github.com/emonti/rbkb-http"
+    gem.authors = ["Eric Monti"]
+    gem.add_development_dependency "rspec"
+    gem.add_dependency "rbkb"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask' 
+Rake::TestTask.new(:test) do |test| 
+  test.libs << 'lib' << 'test' 
+  test.pattern = 'test/**/test_*.rb' 
+  test.verbose = true 
+end 
+
+#require 'spec/rake/spectask'
+#Spec::Rake::SpecTask.new(:spec) do |spec|
+#  spec.libs << 'lib' << 'spec'
+#  spec.spec_files = FileList['spec/**/*_spec.rb']
+#end
+#
+#Spec::Rake::SpecTask.new(:rcov) do |spec|
+#  spec.libs << 'lib' << 'spec'
+#  spec.pattern = 'spec/**/*_spec.rb'
+#  spec.rcov = true
+#end
+
+#task :spec => :check_dependencies
+
+#task :default => :spec
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rbkb-http #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/rbkb/http/base.rb

@@ -0,0 +1,179 @@
+module Rbkb::Http
+
+  # A base class containing some common features for Request and Response 
+  # objects.
+  #
+  # Don't use this class directly, it's intended for being overridden
+  # from its derived classes or mixins.
+  class Base
+    include CommonInterface
+
+    def self.parse(*args)
+      new(*args)
+    end
+
+    # Initializes a new Base object
+    def initialize(*args)
+      _common_init(*args)
+    end
+
+    # This method parses just HTTP message body. Expects body to be split
+    # from the headers before-hand.
+    def capture_body(bstr)
+      self.body ||= default_body_obj
+      @body.capture(bstr)
+    end
+
+    # XXX stub
+    def first_entity
+      @first_entity
+    end
+
+    # XXX stub
+    def first_entity=(f)
+      @first_entity=(f)
+    end
+
+    # This method parses only HTTP response headers. Expects headers to be 
+    # split from the body before-hand.
+    def capture_headers(hstr)
+      self.headers ||= default_headers_obj
+
+      if @body and not @body.capture_complete?
+        return 
+      elsif @headers.capture_complete?
+        self.first_entity, @headers = default_headers_obj.capture_full_headers(hstr)
+      else 
+        @headers.capture(hstr)
+      end
+    end
+
+    # This method returns the content length from Headers. This is
+    # mostly useful if you are using a BoundBody object for the body.
+    # 
+    # Returns nil if no "Content-Length" is not found.
+    #
+    # The opts parameter :ignore_content_length affects this method and 
+    # will cause it always to return nil. This is useful, for example,
+    # for the responses to the HTTP HEAD request method, which return
+    # a Content-Length without actual content.
+    #
+    def content_length(hdrs=@headers)
+      raise "headers is nil?" if not hdrs
+      if( (not @opts[:ignore_content_length]) and 
+          hdrs.get_header_value("Content-Length").to_s =~ /^(\d+)$/ )
+
+        $1.to_i
+      end
+    end
+
+    def content_type(hdrs=@headers)
+      raise "headers is nil?" if not hdrs
+      if ctype=hdrs.get_header_value("Content-Type")
+        ctype.split(/\s*;\s*/).first
+      end
+    end
+    
+    def attach_new_header(hdr_obj=nil)
+      self.headers = hdr_obj
+      return hdr_obj
+    end
+
+    def attach_new_body(body_obj=nil)
+      self.body = body_obj
+      return body_obj
+    end
+
+    # XXX doc override!
+    def default_headers_obj(*args)
+      Header.new(*args)
+    end
+
+    # XXX doc override!
+    def default_body_obj(*args)
+      Body.new(*args)
+    end
+
+    # This method will non-destructively reset the capture state on this 
+    # object and all child entities. Note, however, If child entities are not 
+    # defined, it may instantiate new ones. 
+    # See also: capture_complete?, reset_capture!
+    def reset_capture
+      if @headers
+        @headers.reset_capture if not @headers.capture_complete?
+      else
+        attach_new_header()
+      end
+
+      if @body
+        @body.reset_capture if not @body.capture_complete? 
+      else
+        attach_new_body()
+      end
+      @capture_state = nil
+      self
+    end
+
+    # This method will destructively reset the capture state on this object.
+    # It does so by initializing fresh child entities and discarding the old
+    # ones. See also: capture_complete?, reset_capture
+    def reset_capture!
+      attach_new_header()
+      attach_new_body()
+      @capture_state = nil
+      self
+    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?
+      if( (@headers and not @headers.capture_complete?) or
+          (@body and not @body.capture_complete?) )
+        return false
+      else
+        true
+      end
+    end
+
+    attr_reader :body, :headers
+
+    # This accessor will attempt to always do the "right thing" while
+    # setting this object's body entity. 
+    #
+    # See also: default_body_obj
+    def body=(b)
+      if @body
+        @body.data = b
+      elsif b.kind_of? Body
+        @body = b.dup
+        @body.opts = b.opts
+      else
+        @body = default_body_obj(b)
+      end
+      @body.base = self
+      return @body
+    end
+
+    # This accessor will attempt to always do the "right thing" while
+    # setting this object's headers entity. 
+    #
+    # See also: default_headers_obj
+    def headers=(h)
+      if @headers
+        @headers.data = h
+      elsif h.kind_of? Headers
+        @headers = h.dup
+        @headers.opts = h.opts
+      else
+        @headers = default_headers_obj(h)
+      end
+      @headers.base = self
+      return @body
+    end
+
+  end
+
+
+end
+

data/lib/rbkb/http/body.rb

@@ -0,0 +1,220 @@
+require 'stringio'
+
+module Rbkb::Http
+  class Body < String
+    include CommonInterface
+
+    def self.parse(str)
+      new().capture(str)
+    end
+
+    attr_reader :expect_length
+
+    def initialize(str=nil, opts=nil)
+      self.opts = opts
+      if Body === str
+        self.replace(str)
+        @opts = str.opts.merge(@opts)
+      elsif String === str 
+        super(str)
+      else
+        super()
+      end
+
+      yield(self) if block_given?
+    end
+
+    # The capture method is used when parsing HTTP requests/responses.
+    # This can and probably should be overridden in derived classes.
+    def capture(str)
+      yield(str) if block_given?
+      self.data=(str)
+    end
+
+    # The to_raw method is used when writing HTTP requests/responses.
+    # This can and probably should be overridden in derived classes.
+    def to_raw
+      (block_given?) ? yield(self.data) : self.data
+    end
+
+    attr_reader :base
+
+    def base=(b)
+      if b.nil? or b.is_a? Base
+        @base = b
+      else
+        raise "base must be a Response or Request object or nil" 
+      end
+    end
+
+    def data
+      self
+    end
+
+    # Sets internal raw string data without any HTTP decoration.
+    def data=(str)
+      self.replace(str.to_s)
+    end
+
+    # Returns the content length from the HTTP base object if
+    # there is one and content-length is available.
+    def get_content_length
+      @base.content_length if @base
+    end
+    alias content_length get_content_length
+
+    def get_content_type
+      @base.content_type if @base
+    end
+    alias content_type get_content_type
+    
+    # This method will non-destructively reset the capture state on this object.
+    # It is non-destructive in that it will not affect existing captured data 
+    # if present.
+    def reset_capture
+      @expect_length = nil
+      @base.reset_capture() if @base and @base.capture_complete?
+    end
+
+    # This method will destructively reset the capture state on this object.
+    # This method is destructive in that it will clear any previously captured
+    # data.
+    def reset_capture!
+      reset_capture()
+      self.data=""
+    end
+
+    def capture_complete?
+      not @expect_length
+    end
+  end
+
+
+  # BoundBody is designed for handling an HTTP body when using the usual
+  # "Content-Length: NNN" HTTP header.
+  class BoundBody < Body
+
+    # This method may throw :expect_length with one of the following values
+    # to indicate certain content-length conditions:
+    #
+    #   > 0 :   Got incomplete data in this capture. The object expects
+    #           capture to be called again with more body data.
+    #
+    #   < 0 :   Got more data than expected, the caller should truncate and 
+    #           handle the extra data in some way. Note: Calling capture again
+    #           on this instance will start a fresh body capture.
+    #
+    # Caller can also detect the above conditions by checking the expect_length 
+    # attribute but should still be prepared handle the throw().
+    #
+    #  0/nil:  Got exactly what was expected. Caller can proceed with fresh
+    #          captures on this or other Body objects.
+    #
+    # See also reset_capture and reset_capture!
+    def capture(str)
+      raise "arg 0 must be a string" unless String === str
+
+      # Start fresh unless we're expecting more data
+      self.data="" unless @expect_length and @expect_length > 0
+
+      if not clen=get_content_length()
+        raise "content-length is unknown. aborting capture"
+      else
+        @expect_length = clen - (self.size + str.size)
+        self << str[0, clen - self.size]
+        if @expect_length > 0
+          throw(:expect_length, @expect_length)
+        elsif @expect_length < 0
+          throw(:expect_length, @expect_length)
+        else
+          reset_capture()
+        end
+      end
+      return self
+    end
+
+    def to_raw(*args)
+      if @base
+        @base.headers.set_header("Content-Length", self.size)
+      end
+      super(*args)
+    end
+  end
+
+
+  # ChunkedBody is designed for handling an HTTP body when using a
+  # "Transfer-Encoding: chunked" HTTP header.
+  class ChunkedBody < Body
+    DEFAULT_CHUNK_SIZE = 2048
+
+    # Throws :expect_length with 'true' when given incomplete data and expects 
+    # to be called again with more body data to parse. 
+    #
+    # The caller can also detect this condition by checking the expect_length 
+    # attribute but must still handle the throw().
+    #
+    # See also reset_capture and reset_capture!
+    def capture(str)
+      # chunked encoding is gross...
+      if @expect_length
+        sio = StringIO.new(@last_chunk.to_s + str)
+      else
+        sio = StringIO.new(str)
+        self.data=""
+      end
+      @last_chunk = nil
+
+      @expect_length = true
+      while not sio.eof?
+        unless m=/^([a-fA-F0-9]+)\s*(;[[:print:]\s]*)?\r?\n$/.match(line=sio.readline)
+          raise "invalid chunk at #{line.chomp.inspect}"
+        end
+        if (chunksz = m[1].hex) == 0
+          @expect_length = false
+          # XXX ignore Trailer headers
+          break
+        end
+
+        if ( (not sio.eof?) and 
+             (chunk=sio.read(chunksz)) and 
+             chunk.size == chunksz and 
+             (not sio.eof?) and (extra = sio.readline) and
+             (not sio.eof?) and (extra << sio.readline)
+           )
+          if extra =~ /^\r?\n\r?\n$/
+            yield(chunk) if block_given?
+            self << chunk
+          else
+            raise "expected CRLF"
+          end
+        else
+          @last_chunk = line + chunk.to_s + extra.to_s
+          break
+        end
+      end
+      throw(:expect_length, @expect_length) if @expect_length
+      return self
+    end
+
+
+    def to_raw(csz=nil)
+      csz ||= (@opts[:output_chunk_size] || DEFAULT_CHUNK_SIZE)
+      unless csz.kind_of? Integer and csz > 0
+        raise "chunk size must be an integer >= 1"
+      end
+
+      out=[]
+      i=0
+      while i <= self.size
+        chunk = self[i, csz]
+        out << "#{chunk.size.to_s(16)}\r\n#{chunk}\r\n\r\n"
+        yield(self, out.last) if block_given?
+        i+=csz
+      end
+      out << "0\r\n"
+      yield(self, out.last) if block_given?
+      return out.join
+    end
+  end
+end
+

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