ftw 0.0.1

data/lib/net/ftw/http/connection.rb

@@ -0,0 +1,42 @@
+require "net/ftw/namespace"
+require "net/ftw/connection"
+
+class Net::FTW::HTTP::Connection < Net::FTW::Connection
+  HEADERS_COMPLETE = :headers_complete
+  MESSAGE_BODY = :message_body
+
+  def run
+    # TODO(sissel): Implement retries on certain failures like DNS, connect
+    # timeouts, or connection resets?
+    # TODO(sissel): use HTTPS if the uri.scheme == "https"
+    # TODO(sissel): Resolve the hostname
+    # TODO(sissel): Start a new connection, or reuse an existing one.
+    #
+    # TODO(sissel): This suff belongs in a new class, like HTTP::Connection or something.
+    parser = HTTP::Parser.new
+
+    # Only parse the header of the response
+    state = :headers
+    parser.on_headers_complete = proc { state = :body; :stop }
+
+    on(DATA) do |data|
+      # TODO(sissel): Implement this better. Should be able to swap out the
+      # DATA handler at run-time
+      if state == :headers
+        offset = parser << data
+        if state == :body
+          # headers done parsing.
+          version = "#{parser.http_major}.#{parser.http_minor}".to_f
+          trigger(HEADERS_COMPLETE, version, parser.status_code, parser.headers)
+
+          # Re-call 'data' with the remaining non-header portion of data.
+          trigger(DATA, data[offset..-1])
+        end
+      else
+        trigger(MESSAGE_BODY, data)
+      end
+    end
+
+    super()
+  end # def run
+end # class Net::FTW::HTTP::Connection

data/lib/net/ftw/http/headers.rb

@@ -0,0 +1,122 @@
+require "net/ftw/namespace"
+require "net/ftw/crlf"
+
+# HTTP Headers
+#
+# See RFC2616 section 4.2: <http://tools.ietf.org/html/rfc2616#section-4.2>
+#
+# Section 14.44 says Field Names in the header are case-insensitive, so
+# this library always forces field names to be lowercase. This includes
+# get() calls.
+#
+#    headers.set("HELLO", "world")
+#    headers.get("hello")   # ===> "world"
+#
+class Net::FTW::HTTP::Headers
+  include Enumerable
+  include Net::FTW::CRLF
+
+  # Make a new headers container. You can pass a hash of 
+  public
+  def initialize(headers={})
+    super()
+    @version = 1.1
+    @headers = headers
+  end # def initialize
+
+  # Set a header field to a specific value.
+  # Any existing value(s) for this field are destroyed.
+  def set(field, value)
+    @headers[field.downcase] = value
+  end # def set
+
+  # Set a header field to a specific value.
+  # Any existing value(s) for this field are destroyed.
+  def include?(field)
+    @headers.include?(field.downcase)
+  end # def include?
+
+  # Add a header field with a value.
+  #
+  # If this field already exists, another value is added.
+  # If this field does not already exist, it is set.
+  def add(field, value)
+    field = field.downcase
+    if @headers.include?(field)
+      if @headers[field].is_a?(Array)
+        @headers[field] << value
+      else
+        @headers[field] = [@headers[field], value]
+      end
+    else
+      set(field, value)
+    end
+  end # def add
+
+  # Removes a header entry. If the header has multiple values
+  # (like X-Forwarded-For can), you can delete a specific entry
+  # by passing the value of the header field to remove.
+  #
+  #     # Remove all X-Forwarded-For entries
+  #     headers.remove("X-Forwarded-For") 
+  #     # Remove a specific X-Forwarded-For entry
+  #     headers.remove("X-Forwarded-For", "1.2.3.4")
+  #
+  # * If you remove a field that doesn't exist, no error will occur.
+  # * If you remove a field value that doesn't exist, no error will occur.
+  # * If you remove a field value that is the only value, it is the same as
+  #   removing that field by name.
+  def remove(field, value=nil)
+    field = field.downcase
+    if value.nil?
+      # no value, given, remove the entire field.
+      @headers.delete(field)
+    else
+      field_value = @headers[field]
+      if field_value.is_a?(Array)
+        # remove a specific value
+        field_value.delete(value)
+        # Down to a String again if there's only one value.
+        if field_value.size == 1
+          set(field, field_value.first)
+        end
+      else
+        # Remove this field if the value matches
+        if field_value == value
+          remove(field)
+        end
+      end
+    end
+  end # def remove
+
+  # Get a field value. 
+  # 
+  # This will return:
+  #   * String if there is only a single value for this field
+  #   * Array of String if there are multiple values for this field
+  def get(field)
+    field = field.downcase
+    return @headers[field]
+  end # def get
+
+  # Iterate over headers. Given to the block are two arguments, the field name
+  # and the field value. For fields with multiple values, you will receive
+  # that same field name multiple times, like:
+  #    yield "Host", "www.example.com"
+  #    yield "X-Forwarded-For", "1.2.3.4"
+  #    yield "X-Forwarded-For", "1.2.3.5"
+  def each(&block)
+    @headers.each do |field_name, field_value|
+      if field_value.is_a?(Array)
+        field_value.map { |value| yield field_name, v }
+      else
+        yield field_name, field_value
+      end
+    end
+  end # end each
+
+  public
+  def to_s
+    return @headers.collect { |name, value| "#{name}: #{value}" }.join(CRLF) + CRLF
+  end # def to_s
+end # class Net::FTW::HTTP::Request < Message

data/lib/net/ftw/http/machine.rb

@@ -0,0 +1,38 @@
+require "net/ftw/namespace"
+require "net/ftw/machine"
+require "http/parser" # gem http_parser.rb
+
+class Net::FTW::HTTP::Machine
+  # States
+  HEADERS = :headers
+  MESSAGE = :message
+
+  # Valid transitions
+  TRANSITIONS = {
+    START => HEADERS
+    HEADERS => [MESSAGE, ERROR]
+    MESSAGE => [START, ERROR]
+  }
+
+  def initialize
+    super
+    transition(HEADERS)
+    @parser = HTTP::Parser.new
+    @parser.on_headers_complete = proc { transition(MESSAGE) }
+  end # def initialize
+
+  def state_headers(data)
+    offset = parser << data
+    if state?(MESSAGE)
+      # We finished headers and transitioned to message body.
+      yield version, parser.status_code, parser.headers
+
+      # Re-feed any body part we were fed that wasn't part of the headers
+      feed(data[offset..-1])
+    end
+  end # def state_headers
+
+  def state_message(data)
+    yield data
+  end # def state_message
+end # class Net::FTW::HTTP::Connection

data/lib/net/ftw/http/message.rb

@@ -0,0 +1,91 @@
+require "net/ftw/namespace"
+require "net/ftw/http/headers"
+
+# HTTP Message, RFC2616
+class Net::FTW::HTTP::Message
+  include Net::FTW::CRLF
+
+  # The HTTP headers. See Net::FTW::HTTP::Headers
+  # RFC2616 5.3 - <http://tools.ietf.org/html/rfc2616#section-5.3>
+  attr_reader :headers
+
+  # The HTTP version. See VALID_VERSIONS for valid versions.
+  # This will always be a Numeric object.
+  # Both Request and Responses have version, so put it in the parent class.
+  attr_accessor :version
+  VALID_VERSIONS = [1.0, 1.1]
+
+  # A new HTTP Message. You probably won't use this class much. 
+  # See RFC2616 section 4: <http://tools.ietf.org/html/rfc2616#section-4>
+  # See Request and Response.
+  public
+  def initialize
+    @headers = Net::FTW::HTTP::Headers.new
+    @body = nil
+  end # def initialize
+
+  # get a header value
+  public
+  def [](header)
+    return @headers[header]
+  end # def []
+
+  public
+  def []=(header, value)
+    @headers[header] = header
+  end # def []=
+
+  # See RFC2616 section 4.3: <http://tools.ietf.org/html/rfc2616#section-4.3>
+  public
+  def body=(message_body)
+    # TODO(sissel): if message_body is a string, set Content-Length header
+    # TODO(sissel): if it's an IO object, set Transfer-Encoding to chunked
+    # TODO(sissel): if it responds to each or appears to be Enumerable, then
+    # set Transfer-Encoding to chunked.
+    @body = message_body
+  end # def body=
+
+  public
+  def body
+    # TODO(sissel): verification todos follow...
+    # TODO(sissel): RFC2616 section 4.3 - if there is a message body
+    # then one of "Transfer-Encoding" *or* "Content-Length" MUST be present.
+    # otherwise, if neither header is present, no body is present.
+    # TODO(sissel): Responses to HEAD requests or those with status 1xx, 204,
+    # or 304 MUST NOT have a body. All other requests have a message body,
+    # even if that body is of zero length.
+    return @body
+  end # def body
+
+  # Does this message have a message body?
+  public
+  def body?
+    return @body.nil?
+  end # def body?
+
+  # Set the HTTP version. Must be a valid version. See VALID_VERSIONS.
+  public
+  def version=(ver)
+    # Accept string "1.0" or simply "1", etc.
+    ver = ver.to_f if !ver.is_a?(Float)
+
+    if !VALID_VERSIONS.include?(ver)
+      raise ArgumentError.new("#{self.class.name}#version = #{ver.inspect} is" \
+        "invalid. It must be a number, one of #{VALID_VERSIONS.join(", ")}")
+    end
+    @version = ver
+  end # def version=
+
+  # Serialize this Request according to RFC2616
+  # Note: There is *NO* trailing CRLF. This is intentional.
+  # The RFC defines:
+  #     generic-message = start-line
+  #                       *(message-header CRLF)
+  #                       CRLF
+  #                       [ message-body ]
+  # Thus, the CRLF between header and body is not part of the header.
+  public
+  def to_s
+    return [start_line, @headers].join(CRLF)
+  end
+end # class Net::FTW::HTTP::Message

data/lib/net/ftw/http/request.rb

@@ -0,0 +1,80 @@
+require "net/ftw/namespace"
+require "net/ftw/http/message"
+require "addressable/uri" # gem addressable
+require "uri" # ruby stdlib
+require "http/parser" # gem http_parser.rb
+
+# An HTTP Request.
+#
+# See RFC2616 section 5: <http://tools.ietf.org/html/rfc2616#section-5>
+class Net::FTW::HTTP::Request < Net::FTW::HTTP::Message
+  include Net::FTW::CRLF
+
+  # The http method. Like GET, PUT, POST, etc..
+  # RFC2616 5.1.1 - <http://tools.ietf.org/html/rfc2616#section-5.1.1>
+  #
+  # Warning: this accessor obscures the ruby Kernel#method() method.
+  # I would like to call this 'verb', but my preference is first to adhere to
+  # RFC terminology. Further, ruby's stdlib Net::HTTP calls this 'method' as
+  # well (See Net::HTTPGenericRequest).
+  attr_accessor :method
+
+  # This is the Request-URI. Many people call this the 'path' of the request.
+  # RFC2616 5.1.2 - <http://tools.ietf.org/html/rfc2616#section-5.1.2>
+  attr_accessor :request_uri
+
+  # Lemmings. Everyone else calls Request-URI the 'path' - so I should too.
+  alias_method :path, :request_uri
+
+  public
+  def initialize(uri=nil)
+    super()
+    use_uri(uri) if !uri.nil?
+    @version = 1.1
+  end # def initialize
+
+  public
+  def use_uri(uri)
+    # Convert URI objects to Addressable::URI
+    uri = Addressable::URI.parse(uri.to_s) if uri.is_a?(URI)
+
+    # TODO(sissel): Use normalized versions of these fields?
+    # uri.host
+    # uri.port
+    # uri.scheme
+    # uri.path
+    # uri.password
+    # uri.user
+    @request_uri = uri.path
+    @headers.set("Host", uri.host)
+    
+    # TODO(sissel): support authentication
+  end # def use_uri
+
+  # Set the method for this request. Usually something like "GET" or "PUT"
+  # etc. See <http://tools.ietf.org/html/rfc2616#section-5.1.1>
+  public
+  def method=(method)
+    # RFC2616 5.1.1 doesn't say the method has to be uppercase.
+    # It can be any 'token' besides the ones defined in section 5.1.1:
+    # The grammar for 'token' is:
+    #          token          = 1*<any CHAR except CTLs or separators>
+    # TODO(sissel): support section 5.1.1 properly. Don't upcase, but 
+    # maybe upcase things that are defined in 5.1.1 like GET, etc.
+    @method = method.upcase
+  end # def method=
+
+  # Get the request line (first line of the http request)
+  # From the RFC: Request-Line   = Method SP Request-URI SP HTTP-Version CRLF
+  #
+  # Note: I skip the trailing CRLF. See the to_s method where it is provided.
+  def request_line
+    return "#{method} #{request_uri} HTTP/#{version}"
+  end # def request_line
+
+  # Define the Message's start_line as request_line
+  alias_method :start_line, :request_line
+  # TODO(sissel): Methods to write:
+  # 1. Parsing a request, use HTTP::Parser from http_parser.rb
+  # 2. Building a request from a URI or Addressable::URI
+end # class Net::FTW::HTTP::Request < Message

data/lib/net/ftw/http/response.rb

@@ -0,0 +1,80 @@
+require "net/ftw/namespace"
+require "net/ftw/http/message"
+require "http/parser" # gem http_parser.rb
+
+class Net::FTW::HTTP::Response < Net::FTW::HTTP::Message
+  # The HTTP version number
+  # See RFC2616 section 6.1: <http://tools.ietf.org/html/rfc2616#section-6.1>
+  attr_reader :version
+
+  # The http status code (RFC2616 6.1.1)
+  # See RFC2616 section 6.1.1: <http://tools.ietf.org/html/rfc2616#section-6.1.1>
+  attr_reader :status
+
+  # The reason phrase (RFC2616 6.1.1)
+  # See RFC2616 section 6.1.1: <http://tools.ietf.org/html/rfc2616#section-6.1.1>
+  attr_reader :reason
+
+  # Translated from the recommendations listed in RFC2616 section 6.1.1
+  # See RFC2616 section 6.1.1: <http://tools.ietf.org/html/rfc2616#section-6.1.1>
+  STATUS_REASON_MAP =  {
+    100 => "Continue",
+    101 => "Switching Protocols",
+    200 => "OK",
+    201 => "Created",
+    202 => "Accepted",
+    203 => "Non-Authoritative Information",
+    204 => "No Content",
+    205 => "Reset Content",
+    206 => "Partial Content",
+    300 => "Multiple Choices",
+    301 => "Moved Permanently",
+    302 => "Found",
+    303 => "See Other",
+    304 => "Not Modified",
+    305 => "Use Proxy",
+    307 => "Temporary Redirect",
+    400 => "Bad Request",
+    401 => "Unauthorized",
+    402 => "Payment Required",
+    403 => "Forbidden",
+    404 => "Not Found",
+    405 => "Method Not Allowed",
+    406 => "Not Acceptable"
+  } # STATUS_REASON_MAP
+
+  public
+  def initialize
+    super
+    @reason = "" # Empty reason string by default. It is not required.
+  end # def initialize
+
+  # Set the status code
+  public
+  def status=(code)
+    code = code.to_i if !code.is_a?(Fixnum)
+    # TODO(sissel): Validate that 'code' is a 3 digit number
+    @status = code
+
+    # Attempt to set the reason if the status code has a known reason
+    # recommendation. If one is not found, default to the current reason.
+    @reason = STATUS_REASON_MAP.fetch(@status, @reason)
+  end # def status=
+
+  # Get the status-line string, like "HTTP/1.0 200 OK"
+  public
+  def status_line
+    # First line is 'Status-Line' from RFC2616 section 6.1
+    # Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
+    # etc...
+    return "HTTP-#{version} #{status} #{reason}"
+  end # def status_line
+
+  # Define the Message's start_line as status_line
+  alias_method :start_line, :status_line
+
+  # TODO(sissel): Methods to write:
+  # 1. Parsing a request, use HTTP::Parser from http_parser.rb
+  # 2. Building a request from a URI or Addressable::URI
+end # class Net::FTW::HTTP::Response
+