ftw 0.0.7 → 0.0.8

data/README.md

@@ -62,13 +62,29 @@ I do not plan on exposing any direct means for invoking SPDY.
 
 ## Server API
 
-Not sure yet...
+I have implemented a rack server, Rack::Handler::FTW. It does not comply fully
+with the Rack spec. See 'Rack Compliance Issues' below.
 
-Since Rack is not supported, I'll have to do a lot of legwork myself.
+Under the FTW rack handler, there is an environment variable added,
+"ftw.connection". This will be a FTW::Connection you can use for CONNECT,
+Upgrades, etc. 
 
-* Implement a proper Socket Server api
-* Implement a HTTP server on top of that (add SPDY support later)
-* Implement a Sinatra-like DSL on top of HTTP
+There's also a websockets wrapper, FTW::WebSockets::Rack, that will help you
+specifically with websocket requests and such.
+
+## Rack Compliance issues
+
+Due to some awkward and bad requirements - specifically those around the
+specified behavior of 'rack.input' - I can't support the rack specification fully.
+
+The 'rack.input' must be an IO-like object supporting #rewind which rewinds to
+the beginning of the request.
+
+For high-data connections (like uploads, HTTP CONNECT, and HTTP Upgrade), it's
+not practical to hold the entire history of time in a buffer. We'll run out of
+memory, you crazy!
+
+Details here: https://github.com/rack/rack/issues/347
 
 ## Other Projects
 
@@ -79,10 +95,3 @@ Here are some related projects that I have no affiliation with:
 * https://github.com/lifo/cramp - real-time web framework (async, websockets)
 * https://github.com/igrigorik/em-http-request - HTTP client for EventMachine
 * https://github.com/geemus/excon - http client library
-
-## Missing Features
-
-* No Rack support, for now. There are technical requirements the Rack SPEC that
-  prevent rack applications from really servicing uploads, HTTP Upgrades, etc.
-  Details here: https://github.com/rack/rack/issues/347
-

data/lib/ftw/singleton.rb

@@ -1,10 +1,22 @@
 require "ftw/namespace"
 
+# A mixin that provides singleton-ness
+#
+# Usage:
+#
+#     class Foo
+#       extend FTW::Singleton
+#
+#       ...
+#     end
+#
+# foo = Foo.singleton
 module FTW::Singleton
   def self.included(klass)
     raise ArgumentError.new("In #{klass.name}, you want to use 'extend #{self.name}', not 'include ...'")
   end # def included
 
+  # Create a singleton instance of this class.
   def singleton
     @instance ||= self.new
     return @instance

data/lib/ftw/version.rb

@@ -3,5 +3,5 @@ require "ftw/namespace"
 # :nodoc:
 module FTW
   # The version of this library
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/lib/ftw/websocket/constants.rb

@@ -5,6 +5,7 @@
 # The opcode definitions come from:
 # http://tools.ietf.org/html/rfc6455#section-11.8
 module FTW::WebSocket::Constants
+  # websocket uuid, used in hash signing of websocket responses (RFC6455)
   WEBSOCKET_ACCEPT_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
   # Indication that this frame is a continuation in a fragmented message

data/lib/ftw/websocket/rack.rb

@@ -3,11 +3,29 @@ require "ftw/websocket/parser"
 require "base64" # stdlib 
 require "digest/sha1" # stdlib
 
+# A websocket helper for Rack
+#
+# An example with Sinatra:
+#
+#     get "/websocket/echo" do
+#       ws = FTW::WebSocket::Rack.new(env)
+#       stream(:keep_open) do |out|
+#         ws.each do |payload|
+#           # 'payload' is the text payload of a single websocket message
+#           # publish it back to the client
+#           ws.publish(payload)
+#         end
+#       end
+#       ws.rack_response
+#     end
 class FTW::WebSocket::Rack
   include FTW::WebSocket::Constants
 
   private
 
+  # Create a new websocket rack helper... thing.
+  #
+  # @param rack_env the 'env' bit given to your Rack application
   def initialize(rack_env)
     @env = rack_env
     @handshake_errors = []
@@ -28,16 +46,28 @@ class FTW::WebSocket::Rack
     @parser = FTW::WebSocket::Parser.new
   end # def initialize
 
+  # Test values for equality. This is used in handshake tests.
   def expect_equal(expected, actual, message)
     if expected != actual
       @handshake_errors << message
     end
   end # def expected
 
+  # Is this a valid handshake?
   def valid?
     return @handshake_errors.empty?
   end # def valid?
 
+  # Get the response Rack is expecting.
+  #
+  # If this was a valid websocket request, it will return a response
+  # that completes the HTTP portion of the websocket handshake.
+  #
+  # If this was an invalid websocket request, it will return a
+  # 400 status code and descriptions of what failed in the body
+  # of the response.
+  #
+  # @return [number, hash, body]
   def rack_response
     if valid?
       # Return the status, headers, body that is expected.
@@ -58,6 +88,15 @@ class FTW::WebSocket::Rack
     end
   end # def rack_response
 
+  # Enumerate each websocket payload (message).
+  #
+  # The payload of each message will be yielded to the block.
+  #
+  # Example:
+  #
+  #     ws.each do |payload|
+  #       puts "Received: #{payload}"
+  #     end
   def each
     connection = @env["ftw.connection"]
     while true
@@ -68,6 +107,9 @@ class FTW::WebSocket::Rack
     end
   end # def each
 
+  # Publish a message over this websocket.
+  #
+  # @param message Publish a string message to the websocket.
   def publish(message)
     writer = FTW::WebSocket::Writer.singleton
     writer.write_text(@env["ftw.connection"], message)

data/lib/ftw/websocket/writer.rb

@@ -29,7 +29,10 @@ class FTW::WebSocket::Writer
   include FTW::WebSocket::Constants
   extend FTW::Singleton
 
-  # 
+  # A list of valid modes. Used to validate input in #write_text.
+  #
+  # In :server mode, payloads are not masked. In :client mode, payloads
+  # are masked. Masking is described in RFC6455.
   VALID_MODES = [:server, :client]
 
   private

data/lib/rack/handler/ftw.rb

@@ -23,35 +23,56 @@ class Rack::Handler::FTW
   include FTW::Protocol
   include FTW::CRLF
 
+  # The version of the rack specification supported by this handler.
   RACK_VERSION = [1,1]
+
+  # A string constant value (used to avoid typos).
   REQUEST_METHOD = "REQUEST_METHOD".freeze
+  # A string constant value (used to avoid typos).
   SCRIPT_NAME = "SCRIPT_NAME".freeze
+  # A string constant value (used to avoid typos).
   PATH_INFO = "PATH_INFO".freeze
+  # A string constant value (used to avoid typos).
   QUERY_STRING = "QUERY_STRING".freeze
+  # A string constant value (used to avoid typos).
   SERVER_NAME = "SERVER_NAME".freeze
+  # A string constant value (used to avoid typos).
   SERVER_PORT = "SERVER_PORT".freeze
 
+  # A string constant value (used to avoid typos).
   RACK_DOT_VERSION = "rack.version".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_URL_SCHEME = "rack.url_scheme".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_INPUT = "rack.input".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_ERRORS = "rack.errors".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_MULTITHREAD = "rack.multithread".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_MULTIPROCESS = "rack.multiprocess".freeze
+  # A string constant value (used to avoid typos).
   RACK_DOT_RUN_ONCE = "rack.run_once".freeze
+  # A string constant value (used to avoid typos).
   FTW_DOT_CONNECTION = "ftw.connection".freeze
 
+  # This method is invoked when rack starts this as the server.
   def self.run(app, config)
     server = self.new(app, config)
     server.run
-  end
+  end # def self.run
 
   private
 
+  # setup a new rack server
   def initialize(app, config)
     @app = app
     @config = config
-  end
+  end # def initialize
 
+  # Run the server.
+  #
+  # Connections are farmed out to threads.
   def run
     # {:environment=>"development", :pid=>nil, :Port=>9292, :Host=>"0.0.0.0",
     #  :AccessLog=>[], :config=>"/home/jls/projects/ruby-ftw/examples/test.ru",
@@ -72,6 +93,11 @@ class Rack::Handler::FTW
     end
   end # def run
 
+  # Handle a new connection.
+  #
+  # This method parses http requests and passes them on to #handle_request
+  #
+  # @param connection The FTW::Connection being handled.
   def handle_connection(connection)
     while true
       begin
@@ -86,6 +112,8 @@ class Rack::Handler::FTW
     connection.disconnect("Fun")
   end # def handle_connection
 
+  # Handle a request. This will set up the rack 'env' and invoke the
+  # application associated with this handler.
   def handle_request(request, connection)
     path, query = request.path.split("?", 2)
     env = {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ftw
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors: