websocket-driver 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+### 0.0.0 / 2013-04-22
+
+* First release
+* Proof of concept for people to try out
+* Might be unstable
+

data/README.md

@@ -0,0 +1,266 @@
+# websocket-driver [![Build Status](https://travis-ci.org/faye/websocket-driver-ruby.png)](https://travis-ci.org/faye/websocket-driver-ruby)
+
+This module provides a complete implementation of the WebSocket protocols that
+can be hooked up to any TCP library. It aims to simplify things by decoupling
+the protocol details from the I/O layer, such that users only need to implement
+code to stream data in and out of it without needing to know anything about how
+the protocol actually works. Think of it as a complete WebSocket system with
+pluggable I/O.
+
+Due to this design, you get a lot of things for free. In particular, if you
+hook this module up to some I/O object, it will do all of this for you:
+
+* Select the correct server-side driver to talk to the client
+* Generate and send both server- and client-side handshakes
+* Recognize when the handshake phase completes and the WS protocol begins
+* Negotiate subprotocol selection based on `Sec-WebSocket-Protocol`
+* Buffer sent messages until the handshake process is finished
+* Deal with proxies that defer delivery of the draft-76 handshake body
+* Notify you when the socket is open and closed and when messages arrive
+* Recombine fragmented messages
+* Dispatch text, binary, ping and close frames
+* Manage the socket-closing handshake process
+* Automatically reply to ping frames with a matching pong
+* Apply masking to messages sent by the client
+
+This library was originally extracted from the [Faye](http://faye.jcoglan.com)
+project but now aims to provide simple WebSocket support for any Ruby server or
+I/O system.
+
+
+## Installation
+
+```
+$ gem install websocket-driver
+```
+
+
+## Usage
+
+To build either a server-side or client-side socket, the only requirement is
+that you supply a `socket` object with these methods:
+
+* `socket.url` - returns the full URL of the socket as a string.
+* `socket.write(string)` - writes the given string to a TCP stream.
+
+Server-side sockets require one additional method:
+
+* `socket.env` - returns a Rack-style env hash that will contain some of the
+  following fields. Their values are strings containing the value of the named
+  header, unless stated otherwise.
+  * `HTTP_CONNECTION`
+  * `HTTP_HOST`
+  * `HTTP_ORIGIN`
+  * `HTTP_SEC_WEBSOCKET_KEY`
+  * `HTTP_SEC_WEBSOCKET_KEY1`
+  * `HTTP_SEC_WEBSOCKET_KEY2`
+  * `HTTP_SEC_WEBSOCKET_PROTOCOL`
+  * `HTTP_SEC_WEBSOCKET_VERSION`
+  * `HTTP_UPGRADE`
+  * `rack.input`, an `IO` object representing the request body
+  * `REQUEST_METHOD`, the request's HTTP verb
+
+
+### Server-side
+
+To handle a server-side WebSocket connection, you need to check whether the
+request is a WebSocket handshake, and if so create a protocol driver for it.
+You must give the driver an object with the `env`, `url` and `write` methods.
+A simple example might be:
+
+```ruby
+require 'websocket/driver'
+require 'eventmachine'
+
+class WS
+  attr_reader :env, :url
+
+  def initialize(env)
+    @env = env
+
+    secure = Rack::Request.new(env).ssl?
+    scheme = secure ? 'wss:' : 'ws:'
+    @url = scheme + '//' + env['HTTP_HOST'] + env['REQUEST_URI']
+
+    @driver = WebSocket::Driver.rack(self)
+
+    env['rack.hijack'].call
+    @io = env['rack.hijack_io']
+
+    EM.attach(@io, Reader) { |conn| conn.driver = @driver }
+
+    @driver.start
+  end
+
+  def write(string)
+    @io.write(string)
+  end
+
+  module Reader
+    attr_writer :driver
+
+    def receive_data(string)
+      @driver.parse(string)
+    end
+  end
+end
+```
+
+To explain what's going on here: the `WS` class implements the `env`, `url` and
+`write(string)` methods as required. When instantiated with a Rack environment,
+it stores the environment and infers the complete URL from it.  Having set up
+the `env` and `url`, it asks `WebSocket::Driver` for a server-side driver for
+the socket. Then it uses the Rack hijack API to gain access to the TCP stream,
+and uses EventMachine to stream in incoming data from the client, handing
+incoming data off to the driver for parsing. Finally, we tell the driver to
+`start`, which will begin sending the handshake response.  This will invoke the
+`WS#write` method, which will send the response out over the TCP socket.
+
+Having defined this class we could use it like this when handling a request:
+
+```ruby
+if WebSocket::Driver.websocket?(env)
+  socket = WS.new(env)
+end
+```
+
+The driver API is described in full below.
+
+
+### Client-side
+
+Similarly, to implement a WebSocket client you need an object with `url` and
+`write` methods. Once you have one such object, you ask for a driver for it:
+
+```ruby
+driver = WebSocket::Driver.client(socket)
+```
+
+After this you use the driver API as described below to process incoming data
+and send outgoing data.
+
+
+### Driver API
+
+Drivers are created using one of the following methods:
+
+```ruby
+driver = WebSocket::Driver.rack(socket, options)
+driver = WebSocket::Driver.client(socket, options)
+```
+
+The `rack` method returns a driver chosen using the socket's `env`. The
+`client` method always returns a driver for the RFC version of the protocol
+with masking enabled on outgoing frames.
+
+The `options` argument is optional, and is a hash. It may contain the following
+keys:
+
+* `:protocols` - an array of strings representing acceptable subprotocols for
+  use over the socket. The driver will negotiate one of these to use via the
+  `Sec-WebSocket-Protocol` header if supported by the other peer.
+
+All drivers respond to the following API methods, but some of them are no-ops
+depending on whether the client supports the behaviour.
+
+Note that most of these methods are commands: if they produce data that should
+be sent over the socket, they will give this to you by calling
+`socket.write(string)`.
+
+#### `driver.on('open') { |event| }`
+
+Sets the callback block to execute when the socket becomes open.
+
+#### `driver.on('message') { |event| }`
+
+Sets the callback block to execute when a message is received. `event` will
+have a `data` attribute containing either a string in the case of a text
+message or an array of integers in the case of a binary message.
+
+#### `driver.on('error') { |event| }`
+
+Sets the callback to execute when a protocol error occurs due to the other peer
+sending an invalid byte sequence. `event` will have a `message` attribute
+describing the error.
+
+#### `driver.on('close') { |event| }`
+
+Sets the callback block to execute when the socket becomes closed. The `event`
+object has `code` and `reason` attributes.
+
+#### `driver.start`
+
+Initiates the protocol by sending the handshake - either the response for a
+server-side driver or the request for a client-side one. This should be the
+first method you invoke.  Returns `true` iff a handshake was sent.
+
+#### `driver.parse(string)`
+
+Takes a string and parses it, potentially resulting in message events being
+emitted (see `on('message')` above) or in data being sent to `socket.write`.
+You should send all data you receive via I/O to this method.
+
+#### `driver.text(string)`
+
+Sends a text message over the socket. If the socket handshake is not yet
+complete, the message will be queued until it is. Returns `true` if the message
+was sent or queued, and `false` if the socket can no longer send messages.
+
+#### `driver.binary(array)`
+
+Takes an array of byte-sized integers and sends them as a binary message. Will
+queue and return `true` or `false` the same way as the `text` method. It will
+also return `false` if the driver does not support binary messages.
+
+#### `driver.ping(string = '', &callback)`
+
+Sends a ping frame over the socket, queueing it if necessary. `string` and the
+`callback` block are both optional. If a callback is given, it will be invoked
+when the socket receives a pong frame whose content matches `string`. Returns
+`false` if frames can no longer be sent, or if the driver does not support
+ping/pong.
+
+#### `driver.close`
+
+Initiates the closing handshake if the socket is still open. For drivers with
+no closing handshake, this will result in the immediate execution of the
+`on('close')` callback. For drivers with a closing handshake, this sends a
+closing frame and `emit('close')` will execute when a response is received or a
+protocol error occurs.
+
+#### `driver.version`
+
+Returns the WebSocket version in use as a string. Will either be `hixie-75`,
+`hixie-76` or `hybi-$version`.
+
+#### `driver.protocol`
+
+Returns a string containing the selected subprotocol, if any was agreed upon
+using the `Sec-WebSocket-Protocol` mechanism. This value becomes available
+after `emit('open')` has fired.
+
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2010-2013 James Coglan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the 'Software'), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/ext/websocket_mask/WebsocketMaskService.java

@@ -0,0 +1,61 @@
+package com.jcoglan.websocket;
+
+import java.lang.Long;
+import java.io.IOException;
+
+import org.jruby.Ruby;
+import org.jruby.RubyArray;
+import org.jruby.RubyClass;
+import org.jruby.RubyFixnum;
+import org.jruby.RubyModule;
+import org.jruby.RubyObject;
+import org.jruby.anno.JRubyMethod;
+import org.jruby.runtime.ObjectAllocator;
+import org.jruby.runtime.ThreadContext;
+import org.jruby.runtime.builtin.IRubyObject;
+import org.jruby.runtime.load.BasicLibraryService;
+
+public class WebsocketMaskService implements BasicLibraryService {
+  private Ruby runtime;
+
+  public boolean basicLoad(Ruby runtime) throws IOException {
+    this.runtime = runtime;
+    RubyModule websocket = runtime.defineModule("WebSocket");
+
+    RubyClass webSocketMask = websocket.defineClassUnder("Mask", runtime.getObject(), new ObjectAllocator() {
+      public IRubyObject allocate(Ruby runtime, RubyClass rubyClass) {
+        return new WebsocketMask(runtime, rubyClass);
+      }
+    });
+
+    webSocketMask.defineAnnotatedMethods(WebsocketMask.class);
+    return true;
+  }
+
+  public class WebsocketMask extends RubyObject {
+    public WebsocketMask(final Ruby runtime, RubyClass rubyClass) {
+      super(runtime, rubyClass);
+    }
+
+    @JRubyMethod
+    public IRubyObject mask(ThreadContext context, IRubyObject payload, IRubyObject mask) {
+      int n = ((RubyArray)payload).getLength(), i;
+      long p, m;
+      RubyArray unmasked = RubyArray.newArray(runtime, n);
+
+      long[] maskArray = {
+        (Long)((RubyArray)mask).get(0),
+        (Long)((RubyArray)mask).get(1),
+        (Long)((RubyArray)mask).get(2),
+        (Long)((RubyArray)mask).get(3)
+      };
+
+      for (i = 0; i < n; i++) {
+        p = (Long)((RubyArray)payload).get(i);
+        m = maskArray[i % 4];
+        unmasked.set(i, p ^ m);
+      }
+      return unmasked;
+    }
+  }
+}

data/ext/websocket_mask/extconf.rb

@@ -0,0 +1,5 @@
+require 'mkmf'
+extension_name = 'websocket_mask'
+dir_config(extension_name)
+create_makefile(extension_name)
+

data/ext/websocket_mask/websocket_mask.c

@@ -0,0 +1,33 @@
+#include <ruby.h>
+
+VALUE WebSocket = Qnil;
+VALUE WebSocketMask = Qnil;
+
+void Init_websocket_mask();
+VALUE method_websocket_mask(VALUE self, VALUE payload, VALUE mask);
+
+void Init_websocket_mask() {
+  WebSocket = rb_define_module("WebSocket");
+  WebSocketMask = rb_define_module_under(WebSocket, "Mask");
+  rb_define_singleton_method(WebSocketMask, "mask", method_websocket_mask, 2);
+}
+
+VALUE method_websocket_mask(VALUE self, VALUE payload, VALUE mask) {
+  int n = RARRAY_LEN(payload), i, p, m;
+  VALUE unmasked = rb_ary_new2(n);
+
+  int mask_array[] = {
+    NUM2INT(rb_ary_entry(mask, 0)),
+    NUM2INT(rb_ary_entry(mask, 1)),
+    NUM2INT(rb_ary_entry(mask, 2)),
+    NUM2INT(rb_ary_entry(mask, 3))
+  };
+
+  for (i = 0; i < n; i++) {
+    p = NUM2INT(rb_ary_entry(payload, i));
+    m = mask_array[i % 4];
+    rb_ary_store(unmasked, i, INT2NUM(p ^ m));
+  }
+  return unmasked;
+}
+

data/lib/websocket/driver.rb

@@ -0,0 +1,158 @@
+# Protocol references:
+#
+# * http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75
+# * http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-76
+# * http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17
+
+require 'base64'
+require 'digest/md5'
+require 'digest/sha1'
+require 'net/http'
+require 'stringio'
+require 'uri'
+
+module WebSocket
+  class Driver
+
+    root = File.expand_path('../driver', __FILE__)
+    require root + '/../../websocket_mask'
+
+    if RUBY_PLATFORM =~ /java/
+      require 'jruby'
+      com.jcoglan.websocket.WebsocketMaskService.new.basicLoad(JRuby.runtime)
+    end
+
+    unless Mask.respond_to?(:mask)
+      def Mask.mask(payload, mask)
+        @instance ||= new
+        @instance.mask(payload, mask)
+      end
+    end
+
+    unless String.instance_methods.include?(:force_encoding)
+      require root + '/utf8_match'
+    end
+
+    STATES = [:connecting, :open, :closing, :closed]
+
+    class OpenEvent < Struct.new(nil) ; end
+    class MessageEvent < Struct.new(:data) ; end
+    class CloseEvent < Struct.new(:code, :reason) ; end
+
+    class ProtocolError < StandardError ; end
+
+    autoload :EventEmitter, root + '/event_emitter'
+    autoload :Draft75,      root + '/draft75'
+    autoload :Draft76,      root + '/draft76'
+    autoload :Hybi,         root + '/hybi'
+    autoload :Client,       root + '/client'
+
+    include EventEmitter
+    attr_reader :protocol, :ready_state
+
+    def initialize(socket, options = {})
+      super()
+
+      @socket      = socket
+      @options     = options
+      @queue       = []
+      @ready_state = 0
+    end
+
+    def state
+      return nil unless @ready_state >= 0
+      STATES[@ready_state]
+    end
+
+    def start
+      return false unless @ready_state == 0
+      @socket.write(handshake_response)
+      open unless @stage == -1
+      true
+    end
+
+    def text(message)
+      frame(message)
+    end
+
+    def binary(message)
+      false
+    end
+
+    def ping(*args)
+      false
+    end
+
+    def close(reason = nil, code = nil)
+      return false unless @ready_state == 1
+      @ready_state = 3
+      emit(:close, CloseEvent.new(nil, nil))
+      true
+    end
+
+  private
+
+    def open
+      @ready_state = 1
+      @queue.each { |message| frame(*message) }
+      @queue = []
+      emit(:open, OpenEvent.new)
+    end
+
+    def queue(message)
+      @queue << message
+      true
+    end
+
+    def self.encode(string, validate_encoding = false)
+      if Array === string
+        string = utf8_string(string)
+        return nil if validate_encoding and !valid_utf8?(string)
+      end
+      utf8_string(string)
+    end
+
+    def self.client(socket, options = {})
+      Client.new(socket, options.merge(:masking => true))
+    end
+
+    def self.rack(socket, options = {})
+      env = socket.env
+      if env['HTTP_SEC_WEBSOCKET_VERSION']
+        Hybi.new(socket, options.merge(:require_masking => true))
+      elsif env['HTTP_SEC_WEBSOCKET_KEY1']
+        Draft76.new(socket, options)
+      else
+        Draft75.new(socket, options)
+      end
+    end
+
+    def self.utf8_string(string)
+      string = string.pack('C*') if Array === string
+      string.respond_to?(:force_encoding) ?
+          string.force_encoding('UTF-8') :
+          string
+    end
+
+    def self.valid_utf8?(byte_array)
+      string = utf8_string(byte_array)
+      if defined?(UTF8_MATCH)
+        UTF8_MATCH =~ string ? true : false
+      else
+        string.valid_encoding?
+      end
+    end
+
+    def self.websocket?(env)
+      return false unless env['REQUEST_METHOD'] == 'GET'
+      connection = env['HTTP_CONNECTION'] || ''
+      upgrade    = env['HTTP_UPGRADE']    || ''
+
+      env['REQUEST_METHOD'] == 'GET' and
+      connection.downcase.split(/\s*,\s*/).include?('upgrade') and
+      upgrade.downcase == 'websocket'
+    end
+
+  end
+end
+