ftw 0.0.1 → 0.0.4

data/lib/ftw/version.rb

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

data/lib/ftw/websocket.rb

@@ -0,0 +1,194 @@
+require "ftw/namespace"
+require "openssl"
+require "base64" # stdlib 
+require "digest/sha1" # stdlib
+require "cabin"
+require "ftw/websocket/parser"
+
+# WebSockets, RFC6455.
+#
+# TODO(sissel): Find a comfortable way to make this websocket stuff 
+# both use HTTP::Connection for the HTTP handshake and also be usable
+# from HTTP::Client
+# TODO(sissel): Also consider SPDY and the kittens.
+class FTW::WebSocket
+  include FTW::CRLF
+  include Cabin::Inspectable
+
+  TEXTFRAME = 0x0001
+
+  WEBSOCKET_ACCEPT_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+  # Protocol phases
+  # 1. tcp connect
+  # 2. http handshake (RFC6455 section 4)
+  # 3. websocket protocol
+
+  # 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
+    prepare(@request)
+    @parser = FTW::WebSocket::Parser.new
+  end # def initialize
+
+  # Set the connection for this websocket. This is usually invoked by FTW::Agent
+  # 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
+    #        be at least 1.1."
+    request.method = "GET"
+    request.version = 1.1
+
+    # RFC6455 section 4.2.1 bullet 3
+    request.headers.set("Upgrade", "websocket") 
+    # RFC6455 section 4.2.1 bullet 4
+    request.headers.set("Connection", "Upgrade") 
+    # RFC6455 section 4.2.1 bullet 5
+    request.headers.set("Sec-WebSocket-Key", @key_nonce)
+    # RFC6455 section 4.2.1 bullet 6
+    request.headers.set("Sec-WebSocket-Version", 13)
+    # RFC6455 section 4.2.1 bullet 7 (optional)
+    # The Origin header is optional for non-browser clients.
+    #request.headers.set("Origin", ...)
+    # RFC6455 section 4.2.1 bullet 8 (optional)
+    #request.headers.set("Sec-Websocket-Protocol", ...)
+    # RFC6455 section 4.2.1 bullet 9 (optional)
+    #request.headers.set("Sec-Websocket-Extensions", ...)
+    # RFC6455 section 4.2.1 bullet 10 (optional)
+    # TODO(sissel): Any other headers like cookies, auth headers, are allowed.
+  end # def prepare
+
+  # Generate a websocket key nonce.
+  private
+  def generate_key_nonce
+    # RFC6455 section 4.1 says:
+    # ---
+    # 7.   The request MUST include a header field with the name
+    #      |Sec-WebSocket-Key|.  The value of this header field MUST be a
+    #      nonce consisting of a randomly selected 16-byte value that has
+    #      been base64-encoded (see Section 4 of [RFC4648]).  The nonce
+    #      MUST be selected randomly for each connection.
+    # ---
+    #
+    # It's not totally clear to me how cryptographically strong this random
+    # nonce needs to be, and if it does not need to be strong and it would
+    # benefit users who do not have ruby with openssl enabled, maybe just use
+    # rand() to generate this string.
+    #
+    # Thus, generate a random 16 byte string and encode i with base64.
+    # Array#pack("m") packs with base64 encoding.
+    return Base64.strict_encode64(OpenSSL::Random.random_bytes(16))
+  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"
+    return false unless response.headers.get("upgrade") == "websocket"
+    return false unless response.headers.get("connection") == "Upgrade"
+
+    # Now verify Sec-WebSocket-Accept. It should be the SHA-1 of the
+    # Sec-WebSocket-Key (in base64) + WEBSOCKET_ACCEPT_UUID
+    expected = @key_nonce + WEBSOCKET_ACCEPT_UUID
+    expected_hash = Digest::SHA1.base64digest(expected)
+    return false unless response.headers.get("Sec-WebSocket-Accept") == expected_hash
+
+    return true
+  end # def handshake_ok?
+
+  # Iterate over each WebSocket message. This method will run forever unless you
+  # 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)
+      next if payload.nil?
+      yield payload
+    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]
+  #   ...
+  private
+  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.
+  public
+  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
+  end # def publish
+end # class FTW::WebSocket
+

data/lib/ftw/websocket/parser.rb

@@ -0,0 +1,183 @@
+require "ftw/namespace"
+require "ftw/websocket"
+
+# This class implements a parser for WebSocket messages over a stream.
+#
+# Protocol diagram copied from RFC6455
+#     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 ...                |
+#    +---------------------------------------------------------------+
+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 ]
+
+  # A new WebSocket protocol parser.
+  def initialize
+    @logger = Cabin::Channel.get($0)
+    @opcode = 0
+    @masking_key = ""
+    @flag_final_payload = 0
+    @flag_mask = 0
+
+    transition(:flags_and_opcode, 1)
+    @buffer = ""
+    @buffer.force_encoding("BINARY")
+  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
+    need(next_length)
+  end # def transition
+
+  # Feed data to this parser.
+  # 
+  # Currently, it will return the raw payload of websocket messages.
+  # Otherwise, it returns nil if no complete message has yet been consumed.
+  public
+  def feed(data)
+    @buffer << data
+    while have?(@need)
+      value = send(@state)
+      # Return if our state yields a value.
+      return value if !value.nil?
+      #yield value if !value.nil? and block_given?
+    end
+    return nil
+  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]
+    @buffer = @buffer[length .. -1]
+    return data
+  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
+    #    +-+-+-+-+-------
+    #    |F|R|R|R| opcode
+    #    |I|S|S|S|  (4)  
+    #    |N|V|V|V|       
+    #    | |1|2|3|       
+    byte = get.bytes.first
+    @opcode = byte & 0xF # last 4 bites
+    @fin = (byte & 0x80 == 0x80)# first bit
+
+    #p :byte => byte, :bits => byte.to_s(2), :opcode => @opcode, :fin => @fin
+    # mask_and_payload_length has a minimum length
+    # of 1 byte, so start there.
+    transition(:mask_and_payload_init, 1)
+
+    # This state yields no output.
+    return nil
+  end # def flags_and_opcode
+
+  # 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)
+    @payload_length = byte & 0x7F # remaining bits are the length
+    case @payload_length
+      when 126 # 2 byte, unsigned value is the payload length
+        transition(:extended_payload_length, 2)
+      when 127 # 8 byte, unsigned value is the payload length
+        transition(:extended_payload_length, 8)
+      else
+        # Keep the current payload length, a 7 bit value.
+        # Go to read the payload
+        transition(:payload, @payload_length)
+    end # case @payload_length
+
+    # This state yields no output.
+    return nil
+  end # def mask_and_payload_init
+
+  # State: payload_length
+  # 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
+    #    +-+-+-+-+-------+-+-------------+-------------------------------+
+    #    |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  |
+    #    +-------------------------------+-------------------------------+
+    data = get
+    case @need
+      when 2
+        @payload_length = data.unpack("S")
+      when 8
+        @payload_length = data.unpack("Q")
+      else
+        raise "Unknown payload_length byte length '#{@need}'"
+    end
+
+    transition(:payload, @payload_length)
+
+    # This state yields no output.
+    return nil
+  end # def payload_length
+
+  # State: payload
+  # 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),
+    # instead of returning the whole thing, simply return an Enumerable that
+    # yields chunks of the payload. There's no reason to buffer the entire
+    # thing. Have the consumer of this library make that decision.
+    data = get(@need)
+    transition(:flags_and_opcode, 1)
+    return data
+  end # def payload
+end # class FTW::WebSocket::Parser

data/test/all.rb

@@ -0,0 +1,16 @@
+require "rubygems"
+require "minitest/spec"
+require "minitest/autorun"
+
+# Get coverage report
+require "simplecov"
+SimpleCov.start
+
+# Add '../lib' to the require path.
+$: << File.join(File.dirname(__FILE__), "..", "lib")
+
+glob = File.join(File.dirname(__FILE__), "ftw", "**", "*.rb")
+Dir.glob(glob).each do |path|
+  puts "Loading tests from #{path}"
+  require File.expand_path(path)
+end

data/test/ftw/crlf.rb

@@ -0,0 +1,12 @@
+require File.join(File.expand_path(__FILE__).sub(/\/ftw\/.*/, "/testing"))
+require "ftw/crlf"
+
+describe FTW::CRLF do
+  test "CRLF is as expected" do
+    class Foo
+      include FTW::CRLF
+    end
+
+    assert_equal("\r\n", Foo::CRLF)
+  end
+end

data/test/ftw/http/dns.rb

@@ -0,0 +1,6 @@
+require File.join(File.expand_path(__FILE__).sub(/\/ftw\/.*/, "/testing"))
+require "ftw/dns"
+
+describe FTW::DNS do
+  # TODO(sissel): mock Socket.gethostbyname?
+end

data/test/{net/ftw → ftw}/http/headers.rb

@@ -1,9 +1,9 @@
-require File.join(File.expand_path(__FILE__).sub(/\/net\/ftw\/.*/, "/testing"))
-require "net/ftw/http/headers"
+require File.join(File.expand_path(__FILE__).sub(/\/ftw\/.*/, "/testing"))
+require "ftw/http/headers"
 
-describe Net::FTW::HTTP::Headers do
+describe FTW::HTTP::Headers do
   before do
-    @headers = Net::FTW::HTTP::Headers.new
+    @headers = FTW::HTTP::Headers.new
   end
 
   test "add adds" do
@@ -47,4 +47,4 @@ describe Net::FTW::HTTP::Headers do
     @headers.remove("foo", "two")
     assert_equal("one", @headers.get("foo"))
   end
-end # describe Net::FTW::HTTP::Headers
+end # describe FTW::HTTP::Headers

data/test/testing.rb

@@ -1,6 +1,5 @@
 require "rubygems"
 require "minitest/spec"
-require "minitest/autorun"
 
 # Add '../lib' to the require path.
 $: << File.join(File.dirname(__FILE__), "..", "lib")
@@ -13,11 +12,3 @@ class MiniTest::Spec
     alias :test :it
   end
 end
-
-if __FILE__ == $0
-  glob = File.join(File.dirname(__FILE__), "net", "**", "*.rb")
-  Dir.glob(glob).each do |path|
-    puts "Loading tests from #{path}"
-    require File.expand_path(path)
-  end
-end