http_spew 0.1.0 → 0.2.0

data/.gitignore

@@ -6,3 +6,6 @@
 /tmp
 /GIT-VERSION-FILE
 /.manifest
+/lib/http_spew/version.rb
+# http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/
+/Gemfile.lock

data/.manifest

@@ -7,6 +7,7 @@ ChangeLog
 GIT-VERSION-FILE
 GIT-VERSION-GEN
 GNUmakefile
+Gemfile
 LATEST
 LICENSE
 NEWS
@@ -14,20 +15,25 @@ README
 http_spew.gemspec
 lib/http_spew.rb
 lib/http_spew/chunky_pipe.rb
+lib/http_spew/class_methods.rb
 lib/http_spew/content_md5.rb
 lib/http_spew/headers.rb
 lib/http_spew/hit_n_run.rb
 lib/http_spew/input_spray.rb
 lib/http_spew/request.rb
+lib/http_spew/version.rb
 pkg.mk
 setup.rb
 test/content-md5.ru
 test/helper.rb
 test/mirror.ru
+test/response_code.ru
 test/sha1.ru
 test/test_content_md5.rb
 test/test_hit_n_run.rb
 test/test_input_spray.rb
+test/test_input_spray_with_md5.rb
 test/test_mirror.rb
 test/test_request.rb
+test/test_unexpected_response.rb
 test/test_upload.rb

data/ChangeLog

@@ -1,5 +1,308 @@
 ChangeLog from http://bogomips.org/http_spew.git
 
+   commit 84eaf4df3da4ef55e21649b971f2f246ab556b52
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Tue May 10 14:40:53 2011 -0700
+   
+       http_spew 0.2.0 - bugfixes and improvements
+       
+       InputSpray may now be layered on top of ContentMD5 successfully.
+       Improved multi-threading abilities and tests.
+       
+       Do not consider the API remotely stable, yet.
+   
+   commit 02e333f025fb31e3384941c8c890b94394f98c34
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Mon May 9 12:07:14 2011 -0700
+   
+       test: disable rewindable input for Unicorn
+       
+       In most cases, it's a feature we do not want.
+   
+   commit c4b3c9d4231655b053472d47046d5512e55a79a9
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Mon May 9 19:03:27 2011 +0000
+   
+       request: fix bad constant reference
+       
+       Oops :<
+   
+   commit 8849da940687bd6433cf4b18cb4096f6867f3b3e
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Mon May 9 18:32:28 2011 +0000
+   
+       content_md5: switch back to pipe for tee-ability
+       
+       This will save memory bandwidth down the line on Linux
+   
+   commit 8c47ed775e7d40291660354bff29efea3d6f177a
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Sat May 7 02:20:28 2011 +0000
+   
+       content_md5: small garbage reduction
+       
+       Might help somewhere...
+   
+   commit ec0ff47df8c4068da2977cc9cb444caaac17b571
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Sat May 7 01:52:16 2011 +0000
+   
+       improve reliability of input_spray
+       
+       Use pipes to avoid race condidions and deadlocks
+   
+   commit 8157576344b9fcf98e85aafcc958c6ebe385b55b
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Fri May 6 20:38:43 2011 +0000
+   
+       update to kgio 2.4.0
+       
+       Kgio.poll no longer returns EINTR
+   
+   commit af2462a69eae821d6160fd2c2e571a589088977c
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu May 5 16:53:53 2011 -0700
+   
+       chunky_pipe: better error checking
+   
+   commit 58ec2331a74ae472694fddae03f4ff454a801444
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu May 5 16:53:04 2011 -0700
+   
+       test_request: longer timeout for tests
+       
+       This increases reliability, hopefully
+   
+   commit 014cfa31df238a6b7a7e1652442613eed841b757
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed May 4 18:11:22 2011 -0700
+   
+       class_methods: fix race/deadlock issues
+   
+   commit 254b6917d15d4bc013d9ca6889dc802b41592903
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 17:53:14 2011 -0700
+   
+       GNUmakefile: version file is added to gem
+       
+       It's kinda useless otherwise...
+   
+   commit 20fc09850031fb0a26f71ceafd15c93b924582f9
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 17:44:01 2011 -0700
+   
+       content_md5: stop using a pipe + thread
+       
+       Too complex.
+   
+   commit 7ac87f270c2583262ea923960c7cbb8a9b1f2dea
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 17:43:41 2011 -0700
+   
+       test_upload: more robust test case
+       
+       Servers can be super fast.
+   
+   commit 5e7e0553b7b435940afd478b83ebc265f31fdcf3
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 17:43:13 2011 -0700
+   
+       test_upload: fix timeout for seconds
+       
+       HTTP_Spew.wait is now in seconds, not milliseconds
+   
+   commit 33ae61959c657b5c60c2b7d9adb137ad46b24a15
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 16:53:13 2011 -0700
+   
+       request: handle EOF on read properly
+       
+       "eof!" was never a method :x
+   
+   commit f524b02e638cf6ec138f92538cf169edf524326c
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 16:52:34 2011 -0700
+   
+       content_md5: use kgio_write instead of IO#write
+       
+       for consistency, not that we really take advantage
+       of kgio_write at the moment...
+   
+   commit 3dd4f8c357b687bc1bf47785253e84cd7caa4661
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 16:52:07 2011 -0700
+   
+       input_spray: kill needless ivar assignment
+       
+       Nothing references the writer thread.
+   
+   commit b3dc72f3762b737bfc5dbed2d3d296a61879dc09
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 16:51:23 2011 -0700
+   
+       test/helper: use Thread.abort_on_exception = true
+       
+       We want to detect failures during testing and fail hard
+   
+   commit bde96ebe0c31508a4128542fce8753ba5e7403d7
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 16:09:18 2011 -0700
+   
+       remove timed_queue class
+       
+       We don't need it, a mutex is all we need.
+   
+   commit 9e5c03f84e4961d236398d416d526eef8344f98f
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 15:42:53 2011 -0700
+   
+       auto-generate version.rb file based on git version
+       
+       It's helpful for people using in-development versions
+       of the code.
+   
+   commit 6657070f27364688bba503c7e58add6dfe4dd8bf
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 15:34:20 2011 -0700
+   
+       reorganize class methods and exceptions
+       
+       Also none of the exceptions we raise are for programming/user
+       so don't bother generating an expensive backtrace.
+   
+   commit 100c23e10910bb8daff5507fd69f5d951b804672
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 15:12:27 2011 -0700
+   
+       request: support limiting accepted response codes
+       
+       Some apps don't want certain responses and we won't
+       treat that as valid.
+   
+   commit 67e23586d908eeed510508405dcdbee1dc5f9033
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 14:49:06 2011 -0700
+   
+       wait_mt: simplify
+   
+   commit d2e882bdf763319ab149044440fe9bf108d46bc4
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 14:29:26 2011 -0700
+   
+       timed_queue: fix unused variable warning
+   
+   commit 87cb2f5328bc20245a53a8462e6c1324c977189e
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 14:17:20 2011 -0700
+   
+       content_md5: make this a read-only IO-like object
+       
+       It's easier to use this way since we'll also be able
+       to see the Content-MD5 and number of bytes digested.
+   
+   commit 4a3f8cae93d12ebea896227e789d01912a3d55f3
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Apr 20 14:01:39 2011 -0700
+   
+       chunky_pipe: autoclose on EOF
+       
+       Since env["rack.input"] can't reliably be closed any
+       other way.
+   
+   commit 0b6c35740ab1dd0ac64183b9ae0f1a5c710e4022
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu Apr 14 15:19:02 2011 -0700
+   
+       timeouts are in seconds, not milliseconds
+       
+       It's more consistent with other Ruby code.  poll(2)
+       (and epoll(2)) remain exception to that, so the
+       Ruby wrappers for those calls still use milliseconds.
+   
+   commit 9e727f32a6e3506994934b9a48204ffdf0003bca
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu Apr 14 21:56:48 2011 +0000
+   
+       allow combining input_spray + MD5 filter
+       
+       This is required for large parallel uploads.
+   
+   commit 3aa054616bae3184ead01e78d70a707b59f71e63
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu Apr 14 20:59:59 2011 +0000
+   
+       Gemfile: depend on Unicorn 3 for tests
+       
+       We need trailer support
+   
+   commit b35f0d9bcdd3551bcdf2b5285c92197767fde496
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Fri Apr 8 06:15:04 2011 +0000
+   
+       timed_queue: Queue-like class that works with a timeout
+   
+   commit 3db374e644014726092913eee7a4f09d15f6762c
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Tue Apr 5 17:37:54 2011 -0700
+   
+       chunky_pipe: rdoc purpose of this class
+   
+   commit aac364b03306b1ba6ac65c325d946db4b0af02bd
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Tue Apr 5 17:34:01 2011 -0700
+   
+       content_md5: cleaner pack invocation (Ruby 1.9-only)
+       
+       No need to String#strip!
+   
+   commit c78c63adde85f0b329b44484ae652b0acdee4063
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Fri Mar 18 14:23:51 2011 -0700
+   
+       doc: various rdoc updates
+       
+       Forcing myself to relearn my own library
+   
+   commit cfa6c6b329ae44ae4f30a590d45e5df4c2d14d9a
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu Mar 17 14:44:06 2011 -0700
+   
+       tests: cleanup shadow warnings under 1.9.2
+   
+   commit 1216ec9fc829c8c65f0f8ae2376138b90a1083d3
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Thu Mar 17 21:19:54 2011 +0000
+   
+       pkg.mk: new task for checking Ruby warnings
+   
+   commit efcb08f789d60ebec26eadaada9af09593fedb9b
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Mar 16 01:11:05 2011 +0000
+   
+       remove needless assignments
+       
+       More noise
+   
+   commit 6ce8e006a94a852ed76ffeababa1cac2ed7889c0
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Mar 16 01:06:22 2011 +0000
+   
+       content_md5: improve readability
+   
+   commit 61c1164c39886a198d33697c14c9abf099e3e08f
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Wed Mar 16 00:31:25 2011 +0000
+   
+       use bundler
+   
+   commit 2318ee6a732f71d38a7749c0663bf780135be49c
+   Author: Eric Wong <normalperson@yhbt.net>
+   Date:   Mon Feb 28 04:27:26 2011 +0000
+   
+       gemspec: bump kcar version
+       
+       Newer is better
+   
    commit 32223af63dc5296cd09f2472ad60263d98f379a2
    Author: Eric Wong <normalperson@yhbt.net>
    Date:   Thu Feb 24 08:28:34 2011 +0000

data/GIT-VERSION-FILE

@@ -1 +1 @@
-GIT_VERSION = 0.1.0
+GIT_VERSION = 0.2.0

data/GIT-VERSION-GEN

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 GVF=GIT-VERSION-FILE
-DEF_VER=v0.1.0.GIT
+DEF_VER=v0.2.0.GIT
 
 LF='
 '

data/GNUmakefile

@@ -2,4 +2,15 @@ all::
 RSYNC_DEST := bogomips.org:/srv/bogomips/http_spew
 rfproject := rainbows
 rfpackage := http_spew
+
+RUBY_VERSION_FILE = lib/http_spew/version.rb
+pkg_extra += $(RUBY_VERSION_FILE)
 include pkg.mk
+
+$(RUBY_VERSION_FILE): GIT-VERSION-FILE
+	@$(RM) -f $@+
+	@echo >> $@+ '# -*- encoding: binary -*-'
+	@echo >> $@+ 'HTTP_Spew.const_set :VERSION, "$(GIT_VERSION)"'
+	@mv $@+ $@
+
+build: $(RUBY_VERSION_FILE)

data/Gemfile

@@ -0,0 +1,5 @@
+source(ENV["GEM_SOURCE"] || :rubygems)
+gem 'rack', '~> 1.2'
+gem 'kgio', '~> 2.4'
+gem 'kcar', '~> 0.2'
+gem 'unicorn', '~> 3' # not many servers offer HTTP Trailer handling

data/LATEST

@@ -1,4 +1,7 @@
-=== HTTP spew 0.1.0 - initial release / 2011-02-24 08:50 UTC
+=== http_spew 0.2.0 - bugfixes and improvements / 2011-05-10 22:19 UTC
 
-  Might as well...
+  InputSpray may now be layered on top of ContentMD5 successfully.
+  Improved multi-threading abilities and tests.
+
+  Do not consider the API remotely stable, yet.
 

data/NEWS

@@ -1,3 +1,10 @@
+=== http_spew 0.2.0 - bugfixes and improvements / 2011-05-10 22:19 UTC
+
+  InputSpray may now be layered on top of ContentMD5 successfully.
+  Improved multi-threading abilities and tests.
+
+  Do not consider the API remotely stable, yet.
+
 === HTTP spew 0.1.0 - initial release / 2011-02-24 08:50 UTC
 
   Might as well...

data/http_spew.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = rdoc_options
   s.rubyforge_project = %q{rainbows}
   s.test_files = Dir["test/test_*.rb"]
-  s.add_dependency(%q<kcar>, "~> 0.1.2")
-  s.add_dependency(%q<kgio>, "~> 2.3")
+  s.add_dependency(%q<kcar>, "~> 0.2")
+  s.add_dependency(%q<kgio>, "~> 2.4")
   s.add_development_dependency(%q<wrongdoc>, "~> 1.5")
 end

data/lib/http_spew/chunky_pipe.rb

@@ -1,12 +1,26 @@
 # -*- encoding: binary -*-
 #
-# HTTP Spew blows chunks (at HTTP servers)!
+# This is a OS-level pipe that overrides IO#read to provide
+# IO#readpartial-like semantics while remaining Rack::Lint-compatible
+# for EOF, meaning we return nil on EOF instead of raising EOFError.
 class HTTP_Spew::ChunkyPipe < Kgio::Pipe
+
+  # other threads may force an error to be raised in the +read+
+  # method
   attr_accessor :error
 
-  # makes read behave like readpartial without EOFError
+  # Override IO#read to behave like IO#readpartial, but still return +nil+
+  # on EOF instead of raising EOFError.
   def read(*args)
-    defined?(@error) and raise @error
-    kgio_read(*args)
+    check_err!
+    kgio_read(*args) || check_err! || close
+  end
+
+  def check_err!
+    if defined?(@error)
+      closed? or close
+      raise @error
+    end
+    nil
   end
 end

data/lib/http_spew/class_methods.rb

@@ -0,0 +1,125 @@
+require "thread"
+require "io/wait"
+
+module HTTP_Spew::ClassMethods
+  def error_all(requests, error) # :nodoc:
+    requests.each { |req| req.error ||= error }
+  end
+
+  def done_early(ready, failed, requests) # :nodoc:
+    ready.concat(failed)
+    pending = requests - ready
+    unless pending.empty?
+      error = HTTP_Spew::ConnectionReset.new("prematurely terminated")
+      ready.concat(error_all(pending, error))
+    end
+    ready.uniq!
+    ready
+  end
+
+  # Returns an array of requests that are complete, including those
+  # that have errored out.  Incomplete requests remain in +requests+
+  # If +need+ is fullfilled, it closes all incomplete requests and
+  # returns all requests.
+  def wait_nonblock!(need, requests)
+    ready, failed = [], []
+    requests.delete_if do |req|
+      begin
+        case req.resume
+        when Symbol # :wait_writable, :wait_readable
+          false
+        else
+          (ready << req).size == need and
+            return done_early(ready, failed, requests)
+          true
+        end
+      rescue => e
+        req.error = e
+        failed << req
+      end
+    end
+    ready.concat(failed).empty? ? nil : ready
+  end
+
+  def with_timeout(t)
+    t0 = Time.now
+    yield
+    ensure
+      t[0] -= Time.now - t0
+      t[0] = 0.0 if t[0] < 0
+  end
+
+  # Returns an array of requests that are complete, including those
+  # that have errored out.
+  # If +need+ is fullfilled, it closes all incomplete requests.
+  def wait_mt(need, requests, timeout)
+    ready, failed = [], []
+    r, w = Kgio::Pipe.new
+    active = []
+    t = [ timeout ]
+    requests.each_with_index do |req, i|
+      active << Thread.new do
+        begin
+          rv = req.run(timeout)
+          w.write([ i ].pack("v"))
+          rv
+        rescue => err
+          err
+        end
+      end
+    end
+    begin
+      with_timeout(t) { r.wait(t[0]) }
+      req_idx = r.read(2).unpack("v")[0]
+      thr = active[req_idx]
+      with_timeout(t) { thr.join(t[0]) }
+      rv = thr.value
+      (Array === rv ? ready : failed) << requests[req_idx]
+      ready.size == need and return done_early(ready, failed, requests)
+    end until t[0] < 0.0 || (ready.size + failed.size) == requests.size
+
+    ready.concat(failed)
+    pending = requests - ready
+    error = HTTP_Spew::TimeoutError.new("request timed out")
+    ready.concat(error_all(pending, error))
+    ensure
+      w.close
+      r.close
+  end
+
+  def wait(need, requests, timeout)
+    ready, failed = [], []
+    pollset = {}
+    t = [ timeout ]
+    begin
+      requests.each do |req|
+        begin
+          case rv = req.resume
+          when Symbol # :wait_writable, :wait_readable
+            pollset[req] = rv
+          else
+            (ready << req).size == need and
+              return done_early(ready, failed, requests)
+            pollset.delete(req)
+          end
+        rescue => e
+          req.error = e
+          failed << req
+          pollset.delete(req)
+        end
+      end
+      break if pollset.empty?
+
+      busy = pollset.keys
+      rv = with_timeout(t) { Kgio.poll(pollset, (t[0] * 1000).to_i) } or break
+    end while t[0] > 0.0 && requests = rv.keys.concat(busy).uniq!
+
+    ready.concat(failed)
+    unless requests.empty?
+      error = HTTP_Spew::TimeoutError.new("request timed out")
+      ready.concat(error_all(requests, error))
+      ready.uniq!
+    end
+    ready
+  end
+end

data/lib/http_spew/content_md5.rb

@@ -1,52 +1,62 @@
 # -*- encoding: binary -*-
 require "digest/md5"
-module HTTP_Spew::ContentMD5
-  class MismatchError < HTTP_Spew::Error
-  end
-  class LengthError < HTTP_Spew::Error
-  end
 
-  def self.input(env)
+# this uses a pipe internally so it can use IO.tee in the "io_splice" RubyGem
+class HTTP_Spew::ContentMD5
+  attr_reader :to_io
+  attr_reader :content_md5
+  attr_reader :bytes_digested
+
+  CRLF = "\r\n" # :nodoc:
+
+  def initialize(env)
     if trailer = env["HTTP_TRAILER"]
-      have_md5 = trailer.split(/\s*,\s*/).grep(/\AContent-MD5\z/i)[0]
-      return env["rack.input"] if have_md5 && env["HTTP_CONTENT_MD5"]
-    end
-    if trailer
-      unless have_md5
+      unless trailer.split(/\s*,\s*/).grep(/\AContent-MD5\z/i)[0]
         trailer << (trailer.empty? ? "Content-MD5" : ",Content-MD5")
       end
     else
       env["HTTP_TRAILER"] = "Content-MD5"
     end
     env["HTTP_TRANSFER_ENCODING"] = "chunked"
-    rd, wr = HTTP_Spew::ChunkyPipe.new
-    md5 = env.delete("HTTP_CONTENT_MD5")
-    len = env.delete("CONTENT_LENGTH")
-    start_write_driver(env["rack.input"], rd, wr, md5, len)
-    rd
+    @to_io, wr = HTTP_Spew::ChunkyPipe.new
+    expect_md5 = env.delete("HTTP_CONTENT_MD5")
+    expect_len = env.delete("CONTENT_LENGTH")
+    start_write_driver(env["rack.input"], wr, expect_md5, expect_len)
+  end
+
+  # compatible with IO#read and Rack::InputWrapper#read
+  def read(length, buffer = "")
+    # calls HTTP_Spew::ChunkyPipe#read
+    @to_io.read(length, buffer)
   end
 
-  def self.start_write_driver(input, rd, wr, expect_md5, expect_len)
+  def start_write_driver(input, wr, expect_md5, expect_len) # :nodoc:
     Thread.new do
       begin
-        digest, buf, bytes = Digest::MD5.new, "", 0
+        digest = Digest::MD5.new
+        buf = ""
+        bytes = 0
         while input.read(0x4000, buf)
           n = buf.size
           bytes += n
-          wr.kgio_write("#{n.to_s(16)}\r\n")
+          wr.write("#{n.to_s(16)}\r\n")
           digest.update(buf)
-          wr.kgio_write(buf << "\r\n")
+          wr.write(buf << CRLF)
         end
         if expect_len && expect_len.to_i != bytes
-          raise LengthError, "expect=#{expect_len} != got=#{bytes}"
+          raise HTTP_Spew::LengthError,
+               "expect=#{expect_len} != got=#{bytes}", []
         end
-        digest = [ digest.digest ].pack("m").strip!
-        if expect_md5 && expect_md5.strip != digest
-          raise MismatchError, "expect=#{expect_md5} != got=#{digest}"
+        md5 = [ digest.digest ].pack("m0")
+        if expect_md5 && expect_md5.strip != md5
+          raise HTTP_Spew::ChecksumError,
+                "expect=#{expect_md5} != got=#{md5}", []
         end
-        wr.write "0\r\nContent-MD5: #{digest}\r\n\r\n"
+        wr.write "0\r\nContent-MD5: #{md5}\r\n\r\n"
+        @content_md5 = md5
+        @bytes_digested = bytes
       rescue => e
-        rd.error = e
+        @to_io.error = e
       ensure
         wr.close
       end

data/lib/http_spew/headers.rb

@@ -10,12 +10,23 @@ module HTTP_Spew::Headers
   CONTENT_TYPE = "CONTENT_TYPE" # specified by Rack to be !/^HTTP_/
   # :startdoc:
 
+  # regenerates the request_uri from a Rack +env+
   def request_uri(env)
     qs = env[QUERY_STRING]
     qs.size == 0 ? env[PATH_INFO] : "#{env[PATH_INFO]}?#{qs}"
   end
   module_function :request_uri
 
+  # converts a Rack +env+ into an HTTP header buffer
+  # If +input+ is a string, this appends +input+ to the header
+  # buffer so the client can avoid extra writes.  If input is
+  # an IO-like object, it is returned as the second element
+  # of an array.
+  #
+  # This, the following code always works and may be used to clobber
+  # +input+ if it is merged into +buf+
+  #
+  #   buf, input = env_to_headers(env, input)
   def env_to_headers(env, input)
     req = "#{env[REQUEST_METHOD]} " \
           "#{env[REQUEST_URI] || request_uri(env)} HTTP/1.1\r\n" \