ftw 0.0.6 → 0.0.7

data/lib/ftw/crlf.rb

@@ -1,6 +1,8 @@
 require "ftw/namespace"
 
+# This module provides a 'CRLF' constant for use with protocols that need it.
+# I find it easier to specify CRLF instead of literal "\r\n"
 module FTW::CRLF
   # carriage-return + line-feed
   CRLF = "\r\n"
-end
+end # module FTW::CRLF

data/lib/ftw/dns.rb

@@ -1,5 +1,6 @@
 require "ftw/namespace"
 require "socket" # for Socket.gethostbyname
+require "ftw/singleton"
 
 # I wrap whatever Ruby provides because it is historically very
 # inconsistent in implementation behavior across ruby platforms and versions.
@@ -9,16 +10,12 @@ require "socket" # for Socket.gethostbyname
 # I didn't really want to write a DNS library, but a consistent API and
 # behavior is necessary for my continued sanity :)
 class FTW::DNS
+  extend FTW::Singleton
   # TODO(sissel): Switch to using Resolv::DNS since it lets you (the programmer)
   # choose dns configuration (servers, etc)
 
   V4_IN_V6_PREFIX = "0:" * 12
 
-  # Get a singleton instance of FTW::DNS
-  def self.singleton
-    @resolver ||= self.new
-  end # def self.singleton
-
   private
 
   # Resolve a hostname.
@@ -48,10 +45,12 @@ class FTW::DNS
     return addresses[rand(addresses.size)]
   end # def resolve_random
 
+  # Unserialize a 4-byte ipv4 address into a human-readable a.b.c.d string
   def unpack_v4(address)
     return address.unpack("C4").join(".")
   end # def unpack_v4
 
+  # Unserialize a 16-byte ipv6 address into a human-readable a:b:c:...:d string
   def unpack_v6(address)
     if address.length == 16
       # Unpack 16 bit chunks, convert to hex, join with ":"

data/lib/ftw/namespace.rb

@@ -1,4 +1,6 @@
 module FTW
+  # :nodoc:
   module HTTP; end
+  # :nodoc:
   class WebSocket; end
 end

data/lib/ftw/pool.rb

@@ -44,7 +44,12 @@ class FTW::Pool
       return object if !object.nil?
     end
     # Otherwise put the return value of default_block in the
-    # pool and return it.
-    return add(identifier, default_block.call)
+    # pool and return it, but don't put nil values in the pool.
+    obj = default_block.call
+    if obj.nil?
+      return nil
+    else
+      return add(identifier, obj)
+    end
   end # def fetch
 end # class FTW::Pool

data/lib/ftw/protocol.rb

@@ -0,0 +1,60 @@
+require "ftw/namespace"
+require "cabin"
+require "logger"
+
+# This module provides web protocol handling as a mixin.
+module FTW::Protocol
+  # Read an HTTP message from a given connection
+  #
+  # This method blocks until a full http message header has been consumed
+  # (request *or* response)
+  #
+  # The body of the message, if any, will not be consumed, and the read
+  # position for the connection will be left at the end of the message headers.
+  # 
+  # The 'connection' object must respond to #read(timeout) and #pushback(string)
+  def read_http_message(connection)
+    parser = HTTP::Parser.new
+    headers_done = false
+    parser.on_headers_complete = proc { headers_done = true; :stop }
+
+    # headers_done will be set to true when parser finishes parsing the http
+    # headers for this request
+    while !headers_done
+      # TODO(sissel): This read could toss an exception of the server aborts
+      # prior to sending the full headers. Figure out a way to make this happy.
+      # Perhaps fabricating a 500 response?
+      data = connection.read(16384)
+
+      # Feed the data into the parser. Offset will be nonzero if there's 
+      # extra data beyond the header.
+      offset = parser << data
+    end
+
+    # If we consumed part of the body while parsing headers, put it back
+    # onto the connection's read buffer so the next consumer can use it.
+    if offset < data.length
+      connection.pushback(data[offset .. -1])
+    end
+
+    # This will have an 'http_method' if it's a request
+    if !parser.http_method.nil?
+      # have http_method, so this is an HTTP Request message
+      request = FTW::Request.new
+      request.method = parser.http_method
+      request.request_uri = parser.request_url
+      request.version = "#{parser.http_major}.#{parser.http_minor}".to_f
+      parser.headers.each { |field, value| request.headers.add(field, value) }
+      return request
+    else
+      # otherwise, no http_method, so this is an HTTP Response message
+      response = FTW::Response.new
+      response.version = "#{parser.http_major}.#{parser.http_minor}".to_f
+      response.status = parser.status_code
+      parser.headers.each { |field, value| response.headers.add(field, value) }
+      return response
+    end
+  end # def read_http_message
+
+  public(:read_http_message)
+end # module FTW::Protocol

data/lib/ftw/request.rb

@@ -4,7 +4,7 @@ require "ftw/crlf"
 require "ftw/http/message"
 require "ftw/namespace"
 require "ftw/response"
-require "http/parser" # gem http_parser.rb
+require "ftw/protocol"
 require "uri" # ruby stdlib
 
 # An HTTP Request.
@@ -12,6 +12,7 @@ require "uri" # ruby stdlib
 # See RFC2616 section 5: <http://tools.ietf.org/html/rfc2616#section-5>
 class FTW::Request
   include FTW::HTTP::Message
+  include FTW::Protocol
   include FTW::CRLF
   include Cabin::Inspectable
 
@@ -82,36 +83,8 @@ class FTW::Request
       end
     end
 
-    # TODO(sissel): Support request a body.
-
-    parser = HTTP::Parser.new
-    headers_done = false
-    parser.on_headers_complete = proc { headers_done = true; :stop }
-
-    # headers_done will be set to true when parser finishes parsing the http
-    # headers for this request
-    while !headers_done
-      # TODO(sissel): This read could toss an exception of the server aborts
-      # prior to sending the full headers. Figure out a way to make this happy.
-      # Perhaps fabricating a 500 response?
-      data = connection.read
-
-      # Feed the data into the parser. Offset will be nonzero if there's 
-      # extra data beyond the header.
-      offset = parser << data
-    end
-
-    # Done reading response header
-    response = FTW::Response.new
-    response.version = "#{parser.http_major}.#{parser.http_minor}".to_f
-    response.status = parser.status_code
-    parser.headers.each { |field, value| response.headers.add(field, value) }
-
-    # If we consumed part of the body while parsing headers, put it back
-    # onto the connection's read buffer so the next consumer can use it.
-    if offset < data.length
-      connection.pushback(data[offset .. -1])
-    end
+    response = read_http_message(connection)
+    # TODO(sissel): make sure we got a response, not a request, cuz that'd be weird.
     return response
   end # def execute
 

data/lib/ftw/server.rb

@@ -0,0 +1,110 @@
+require "ftw/namespace"
+
+# A web server.
+class FTW::Server
+  # This class is raised when an error occurs starting the server sockets.
+  class ServerSetupFailure < StandardError; end
+
+  # This class is raised when an invalid address is given to the server to
+  # listen on.
+  class InvalidAddress < StandardError; end
+
+  private
+
+  # The pattern addresses must match. This is used in FTW::Server#initialize.
+  ADDRESS_RE = /^(.*):([^:]+)$/
+
+  # Create a new server listening on the given addresses
+  #
+  # This method will create, bind, and listen, so any errors during that
+  # process be raised as ServerSetupFailure
+  #
+  # The parameter 'addresses' can be a single string or an array of strings.
+  # These strings MUST have the form "address:port". If the 'address' part
+  # is missing, it is assumed to be 0.0.0.0
+  def initialize(addresses)
+    addresses = [addresses] if !addresses.is_a?(Array)
+    dns = FTW::DNS.singleton
+
+    @sockets = {}
+
+    failures = []
+    # address format is assumed to be 'host:port'
+    # TODO(sissel): The split on ":" breaks ipv6 addresses, yo.
+    addresses.each do |address|
+      m = ADDRESS_RE.match(address)
+      if !m
+        raise InvalidAddress.new("Invalid address #{address.inspect}, spected string with format 'host:port'")
+      end
+      host, port = m[1..2] # first capture is host, second capture is port
+
+      # Permit address being simply ':PORT'
+      host = "0.0.0.0" if host.nil?
+
+      # resolve each hostname, use the first one that successfully binds.
+      local_failures = []
+      dns.resolve(host).each do |ip|
+        #family = ip.include?(":") ? Socket::AF_INET6 : Socket::AF_INET
+        #socket = Socket.new(family, Socket::SOCK_STREAM, 0)
+        #sockaddr = Socket.pack_sockaddr_in(port, ip)
+        socket = TCPServer.new(ip, port)
+        #begin
+          #socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+          #socket.bind(sockaddr)
+          # If we get here, bind was successful
+        #rescue Errno::EADDRNOTAVAIL => e
+          # TODO(sissel): Record this failure.
+          #local_failures << "Could not bind to #{ip}:#{port}, address not available on this system."
+          #next
+        #rescue Errno::EACCES
+          # TODO(sissel): Record this failure.
+          #local_failures << "No permission to bind to #{ip}:#{port}: #{e.inspect}"
+          #next
+        #end
+
+        begin
+          socket.listen(100)
+        rescue Errno::EADDRINUSE
+          local_failures << "Address in use, #{ip}:#{port}, cannot listen."
+          next
+        end
+
+        # Break when successfully listened
+        p :accept? => socket.respond_to?(:accept)
+        @sockets["#{host}(#{ip}):#{port}"] = socket
+        local_failures.clear
+        break
+      end
+      failures += local_failures
+    end
+
+    # Abort if there were failures
+    raise ServerSetupFailure.new(failures) if failures.any?
+  end # def initialize
+
+  # Close the server sockets
+  def close
+    @sockets.each do |name, socket|
+      socket.close
+    end
+  end # def close
+
+  # Yield FTW::Connection instances to the block as clients connect.
+  def each_connection(&block)
+    # TODO(sissel): Select on all sockets
+    # TODO(sissel): Accept and yield to the block
+    while true
+      sockets = @sockets.values
+      read, write, error = IO.select(sockets, nil, nil, nil)
+      read.each do |serversocket|
+        p serversocket.methods.sort
+        socket, addrinfo = serversocket.accept
+        connection = FTW::Connection.from_io(socket)
+        yield connection
+      end
+    end
+  end # def each_connection
+
+  public(:initialize, :close, :each_connection)
+end # class FTW::Server
+

data/lib/ftw/singleton.rb

@@ -0,0 +1,13 @@
+require "ftw/namespace"
+
+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
+
+  def singleton
+    @instance ||= self.new
+    return @instance
+  end # def self.singleton
+end # module FTW::Singleton
+

data/lib/ftw/version.rb

@@ -1,5 +1,7 @@
 require "ftw/namespace"
 
+# :nodoc:
 module FTW
-  VERSION = "0.0.6"
+  # The version of this library
+  VERSION = "0.0.7"
 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/websocket/writer"
 require "ftw/crlf"
 
 # WebSockets, RFC6455.
@@ -16,17 +17,20 @@ class FTW::WebSocket
   include FTW::CRLF
   include Cabin::Inspectable
 
+  # The frame identifier for a 'text' frame
   TEXTFRAME = 0x0001
 
+  # Search RFC6455 for this string and you will find its definitions.
+  # It is used in servers accepting websocket upgrades.
   WEBSOCKET_ACCEPT_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
 
-  private
-
   # Protocol phases
   # 1. tcp connect
   # 2. http handshake (RFC6455 section 4)
   # 3. websocket protocol
 
+  private
+
   # Creates a new websocket and fills in the given http request with any
   # necessary settings.
   def initialize(request)
@@ -115,75 +119,18 @@ class FTW::WebSocket
   # The text payload of each message will be yielded to the block.
   def each(&block)
     loop do
-      payload = @parser.feed(@connection.read)
-      next if payload.nil?
-      yield payload
+      @parser.feed(@connection.read(16384)) do |payload|
+        yield payload
+      end
     end
   end # def each
 
-  # Implement masking as described by http://tools.ietf.org/html/rfc6455#section-5.3
-  # Basically, we take a 4-byte random string and use it, round robin, to XOR
-  # every byte. Like so:
-  #   message[0] ^ key[0]
-  #   message[1] ^ key[1]
-  #   message[2] ^ key[2]
-  #   message[3] ^ key[3]
-  #   message[4] ^ key[0]
-  #   ...
-  def mask(message, key)
-    masked = []
-    mask_bytes = key.unpack("C4")
-    i = 0
-    message.each_byte do |byte|
-      masked << (byte ^ mask_bytes[i % 4])
-      i += 1
-    end
-    return masked.pack("C*")
-  end # def mask
-
   # Publish a message text.
   #
   # This will send a websocket text frame over the connection.
   def publish(message)
-    # TODO(sissel): Support server and client modes.
-    # Server MUST NOT mask. Client MUST mask.
-    #
-    #     0                   1                   2                   3
-    #     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
-    #    +-+-+-+-+-------+-+-------------+-------------------------------+
-    #    |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
-    #    |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
-    #    |N|V|V|V|       |S|             |   (if payload len==126/127)   |
-    #    | |1|2|3|       |K|             |                               |
-    #    +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
-    #    |     Extended payload length continued, if payload len == 127  |
-    #    + - - - - - - - - - - - - - - - +-------------------------------+
-    #    |                               |Masking-key, if MASK set to 1  |
-    #    +-------------------------------+-------------------------------+
-    #    | Masking-key (continued)       |          Payload Data         |
-    #    +-------------------------------- - - - - - - - - - - - - - - - +
-    #    :                     Payload Data continued ...                :
-    #    + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
-    #    |                     Payload Data continued ...                |
-    #    +---------------------------------------------------------------+
-    # TODO(sissel): Support 'fin' flag
-    # Set 'fin' flag and opcode of 'text frame' 
-    length = message.length
-    mask_key = [rand(1 << 32)].pack("Q")
-    if message.length >= (1 << 16)
-      pack = "CCSA4A*" # flags+opcode, mask+len, 2-byte len, payload
-      data = [ 0x80 | TEXTFRAME, 0x80 | 126, message.length, mask_key, mask(message, mask_key) ]
-      @connection.write(data.pack(pack))
-    elsif message.length >= (1 << 7)
-      length = 126
-      pack = "CCQA4A*" # flags+opcode, mask+len, 8-byte len, payload
-      data = [ 0x80 | TEXTFRAME, 0x80 | 127, message.length, mask_key, mask(message, mask_key) ]
-      @connection.write(data.pack(pack))
-    else
-      data = [ 0x80 | TEXTFRAME, 0x80 | message.length, mask_key, mask(message, mask_key) ]
-      pack = "CCA4A*" # flags+opcode, mask+len, payload
-      @connection.write(data.pack(pack))
-    end
+    writer = FTW::WebSocket::Writer.singleton
+    writer.write_text(@connection, message)
   end # def publish
 
   public(:initialize, :connection=, :handshake_ok?, :each, :publish)

data/lib/ftw/websocket/constants.rb

@@ -0,0 +1,28 @@
+
+# The UUID comes from: 
+# http://tools.ietf.org/html/rfc6455#page-23
+#
+# The opcode definitions come from:
+# http://tools.ietf.org/html/rfc6455#section-11.8
+module FTW::WebSocket::Constants
+  WEBSOCKET_ACCEPT_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+  # Indication that this frame is a continuation in a fragmented message
+  # See RFC6455 page 33.
+  OPCODE_CONTINUATION = 0
+
+  # Indication that this frame contains a text message
+  OPCODE_TEXT = 1
+
+  # Indication that this frame contains a binary message
+  OPCODE_BINARY = 2
+
+  # Indication that this frame is a 'connection close' message
+  OPCODE_CLOSE = 8
+
+  # Indication that this frame is a 'ping' message
+  OPCODE_PING = 9
+
+  # Indication that this frame is a 'pong' message
+  OPCODE_PONG = 10
+end # module FTW::WebSocket::Constants