README

   1 = kcar - bytestream to Rack response converter
   2
   3 kcar features an HTTP parser that will convert a bytestream into a
   4 3-element array suitable for use as a Rack response.  It is IO interface
   5 agnostic, so it may be used with HTTP streams over Unix domain sockets,
   6 regular files, FIFOs, StringIOs as well as traditional TCP sockets.
   7
   8 A drop-in, Net::HTTP-compatible interface is planned.
   9
  10 == Features
  11
  12 * RFC2616-compliant Ragel+C parser adapted from Unicorn and Mongrel
  13
  14 * decodes chunked response bodies with an optional pass-through mode
  15   (to avoid rechunking with Rack::Chunked)
  16
  17 * handles odd things like trailers and multiline headers
  18
  19 * streaming interface for response bodies allows for incremental
  20   processing of arbitrarily large responses.
  21
  22 * suppported under Ruby 1.8, 1.9 and Rubinuus
  23
  24 == Problems
  25
  26 * kcar is only lightly tested and is not yet aware of all quirks found in
  27   all real (possibly broken) web servers.
  28
  29 == Install
  30
  31 If you're using a packaged Ruby distribution, make sure you have a C
  32 compiler and the matching Ruby development libraries and headers.
  33
  34 If you use RubyGems:
  35
  36     gem install kcar
  37
  38 Otherwise grab the latest tarball from:
  39
  40 http://bogomips.org/kcar/files/
  41
  42 Unpack it, and run "ruby setup.rb"
  43
  44 == Usage:
  45
  46 While you can use the Kcar::Parser directly, you'll usually want the
  47 higher-level interface of Kcar::Response:
  48
  49     require 'rack' # for Rack::Utils::HeaderHash, which is optional
  50     require 'socket' # for TCPSocket
  51     require 'kcar'
  52     sock = TCPSocket.new('example.com', 80)
  53     sock.write("GET / HTTP/1.0\r\n\r\n")
  54
  55     # instead of a Rack::Utils::HeaderHash object below, you can also
  56     # pass a regular Hash or Array object.
  57     response = Kcar::Response.new(sock, Rack::Utils::HeaderHash.new)
  58     status, headers, body = response.rack
  59
  60 You can now do further processing on the status, headers, or iterate
  61 through the body with body.each.
  62
  63 == Development
  64
  65 You can get the latest source via git from the following locations:
  66
  67   git://git.bogomips.org/kcar.git
  68   git://repo.or.cz/kcar.git (mirror)
  69
  70 You may browse the code from the web and download the latest snapshot
  71 tarballs here:
  72
  73 * http://git.bogomips.org/cgit/kcar.git (cgit)
  74 * http://repo.or.cz/w/kcar.git (gitweb)
  75
  76 Inline patches (from "git format-patch") to the mailing list are
  77 preferred because they allow code review and comments in the reply to
  78 the patch.
  79
  80 We will adhere to mostly the same conventions for patch submissions as
  81 git itself.  See the Documentation/SubmittingPatches document
  82 distributed with git on on patch submission guidelines to follow.  Just
  83 don't email the git mailing list or maintainer with kcar patches.
  84
  85 == Contact
  86
  87 All feedback (bug reports, user/development discussion, patches, pull
  88 requests) go to the mailing list: mailto:kcar@librelist.com
  89
  90 The mailing list is mirrored to Gmane, all information about the
  91 group is here:
  92
  93 http://gmane.org/info.php?group=gmane.comp.lang.ruby.kcar.general
  94
  95 Mailing list archives in mbox format may be downloaded here:
  96
  97 http://bogomips.org/kcar/archives/