ftw 0.0.4 → 0.0.5

data/README.md

@@ -1,10 +1,21 @@
 # For The Web
 
-net/http is pretty much not good. dns behavior in ruby changes quite frequently.
+## Getting Started
 
-Above all else, I want a consistent API and behavior that I can rely on. Ruby stdlib is not that thing.
+For doing client stuff (http requests, etc), you'll want {FTW::Agent}.
 
-I want:
+For doing server stuff (http serving, etc), you'll want {FTW::Server}. (not implemented yet)
+
+## Overview
+
+net/http is pretty much not good. Additionally, DNS behavior in ruby changes quite frequently.
+
+I primarily want two things in both client and server operations:
+
+* A consistent API with good documentation and tests
+* Modern web features: websockets, spdy, etc.
+
+Desired features:
 
 * A HTTP client that acts as a full user agent, not just a single connections. (With connection reuse)
 * HTTP and SPDY support.
@@ -14,35 +25,43 @@ I want:
 * Server and Client modes.
 * Support for both normal operation and EventMachine would be nice.
 
-## TODO
+For reference:
 
-* Tests, yo.
-* Logging, yo. With cabin, obviously.
-* [DNS in Ruby stdlib is broken](https://github.com/jordansissel/experiments/tree/master/ruby/dns-resolving-bug), I need to write my own
+* [DNS in Ruby stdlib is broken](https://github.com/jordansissel/experiments/tree/master/ruby/dns-resolving-bug), so I need to provide my own DNS api.
 
-## API Scratch
+## Agent API
 
 ### Common case
 
     agent = FTW::Agent.new
+
     request = agent.get("http://www.google.com/")
     response = request.execute
+    puts response.body.read
 
     # Simpler
-    response = agent.get!("http://www.google.com/")
+    response = agent.get!("http://www.google.com/").read
+    puts response.body.read
 
 ### SPDY
 
-    # SPDY should automatically be attempted. The caller should be unaware.
+SPDY should automatically be attempted. The caller should be unaware.
+
+I do not plan on exposing any direct means for invoking SPDY.
 
 ### WebSockets
 
     # 'http(s)' or 'ws(s)' urls are valid here. They will mean the same thing.
-    request = agent.websocket("http://somehost/endpoint")
-    # Set auth header
-    request["Authorization"] = ...
-    request["Cookie"] = ...
+    websocket = agent.websocket!("http://somehost/endpoint")
+
+    websocket.publish("Hello world")
+    websocket.each do |message|
+      puts :received => message
+    end
+
+## Server API
 
-    websocket, error = request.execute
-    # Now websocket.read receives a message, websocket.write sends a message.
+TBD. Will likely surround 'rack' somehow.
 
+It's possible the 'cramp' gem supports all the server-side features we need
+(except for SPDY, I suppose, which I might be able to contribute upstream)

data/lib/ftw/agent.rb

@@ -37,6 +37,10 @@ require "logger"
 class FTW::Agent
   STANDARD_METHODS = %w(options get head post put delete trace connect)
 
+  # Everything is private by default.
+  # At the bottom of this class, public methods will be declared.
+  private
+
   def initialize
     @pool = FTW::Pool.new
     @logger = Cabin::Channel.get($0)
@@ -91,7 +95,6 @@ class FTW::Agent
   # This will send the http request. If the websocket handshake
   # is successful, a FTW::WebSocket instance will be returned.
   # Otherwise, a FTW::Response will be returned.
-  public
   def websocket!(uri, options={})
     # TODO(sissel): Use FTW::Agent#upgrade! ?
     req = request("GET", uri, options)
@@ -132,7 +135,6 @@ class FTW::Agent
   # The 'options' hash supports the following keys:
   # 
   # * :headers => { string => string, ... }. This allows you to set header values.
-  public
   def request(method, uri, options)
     @logger.info("Creating new request", :method => method, :uri => uri, :options => options)
     request = FTW::Request.new(uri)
@@ -155,7 +157,9 @@ class FTW::Agent
   # is opened.
   #
   # Redirects are always followed.
-  public
+  #
+  # @params
+  # @return [FTW::Response] the response for this request.
   def execute(request)
     # TODO(sissel): Make redirection-following optional, but default.
 
@@ -206,7 +210,6 @@ class FTW::Agent
   end # def execute
 
   # Returns a FTW::Connection connected to this host:port.
-  private
   def connect(host, port)
     address = "#{host}:#{port}"
     @logger.debug("Fetching from pool", :address => address)
@@ -220,4 +223,6 @@ class FTW::Agent
     connection.mark
     return connection
   end # def connect
+
+  public(:initialize, :execute, :websocket!, :upgrade!)
 end # class FTW::Agent

data/lib/ftw/connection.rb

@@ -19,6 +19,8 @@ class FTW::Connection
   include FTW::Poolable
   include Cabin::Inspectable
 
+  private
+
   # A new network connection.
   # The 'destination' argument can be an array of strings or a single string.
   # String format is expected to be "host:port"
@@ -29,7 +31,6 @@ class FTW::Connection
   #
   # If you specify multiple destinations, they are used in a round-robin
   # decision made during reconnection.
-  public
   def initialize(destinations)
     if destinations.is_a?(String)
       @destinations = [destinations]
@@ -64,7 +65,6 @@ class FTW::Connection
   #
   # Timeout value is optional. If no timeout is given, this method
   # blocks until a connection is successful or an error occurs.
-  public
   def connect(timeout=nil)
     # TODO(sissel): Raise if we're already connected?
     close if connected?
@@ -114,7 +114,6 @@ class FTW::Connection
   end # def connect
 
   # Is this Connection connected?
-  public
   def connected?
     return @connected
   end # def connected?
@@ -125,7 +124,6 @@ class FTW::Connection
   # This method is not guaranteed to have written the full data given.
   #
   # Returns the number of bytes written (See also IO#syswrite)
-  public
   def write(data, timeout=nil)
     #connect if !connected?
     if writable?(timeout)
@@ -140,7 +138,6 @@ class FTW::Connection
   #
   # This method is not guaranteed to read exactly 'length' bytes. See
   # IO#sysread
-  public
   def read(timeout=nil)
     data = ""
     data.force_encoding("BINARY") if data.respond_to?(:force_encoding)
@@ -170,13 +167,11 @@ class FTW::Connection
   end # def read
 
   # Push back some data onto the connection's read buffer.
-  public
   def pushback(data)
     @pushback_buffer << data
   end # def pushback
 
   # End this connection, specifying why.
-  public
   def disconnect(reason)
     begin 
       @socket.close_read
@@ -195,7 +190,6 @@ class FTW::Connection
   # the timeout period. False otherwise.
   #
   # The time out is in seconds. Fractional seconds are OK.
-  public
   def writable?(timeout)
     ready = IO.select(nil, [@socket], nil, timeout)
     return !ready.nil?
@@ -205,7 +199,6 @@ class FTW::Connection
   # the timeout period. False otherwise.
   #
   # The time out is in seconds. Fractional seconds are OK.
-  public
   def readable?(timeout)
     #return false if @reader_closed
     ready = IO.select([@socket], nil, nil, timeout)
@@ -213,19 +206,16 @@ class FTW::Connection
   end # def readable?
 
   # The host:port
-  public
   def peer
     return @remote_address
   end # def peer
 
   # Support 'to_io' so you can use IO::select on this object.
-  public
   def to_io
     return @socket
   end # def to_io
 
   # Secure this connection with TLS.
-  public
   def secure(timeout=nil, options={})
     # Skip this if we're already secure.
     return if secured?
@@ -277,9 +267,11 @@ class FTW::Connection
   end # def secure
 
   # Has this connection been secured?
-  public
   def secured?
     return @secure
   end # def secured?
+
+  public(:connect, :connected?, :write, :read, :pushback, :disconnect,
+         :writable?, :readable?, :peer, :to_io, :secure, :secured?)
 end # class FTW::Connection
 

data/lib/ftw/dns.rb

@@ -15,15 +15,15 @@ class FTW::DNS
   V4_IN_V6_PREFIX = "0:" * 12
 
   # Get a singleton instance of FTW::DNS
-  public
   def self.singleton
     @resolver ||= self.new
   end # def self.singleton
 
+  private
+
   # Resolve a hostname.
   #
   # It will return an array of all known addresses for the host.
-  public
   def resolve(hostname)
     official, aliases, family, *addresses = Socket.gethostbyname(hostname)
     # We ignore family, here. Ruby will return v6 *and* v4 addresses in
@@ -43,18 +43,15 @@ class FTW::DNS
   # 
   # Use this method if you are connecting to a hostname that resolves to
   # multiple addresses.
-  public
   def resolve_random(hostname)
     addresses = resolve(hostname)
     return addresses[rand(addresses.size)]
   end # def resolve_random
 
-  private
   def unpack_v4(address)
     return address.unpack("C4").join(".")
   end # def unpack_v4
 
-  private
   def unpack_v6(address)
     if address.length == 16
       # Unpack 16 bit chunks, convert to hex, join with ":"
@@ -68,4 +65,6 @@ class FTW::DNS
       "::" + unpack_v4(address)
     end
   end # def unpack_v6
+
+  public(:resolve, :resolve_random)
 end # class FTW::DNS

data/lib/ftw/http/headers.rb

@@ -16,24 +16,29 @@ class FTW::HTTP::Headers
   include Enumerable
   include FTW::CRLF
 
-  # Make a new headers container. You can pass a hash of 
-  public
+  private
+
+  # Make a new headers container.
+  #
+  # @param [Hash, optional] a hash of headers to start with.
   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.
+  #
+  # @param [String] the name of the field to set
+  # @param [String or Array] the value of the field to set
   def set(field, value)
     @headers[field.downcase] = value
   end # def set
 
   alias_method :[]=, :set
 
-  # Set a header field to a specific value.
-  # Any existing value(s) for this field are destroyed.
+  # Does this header include this field name?
+  # @return [true, false]
   def include?(field)
     @headers.include?(field.downcase)
   end # def include?
@@ -93,9 +98,9 @@ class FTW::HTTP::Headers
 
   # 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
+  # @return [String] if there is only one value for this field
+  # @return [Array] if there are multiple values for this field
+  # @return [nil] if there are no values for this field
   def get(field)
     field = field.downcase
     return @headers[field]
@@ -119,18 +124,33 @@ class FTW::HTTP::Headers
     end
   end # end each
 
-  public
+  # @return [Hash] String keys and values of String (field value) or Array (of String field values)
   def to_hash
     return @headers
   end # def to_hash
 
-  public
+  # Serialize this object to a string in HTTP format described by RFC2616
+  #
+  # Example:
+  #
+  #     headers = FTW::HTTP::Headers.new
+  #     headers.add("Host", "example.com")
+  #     headers.add("X-Forwarded-For", "1.2.3.4")
+  #     headers.add("X-Forwarded-For", "192.168.0.1")
+  #     puts headers.to_s
+  #
+  #     # Result
+  #     Host: example.com
+  #     X-Forwarded-For: 1.2.3.4
+  #     X-Forwarded-For: 192.168.0.1
   def to_s
     return @headers.collect { |name, value| "#{name}: #{value}" }.join(CRLF) + CRLF
   end # def to_s
   
-  public
+  # Inspect this object
   def inspect
     return "#{self.class.name} <#{to_hash.inspect}>"
   end # def inspect
+
+  public(:set, :[]=, :include?, :add, :remove, :get, :[], :each, :to_hash, :to_s, :inspect)
 end # class FTW::HTTP::Headers

data/lib/ftw/http/message.rb

@@ -3,41 +3,52 @@ require "ftw/http/headers"
 require "ftw/crlf"
 
 # HTTP Message, RFC2616
+# For specification, see RFC2616 section 4: <http://tools.ietf.org/html/rfc2616#section-4>
+#
+# You probably won't use this class much. Instead, check out {FTW::Request} and {FTW::Response}
 module FTW::HTTP::Message
   include FTW::CRLF
 
-  # The HTTP headers. See FTW::HTTP::Headers
+  # The HTTP headers - See {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.
+  # 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
+
+  # HTTP Versions that are valid.
   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
+  private
+
+  # A new HTTP message.
   def initialize
     @headers = FTW::HTTP::Headers.new
     @body = nil
   end # def initialize
 
-  # get a header value
-  public
-  def [](header)
+  # Get a header value by field name.
+  #
+  # @param [String] the name of the field. (case insensitive)
+  def [](field)
     return @headers[header]
   end # def []
 
-  public
-  def []=(header, value)
-    @headers[header] = header
+  # Set a header field
+  #
+  # @param [String] the name of the field. (case insensitive)
+  # @param [String] the value to set for this field
+  def []=(field, value)
+    @headers[field] = header
   end # def []=
 
+  # Set the body of this message
+  #
+  # The 'message_body' can be an IO-like object, Enumerable, or String.
+  #
   # 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
@@ -46,7 +57,10 @@ module FTW::HTTP::Message
     @body = message_body
   end # def body=
 
-  public
+  # Get the body of this message
+  #
+  # Returns an Enumerable, IO-like object, or String, depending on how this
+  # message was built.
   def body
     # TODO(sissel): verification todos follow...
     # TODO(sissel): RFC2616 section 4.3 - if there is a message body
@@ -58,22 +72,21 @@ module FTW::HTTP::Message
     return @body
   end # def body
 
-  # Does this message have a message body / content?
-  public
+  # Should this message have a content?
+  #
+  # In HTTP 1.1, there is a body if response sets Content-Length *or*
+  # Transfer-Encoding, it has a body. Otherwise, there is no body.
   def content?
-    # In HTTP 1.1, there is a body if response sets Content-Length *or*
-    # Transfer-Encoding, it has a body. Otherwise, there is no body.
     return (headers.include?("Content-Length") and headers["Content-Length"].to_i > 0) \
       || headers.include?("Transfer-Encoding")
   end # def content?
 
-  public
+  # Does this message have a body?
   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)
@@ -93,8 +106,10 @@ module FTW::HTTP::Message
   #                       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
+
+  public(:initialize, :headers, :version, :version=, :[], :[]=, :body=, :body,
+         :content?, :body?, :to_s)
 end # class FTW::HTTP::Message

data/lib/ftw/request.rb

@@ -15,6 +15,8 @@ class FTW::Request
   include FTW::CRLF
   include Cabin::Inspectable
 
+  private
+
   # The http method. Like GET, PUT, POST, etc..
   # RFC2616 5.1.1 - <http://tools.ietf.org/html/rfc2616#section-5.1.1>
   #
@@ -47,7 +49,6 @@ class FTW::Request
   # Make a new request with a uri if given.
   #
   # The uri is used to set the address, protocol, Host header, etc.
-  public
   def initialize(uri=nil)
     super()
     @port = 80
@@ -66,7 +67,6 @@ class FTW::Request
   # The 'connection' should be a FTW::Connection instance, but it might work
   # with a normal IO object.
   #
-  public
   def execute(connection)
     tries = 3
     begin
@@ -116,7 +116,6 @@ class FTW::Request
   end # def execute
 
   # Use a URI to help fill in parts of this Request.
-  public
   def use_uri(uri)
     # Convert URI objects to Addressable::URI
     case uri
@@ -142,7 +141,6 @@ class FTW::Request
 
   # 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:
@@ -163,4 +161,8 @@ class FTW::Request
 
   # Define the Message's start_line as request_line
   alias_method :start_line, :request_line
+
+  public(:method, :method=, :request_uri, :request_uri=, :path, :port, :port=,
+         :protocol, :protocol=, :execute, :use_uri, :request_line, :start_line)
+
 end # class FTW::Request < Message

data/lib/ftw/response.rb

@@ -9,10 +9,6 @@ require "http/parser" # gem http_parser.rb
 class FTW::Response 
   include 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
@@ -51,8 +47,9 @@ class FTW::Response
 
   attr_accessor :body
 
+  private
+
   # Create a new Response.
-  public
   def initialize
     super
     @logger = Cabin::Channel.get
@@ -60,21 +57,18 @@ class FTW::Response
   end # def initialize
 
   # Is this response a redirect?
-  public
   def redirect?
     # redirects are 3xx
     return @status >= 300 && @status < 400
   end # redirect?
 
   # Is this response an error?
-  public
   def error?
     # 4xx and 5xx are errors
     return @status >= 400 && @status < 600
   end # def error?
 
   # 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
@@ -86,7 +80,6 @@ class FTW::Response
   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
@@ -97,19 +90,10 @@ class FTW::Response
   # Define the Message's start_line as status_line
   alias_method :start_line, :status_line
 
-  # Set the body of this response. In most cases this will be a FTW::Connection when
-  # Response objects are being created by a FTW::Agent. In Server cases,
-  # the body is likely to be a string or enumerable.
-  public
-  def body=(connection_or_string_or_enumerable)
-    @body = connection_or_string_or_enumerable
-  end # def body=
-
   # Read the body of this Response. The block is called with chunks of the
   # response as they are read in.
   #
   # This method is generally only called by http clients, not servers.
-  public
   def read_body(&block)
     if @body.respond_to?(:read)
       if headers.include?("Content-Length") and headers["Content-Length"].to_i > 0
@@ -129,7 +113,6 @@ class FTW::Response
 
   # Read the length bytes from the body. Yield each chunk read to the block
   # given. This method is generally only called by http clients, not servers.
-  private
   def read_body_length(length, &block)
     remaining = length
     while remaining > 0
@@ -148,7 +131,6 @@ class FTW::Response
   end # def read_body_length
 
   # This is kind of messed, need to fix it.
-  private
   def read_body_chunked(&block)
     parser = HTTP::Parser.new
 
@@ -169,11 +151,13 @@ class FTW::Response
   end # def read_body_chunked
 
   # Is this Response the result of a successful Upgrade request?
-  public
   def upgrade?
     return false unless status == 101 # "Switching Protocols"
     return false unless headers["Connection"] == "Upgrade"
     return true
   end # def upgrade?
+
+  public(:status=, :status, :reason, :initialize, :upgrade?, :redirect?,
+         :error?, :status_line, :read_body)
 end # class FTW::Response
 

data/lib/ftw/version.rb

@@ -1,5 +1,5 @@
 require "ftw/namespace"
 
 module FTW
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/ftw/websocket.rb

@@ -4,6 +4,7 @@ require "base64" # stdlib
 require "digest/sha1" # stdlib
 require "cabin"
 require "ftw/websocket/parser"
+require "ftw/crlf"
 
 # WebSockets, RFC6455.
 #
@@ -19,6 +20,8 @@ class FTW::WebSocket
 
   WEBSOCKET_ACCEPT_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
+  private
+
   # Protocol phases
   # 1. tcp connect
   # 2. http handshake (RFC6455 section 4)
@@ -26,7 +29,6 @@ class FTW::WebSocket
 
   # Creates a new websocket and fills in the given http request with any
   # necessary settings.
-  public
   def initialize(request)
     @key_nonce = generate_key_nonce
     @request = request
@@ -38,14 +40,12 @@ class FTW::WebSocket
   # after the websocket upgrade and handshake have been successful.
   #
   # You probably don't call this yourself.
-  public
   def connection=(connection)
     @connection = connection
   end # def connection=
 
   # Prepare the request. This sets any required headers and attributes as
   # specified by RFC6455
-  private
   def prepare(request)
     # RFC6455 section 4.1:
     #  "2.   The method of the request MUST be GET, and the HTTP version MUST
@@ -73,7 +73,6 @@ class FTW::WebSocket
   end # def prepare
 
   # Generate a websocket key nonce.
-  private
   def generate_key_nonce
     # RFC6455 section 4.1 says:
     # ---
@@ -95,7 +94,6 @@ class FTW::WebSocket
   end # def generate_key_nonce
 
   # Is this Response acceptable for our WebSocket Upgrade request?
-  public
   def handshake_ok?(response)
     # See RFC6455 section 4.2.2
     return false unless response.status == 101 # "Switching Protocols"
@@ -115,7 +113,6 @@ class FTW::WebSocket
   # break from it. 
   #
   # The text payload of each message will be yielded to the block.
-  public
   def each(&block)
     loop do
       payload = @parser.feed(@connection.read)
@@ -133,7 +130,6 @@ class FTW::WebSocket
   #   message[3] ^ key[3]
   #   message[4] ^ key[0]
   #   ...
-  private
   def mask(message, key)
     masked = []
     mask_bytes = key.unpack("C4")
@@ -148,7 +144,6 @@ class FTW::WebSocket
   # Publish a message text.
   #
   # This will send a websocket text frame over the connection.
-  public
   def publish(message)
     # TODO(sissel): Support server and client modes.
     # Server MUST NOT mask. Client MUST mask.
@@ -190,5 +185,7 @@ class FTW::WebSocket
       @connection.write(data.pack(pack))
     end
   end # def publish
+
+  public(:initialize, :connection=, :handshake_ok?, :each, :publish)
 end # class FTW::WebSocket
 

data/lib/ftw/websocket/parser.rb

@@ -22,12 +22,29 @@ require "ftw/websocket"
 #    + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
 #    |                     Payload Data continued ...                |
 #    +---------------------------------------------------------------+
+#
+# Example use:
+#
+#     socket = FTW::Connection.new("example.com:80")
+#     parser = FTW::WebSocket::Parser.new
+#     # ... do HTTP Upgrade request to websockets
+#     loop do
+#       data = socket.sysread(4096)
+#       payload = parser.feed(data)
+#       if payload
+#         # We got a full websocket frame, print the payload.
+#         p :payload => payload
+#       end
+#     end
+#
 class FTW::WebSocket::Parser
   # XXX: Implement control frames: http://tools.ietf.org/html/rfc6455#section-5.5
 
   # States are based on the minimal unit of 'byte'
   STATES = [ :flags_and_opcode, :mask_and_payload_init, :payload_length, :payload ]
 
+  private
+
   # A new WebSocket protocol parser.
   def initialize
     @logger = Cabin::Channel.get($0)
@@ -42,7 +59,6 @@ class FTW::WebSocket::Parser
   end # def initialize
 
   # Transition to a specified state and set the next required read length.
-  private
   def transition(state, next_length)
     @logger.debug("Transitioning", :transition => state, :nextlen => next_length)
     @state = state
@@ -53,7 +69,9 @@ class FTW::WebSocket::Parser
   # 
   # Currently, it will return the raw payload of websocket messages.
   # Otherwise, it returns nil if no complete message has yet been consumed.
-  public
+  #
+  # @param [String] the string data to feed into the parser. 
+  # @return [String, nil] the websocket message payload, if any, nil otherwise.
   def feed(data)
     @buffer << data
     while have?(@need)
@@ -66,13 +84,11 @@ class FTW::WebSocket::Parser
   end # def <<
 
   # Do we have at least 'length' bytes in the buffer?
-  private
   def have?(length)
     return length <= @buffer.size 
   end # def have?
 
   # Get 'length' string from the buffer.
-  private
   def get(length=nil)
     length = @need if length.nil?
     data = @buffer[0 ... length]
@@ -81,14 +97,12 @@ class FTW::WebSocket::Parser
   end # def get
 
   # Set the minimum number of bytes we need in the buffer for the next read.
-  private
   def need(length)
     @need = length
   end # def need
 
   # State: Flags (fin, etc) and Opcode. 
   # See: http://tools.ietf.org/html/rfc6455#section-5.3
-  private
   def flags_and_opcode
     #     0              
     #     0 1 2 3 4 5 6 7
@@ -112,7 +126,6 @@ class FTW::WebSocket::Parser
 
   # State: mask_and_payload_init
   # See: http://tools.ietf.org/html/rfc6455#section-5.2
-  private
   def mask_and_payload_init
     byte = get.bytes.first
     @mask = byte & 0x80 # first bit (msb)
@@ -136,7 +149,6 @@ class FTW::WebSocket::Parser
   # This is the 'extended payload length' with support for both 16 
   # and 64 bit lengths.
   # See: http://tools.ietf.org/html/rfc6455#section-5.2
-  private
   def payload_length
     #     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     #    +-+-+-+-+-------+-+-------------+-------------------------------+
@@ -169,7 +181,6 @@ class FTW::WebSocket::Parser
   # Read the full payload and return it.
   # See: http://tools.ietf.org/html/rfc6455#section-5.3
   #
-  private
   def payload
     # TODO(sissel): Handle massive payload lengths without exceeding memory.
     # Perhaps if the payload is large (say, larger than 500KB by default),
@@ -180,4 +191,6 @@ class FTW::WebSocket::Parser
     transition(:flags_and_opcode, 1)
     return data
   end # def payload
+
+  public(:feed)
 end # class FTW::WebSocket::Parser

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ftw
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -11,32 +11,33 @@ bindir: bin
 cert_chain: []
 date: 2012-02-13 00:00:00.000000000 Z
 dependencies: []
-description: Trying to build a solid and sane API for client and server web stuff.
+description: For The Web. Trying to build a solid and sane API for client and server
+  web stuff. Client and Server operations for HTTP, WebSockets, SPDY, etc.
 email:
 - jls@semicomplete.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/ftw/agent.rb
+- lib/ftw/websocket.rb
 - lib/ftw/pool.rb
+- lib/ftw/agent.rb
+- lib/ftw/version.rb
+- lib/ftw/namespace.rb
+- lib/ftw/crlf.rb
+- lib/ftw/connection.rb
+- lib/ftw/websocket/parser.rb
+- lib/ftw/request.rb
 - lib/ftw/cookies.rb
 - lib/ftw/http/headers.rb
 - lib/ftw/http/message.rb
-- lib/ftw/websocket/parser.rb
-- lib/ftw/connection.rb
-- lib/ftw/request.rb
-- lib/ftw/namespace.rb
-- lib/ftw/dns.rb
 - lib/ftw/response.rb
+- lib/ftw/dns.rb
 - lib/ftw/poolable.rb
-- lib/ftw/websocket.rb
-- lib/ftw/crlf.rb
-- lib/ftw/version.rb
 - lib/ftw.rb
+- test/ftw/crlf.rb
 - test/ftw/http/headers.rb
 - test/ftw/http/dns.rb
-- test/ftw/crlf.rb
 - test/testing.rb
 - test/all.rb
 - README.md
@@ -65,5 +66,7 @@ rubyforge_project:
 rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
-summary: For The Web. HTTP, WebSockets, SPDY, etc.
+summary: For The Web. Trying to build a solid and sane API for client and server web
+  stuff. Client and Server operations for HTTP, WebSockets, SPDY, etc.
 test_files: []
+has_rdoc: