websocket-extensions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b1c44128d3db51c789832e4c9c8a69f23dd8b477
+  data.tar.gz: 5214cf7259a10a9a6d252b4fa6febaf75d8d8727
+SHA512:
+  metadata.gz: 0f2189d6fae9bad78b6b5ec275f17435b09345e3113416b0ae2196d262e91ac20e20928a7692d2b448a7a6dac35a4db0091a1214538d50c24d0a25259e2e169c
+  data.tar.gz: fdba7d6246380d2088c62837e6ffc84164d188f9d7c0e0a04d00412be766429ed5aca7382c7b8273f1c0f317fdca1d4d6ab5f158f66728d92dc46e80fcbee587

data/README.md

@@ -0,0 +1,337 @@
+# websocket-extensions [![Build status](https://secure.travis-ci.org/faye/websocket-extensions-ruby.svg)](http://travis-ci.org/faye/websocket-extensions-ruby)
+
+A minimal framework that supports the implementation of WebSocket extensions in
+a way that's decoupled from the main protocol. This library aims to allow a
+WebSocket extension to be written and used with any protocol library, by
+defining abstract representations of frames and messages that allow modules to
+co-operate.
+
+`websocket-extensions` provides a container for registering extension plugins,
+and provides all the functions required to negotiate which extensions to use
+during a session via the `Sec-WebSocket-Extensions` header. By implementing the
+APIs defined in this document, an extension may be used by any WebSocket library
+based on this framework.
+
+## Installation
+
+```
+$ gem install websocket-extensions
+```
+
+## Usage
+
+There are two main audiences for this library: authors implementing the
+WebSocket protocol, and authors implementing extensions. End users of a
+WebSocket library or an extension should be able to use any extension by passing
+it as an argument to their chosen protocol library, without needing to know how
+either of them work, or how the `websocket-extensions` framework operates.
+
+The library is designed with the aim that any protocol implementation and any
+extension can be used together, so long as they support the same abstract
+representation of frames and messages.
+
+### Data types
+
+The APIs provided by the framework rely on two data types; extensions will
+expect to be given data and to be able to return data in these formats:
+
+#### *Frame*
+
+*Frame* is a structure representing a single WebSocket frame of any type. Frames
+are simple objects that must have at least the following properties, which
+represent the data encoded in the frame:
+
+| property      | description                                                        |
+| ------------  | ------------------------------------------------------------------ |
+| `final`       | `true` if the `FIN` bit is set, `false` otherwise                  |
+| `rsv1`        | `true` if the `RSV1` bit is set, `false` otherwise                 |
+| `rsv2`        | `true` if the `RSV2` bit is set, `false` otherwise                 |
+| `rsv3`        | `true` if the `RSV3` bit is set, `false` otherwise                 |
+| `opcode`      | the numeric opcode (`0`, `1`, `2`, `8`, `9`, or `10`) of the frame |
+| `masked`      | `true` if the `MASK` bit is set, `false` otherwise                 |
+| `masking_key` | a 4-byte string if `masked` is `true`, otherwise `nil`             |
+| `payload`     | a string containing the (unmasked) application data                |
+
+#### *Message*
+
+A *Message* represents a complete application message, which can be formed from
+text, binary and continuation frames. It has the following properties:
+
+| property | description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| `rsv1`   | `true` if the first frame of the message has the `RSV1` bit set   |
+| `rsv2`   | `true` if the first frame of the message has the `RSV2` bit set   |
+| `rsv3`   | `true` if the first frame of the message has the `RSV3` bit set   |
+| `opcode` | the numeric opcode (`1` or `2`) of the first frame of the message |
+| `data`   | the concatenation of all the frame payloads in the message        |
+
+### For driver authors
+
+A driver author is someone implementing the WebSocket protocol proper, and who
+wishes end users to be able to use WebSocket extensions with their library.
+
+At the start of a WebSocket session, on both the client and the server side,
+they should begin by creating an extension container and adding whichever
+extensions they want to use.
+
+```rb
+require 'websocket/extensions'
+require 'permessage_deflate'
+
+exts = WebSocket::Extensions.new
+exts.add(PermessageDeflate)
+```
+
+In the following examples, `exts` refers to this `Extensions` instance.
+
+#### Client sessions
+
+Clients will use the methods `generate_offer` and `activate(header)`.
+
+As part of the handshake process, the client must send a
+`Sec-WebSocket-Extensions` header to advertise that it supports the registered
+extensions. This header should be generated using:
+
+```rb
+request_headers['Sec-WebSocket-Extensions'] = exts.generate_offer
+```
+
+This returns a string, for example `"permessage-deflate;
+client_max_window_bits"`, that represents all the extensions the client is
+offering to use, and their parameters. This string may contain multiple offers
+for the same extension.
+
+When the client receives the handshake response from the server, it should pass
+the incoming `Sec-WebSocket-Extensions` header in to `exts` to activate the
+extensions the server has accepted:
+
+```rb
+exts.activate(response_headers['Sec-WebSocket-Extensions'])
+```
+
+If the server has sent any extension responses that the client does not
+recognize, or are in conflict with one another for use of RSV bits, or that use
+invalid parameters for the named extensions, then `exts.activate` will `raise`.
+In this event, the client driver should fail the connection with closing code
+`1010`.
+
+#### Server sessions
+
+Servers will use the method `generate_response(header)`.
+
+A server session needs to generate a `Sec-WebSocket-Extensions` header to send
+in its handshake response:
+
+```rb
+client_offer = request_env['HTTP_SEC_WEBSOCKET_EXTENSIONS']
+ext_response = exts.generate_response(client_offer)
+
+response_headers['Sec-WebSocket-Extensions'] = ext_response
+```
+
+Calling `exts.generate_response(header)` activates those extensions the client
+has asked to use, if they are registered, asks each extension for a set of
+response parameters, and returns a string containing the response parameters for
+all accepted extensions.
+
+#### In both directions
+
+Both clients and servers will use the methods `valid_frame_rsv(frame)`,
+`process_incoming_message(message)` and `process_outgoing_message(message)`.
+
+The WebSocket protocol requires that frames do not have any of the `RSV` bits
+set unless there is an extension in use that allows otherwise. When processing
+an incoming frame, sessions should pass a *Frame* object to:
+
+```rb
+exts.valid_frame_rsv(frame)
+```
+
+If this method returns `false`, the session should fail the WebSocket connection
+with closing code `1002`.
+
+To pass incoming messages through the extension stack, a session should
+construct a *Message* object according to the above datatype definitions, and
+call:
+
+```rb
+message = exts.process_incoming_message(message)
+```
+
+If any extensions fail to process the message, then this call will `raise` an
+error and the session should fail the WebSocket connection with closing code
+`1010`. Otherwise, `message` should be passed on to the application.
+
+To pass outgoing messages through the extension stack, a session should
+construct a *Message* as before, and call:
+
+```rb
+message = exts.process_outgoing_message(message)
+```
+
+If any extensions fail to process the message, then this call will `raise` an
+error and the session should fail the WebSocket connection with closing code
+`1010`. Otherwise, `message` should be converted into frames (with the message's
+`rsv1`, `rsv2`, `rsv3` and `opcode` set on the first frame) and written to the
+transport.
+
+At the end of the WebSocket session (either when the protocol is explicitly
+ended or the transport connection disconnects), the driver should call:
+
+```rb
+exts.close
+```
+
+### For extension authors
+
+An extension author is someone implementing an extension that transforms
+WebSocket messages passing between the client and server. They would like to
+implement their extension once and have it work with any protocol library.
+
+Extension authors will not install `websocket-extensions` or call it directly.
+Instead, they should implement the following API to allow their extension to
+plug into the `websocket-extensions` framework.
+
+An `Extension` is any object that has the following properties:
+
+| property | description                                                                  |
+| -------- | ---------------------------------------------------------------------------- |
+| `name`   | a string containing the name of the extension as used in negotiation headers |
+| `type`   | a string, must be `"permessage"`                                             |
+| `rsv1`   | either `true` if the extension uses the RSV1 bit, `false` otherwise          |
+| `rsv2`   | either `true` if the extension uses the RSV2 bit, `false` otherwise          |
+| `rsv3`   | either `true` if the extension uses the RSV3 bit, `false` otherwise          |
+
+It must also implement the following methods:
+
+```rb
+ext.create_client_session
+```
+
+This returns a *ClientSession*, whose interface is defined below.
+
+```rb
+ext.create_server_session(offers)
+```
+
+This takes an array of offer params and returns a *ServerSession*, whose
+interface is defined below. For example, if the client handshake contains the
+offer header:
+
+```
+Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
+                          permessage-deflate; server_max_window_bits=15
+```
+
+then the `permessage-deflate` extension will receive the call:
+
+```rb
+ext.create_server_session([
+  {'server_no_context_takeover' => true, 'server_max_window_bits' => 8},
+  {'server_max_window_bits' => 15}
+])
+```
+
+The extension must decide which set of parameters it wants to accept, if any,
+and return a *ServerSession* if it wants to accept the parameters and `nil`
+otherwise.
+
+#### *ClientSession*
+
+A *ClientSession* is the type returned by `ext.create_client_session`. It must
+implement the following methods, as well as the *Session* API listed below.
+
+```rb
+client_session.generate_offer
+# e.g.  -> [
+#            {'server_no_context_takeover' => true, 'server_max_window_bits' => 8},
+#            {'server_max_window_bits' => 15}
+#          ]
+```
+
+This must return a set of parameters to include in the client's
+`Sec-WebSocket-Extensions` offer header. If the session wants to offer multiple
+configurations, it can return an array of sets of parameters as shown above.
+
+```rb
+client_session.activate(params) # -> true
+```
+
+This must take a single set of parameters from the server's handshake response
+and use them to configure the client session. If the client accepts the given
+parameters, then this method must return `true`. If it returns any other value,
+the framework will interpret this as the client rejecting the response, and will
+`raise`.
+
+#### *ServerSession*
+
+A *ServerSession* is the type returned by `ext.create_server_session(offers)`. It
+must implement the following methods, as well as the *Session* API listed below.
+
+```rb
+server_session.generate_response
+# e.g.  -> {'server_max_window_bits' => 8}
+```
+
+This returns the set of parameters the server session wants to send in its
+`Sec-WebSocket-Extensions` response header. Only one set of parameters is
+returned to the client per extension. Server sessions that would confict on
+their use of RSV bits are not activated.
+
+#### *Session*
+
+The *Session* API must be implemented by both client and server sessions. It
+contains three methods: `process_incoming_message(message)` and
+`process_outgoing_message(message)`.
+
+```rb
+message = session.process_incoming_message(message)
+```
+
+The session must implement this method to take an incoming *Message* as defined
+above, transform it in any way it needs, then return it. If there is an error
+processing the message, this method should `raise` an error.
+
+```rb
+message = session.process_outgoing_message(message)
+```
+
+The session must implement this method to take an outgoing *Message* as defined
+above, transform it in any way it needs, then return it. If there is an error
+processing the message, this method should `raise` an error.
+
+```rb
+session.close
+```
+
+The framework will call this method when the WebSocket session ends, allowing
+the session to release any resources it's using.
+
+## Examples
+
+* Consumer: [websocket-driver](https://github.com/faye/websocket-driver-ruby)
+* Provider: [permessage-deflate](https://github.com/faye/permessage-deflate-ruby)
+
+## License
+
+(The MIT License)
+
+Copyright (c) 2014 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/lib/websocket/extensions.rb

@@ -0,0 +1,179 @@
+module WebSocket
+  class Extensions
+
+    autoload :Parser, File.expand_path('../extensions/parser', __FILE__)
+
+    ExtensionError = Class.new(ArgumentError)
+
+    MESSAGE_OPCODES = [1, 2]
+
+    def initialize
+      @rsv1 = @rsv2 = @rsv3 = nil
+
+      @by_name  = {}
+      @in_order = []
+      @sessions = []
+      @index    = {}
+    end
+
+    def add(ext)
+      unless ext.respond_to?(:name) and ext.name.is_a?(String)
+        raise TypeError, 'extension.name must be a string'
+      end
+
+      unless ext.respond_to?(:type) and ext.type == 'permessage'
+        raise TypeError, 'extension.type must be "permessage"'
+      end
+
+      unless ext.respond_to?(:rsv1) and [true, false].include?(ext.rsv1)
+        raise TypeError, 'extension.rsv1 must be true or false'
+      end
+
+      unless ext.respond_to?(:rsv2) and [true, false].include?(ext.rsv2)
+        raise TypeError, 'extension.rsv2 must be true or false'
+      end
+
+      unless ext.respond_to?(:rsv3) and [true, false].include?(ext.rsv3)
+        raise TypeError, 'extension.rsv3 must be true or false'
+      end
+
+      if @by_name.has_key?(ext.name)
+        raise TypeError, %Q{An extension with name "#{ext.name}" is already registered}
+      end
+
+      @by_name[ext.name] = ext
+      @in_order.push(ext)
+    end
+
+    def generate_offer
+      sessions = []
+      offer    = []
+      index    = {}
+
+      @in_order.each do |ext|
+        session = ext.create_client_session
+        next unless session
+
+        record = [ext, session]
+        sessions.push(record)
+        index[ext.name] = record
+
+        offers = session.generate_offer
+        offers = offers ? [offers].flatten : []
+
+        offers.each do |off|
+          offer.push(Parser.serialize_params(ext.name, off))
+        end
+      end
+
+      @sessions = sessions
+      @index    = index
+
+      offer.size > 0 ? offer.join(', ') : nil
+    end
+
+    def activate(header)
+      responses = Parser.parse_header(header)
+      @sessions = []
+
+      responses.each_offer do |name, params|
+        unless record = @index[name]
+          raise ExtensionError, %Q{Server sent am extension response for unknown extension "#{name}"}
+        end
+
+        ext, session = *record
+
+        if reserved = reserved?(ext)
+          raise ExtensionError, %Q{Server sent two extension responses that use the RSV#{reserved[0]} } +
+                               %Q{ bit: "#{reserved[1]}" and "#{ext.name}"}
+        end
+
+        unless session.activate(params) == true
+          raise ExtensionError, %Q{Server send unacceptable extension parameters: #{Parser.serialize_params(name, params)}}
+        end
+
+        reserve(ext)
+        @sessions.push(record)
+      end
+    end
+
+    def generate_response(header)
+      offers   = Parser.parse_header(header)
+      sessions = []
+      response = []
+
+      @in_order.each do |ext|
+        offer = offers.by_name(ext.name)
+        next if offer.empty? or reserved?(ext)
+
+        next unless session = ext.create_server_session(offer)
+
+        reserve(ext)
+        sessions.push([ext, session])
+        response.push(Parser.serialize_params(ext.name, session.generate_response))
+      end
+
+      @sessions = sessions
+      response.size > 0 ? response.join(', ') : nil
+    end
+
+    def valid_frame_rsv(frame)
+      allowed = {:rsv1 => false, :rsv2 => false, :rsv3 => false}
+
+      if MESSAGE_OPCODES.include?(frame.opcode)
+        @sessions.each do |ext, session|
+          allowed[:rsv1] ||= ext.rsv1
+          allowed[:rsv2] ||= ext.rsv2
+          allowed[:rsv3] ||= ext.rsv3
+        end
+      end
+
+      (allowed[:rsv1] || !frame.rsv1) &&
+      (allowed[:rsv2] || !frame.rsv2) &&
+      (allowed[:rsv3] || !frame.rsv3)
+    end
+    alias :valid_frame_rsv? :valid_frame_rsv
+
+    def process_incoming_message(message)
+      @sessions.reverse.inject(message) do |msg, (ext, session)|
+        begin
+          session.process_incoming_message(msg)
+        rescue => error
+          raise ExtensionError, [ext.name, error.message].join(': ')
+        end
+      end
+    end
+
+    def process_outgoing_message(message)
+      @sessions.inject(message) do |msg, (ext, session)|
+        begin
+          session.process_outgoing_message(msg)
+        rescue => error
+          raise ExtensionError, [ext.name, error.message].join(': ')
+        end
+      end
+    end
+
+    def close
+      @sessions.each do |ext, session|
+        session.close rescue nil
+      end
+    end
+
+  private
+
+    def reserve(ext)
+      @rsv1 ||= ext.rsv1 && ext.name
+      @rsv2 ||= ext.rsv2 && ext.name
+      @rsv3 ||= ext.rsv3 && ext.name
+    end
+
+    def reserved?(ext)
+      return [1, @rsv1] if @rsv1 and ext.rsv1
+      return [2, @rsv2] if @rsv2 and ext.rsv2
+      return [3, @rsv3] if @rsv3 and ext.rsv3
+      false
+    end
+
+  end
+end

data/lib/websocket/extensions/parser.rb

@@ -0,0 +1,109 @@
+module WebSocket
+  class Extensions
+
+    class Parser
+      TOKEN    = /([!#\$%&'\*\+\-\.\^_`\|~0-9a-z]+)/
+      NOTOKEN  = /([^!#\$%&'\*\+\-\.\^_`\|~0-9a-z])/
+      QUOTED   = /"((?:\\[\x00-\x7f]|[^\x00-\x08\x0a-\x1f\x7f"])*)"/
+      PARAM    = %r{#{TOKEN.source}(?:=(?:#{TOKEN.source}|#{QUOTED.source}))?}
+      EXT      = %r{#{TOKEN.source}(?: *; *#{PARAM.source})*}
+      EXT_LIST = %r{^#{EXT.source}(?: *, *#{EXT.source})*$}
+      NUMBER   = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?$/
+
+      ParseError = Class.new(ArgumentError)
+
+      def self.parse_header(header)
+        offers = Offers.new
+        return offers if header == '' or header.nil?
+
+        unless header =~ EXT_LIST
+          raise ParseError, "Invalid Sec-WebSocket-Extensions header: #{header}"
+        end
+
+        scanner = StringScanner.new(header)
+        value   = scanner.scan(EXT)
+
+        until value.nil?
+          params = value.scan(PARAM)
+          name   = params.shift.first
+          offer  = {}
+
+          params.each do |key, unquoted, quoted|
+            if unquoted
+              data = unquoted
+            elsif quoted
+              data = quoted.gsub(/\\/, '')
+            else
+              data = true
+            end
+            if data =~ NUMBER
+              data = data =~ /\./ ? data.to_f : data.to_i(10)
+            end
+
+            if offer.has_key?(key)
+              offer[key] = [*offer[key]] + [data]
+            else
+              offer[key] = data
+            end
+          end
+
+          offers.push(name, offer)
+
+          scanner.scan(/ *, */)
+          value = scanner.scan(EXT)
+        end
+        offers
+      end
+
+      def self.serialize_params(name, params)
+        values = []
+
+        print = lambda do |key, value|
+          case value
+          when Array   then value.each { |v| print[key, v] }
+          when true    then values.push(key)
+          when Numeric then values.push(key + '=' + value.to_s)
+          else
+            if value =~ NOTOKEN
+              values.push(key + '="' + value.gsub(/"/, '\"') + '"')
+            else
+              values.push(key + '=' + value)
+            end
+          end
+        end
+
+        params.keys.sort.each { |key| print[key, params[key]] }
+
+        ([name] + values).join('; ')
+      end
+    end
+
+    class Offers
+      def initialize
+        @by_name  = {}
+        @in_order = []
+      end
+
+      def push(name, params)
+        @by_name[name] ||= []
+        @by_name[name].push(params)
+        @in_order.push(:name => name, :params => params)
+      end
+
+      def each_offer(&block)
+        @in_order.each do |offer|
+          block.call(offer[:name], offer[:params])
+        end
+      end
+
+      def by_name(name)
+        @by_name[name] || []
+      end
+
+      def to_a
+        @in_order.dup
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: websocket-extensions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Coglan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: jcoglan@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/websocket/extensions.rb
+- lib/websocket/extensions/parser.rb
+homepage: http://github.com/faye/websocket-extensions-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+- "--markup"
+- markdown
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Generic extension manager for WebSocket connections
+test_files: []