permessage_deflate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a45dd8e4933a9a41365043f0b770ad2f9df343c
+  data.tar.gz: 59b4bbba3b0fc00a970604c1a307bf8b80fc034a
+SHA512:
+  metadata.gz: b1c220ecbfe1f83d19c6a59d6045478bc827cb36f72e1f97ad914dc04002f188239bba1adde415f65cb85911a7c423e545e12d6ff1230d57e7bc62626c871af0
+  data.tar.gz: ae327691407e387275f0f0e8a5ce54817108a9f4b4dc2fbd9245f23514873ac3585e380ccfe04b38f3a64a5c93d9d8b6a828f87e06550b759cf2ba8f2a29e8f5

data/README.md

@@ -0,0 +1,91 @@
+# permessage_deflate [![Build status](https://secure.travis-ci.org/faye/permessage-deflate-ruby.svg)](http://travis-ci.org/faye/permessage-deflate-ruby)
+
+Implements the
+[permessage-deflate](https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression)
+WebSocket protocol extension as a plugin for
+[websocket-extensions](https://github.com/faye/websocket-extensions-ruby).
+
+## Installation
+
+```
+$ gem install permessage_deflate
+```
+
+## Usage
+
+Add the plugin to your extensions:
+
+```rb
+require 'websocket/extensions'
+require 'permessage_deflate'
+
+exts = WebSocket::Extensions.new
+exts.add(PermessageDeflate)
+```
+
+The extension can be configured, for example:
+
+```rb
+require 'websocket/extensions'
+require 'permessage_deflate'
+
+deflate = PermessageDeflate.configure(
+  :level => Zlib::BEST_COMPRESSION,
+  :max_window_bits => 13
+)
+
+exts = WebSocket::Extensions.new
+exts.add(deflate)
+```
+
+The set of available options can be split into two sets: those that control the
+session's compressor for outgoing messages and do not need to be communicated to
+the peer, and those that are negoatiated as part of the protocol. The settings
+only affecting the compressor are described fully in the [Zlib
+documentation](http://ruby-doc.org/stdlib-2.1.0/libdoc/zlib/rdoc/Zlib/Deflate.html#method-c-new):
+
+* `:level`: sets the compression level, can be an integer from `0` to `9`, or
+  one of the contants `Zlib::NO_COMPRESSION`, `Zlib::BEST_SPEED`,
+  `Zlib::BEST_COMPRESSION`, or `Zlib::DEFAULT_COMPRESSION`
+* `:mem_level`: sets how much memory the compressor allocates, can be an integer
+  from `1` to `9`, or one of the constants `Zlib::MAX_MEM_LEVEL`, or
+  `Zlib::DEF_MEM_LEVEL`
+* `:strategy`: can be one of the constants `Zlib::FILTERED`,
+  `Zlib::HUFFMAN_ONLY`, `Zlib::RLE`, `Zlib::FIXED`, or `Zlib::DEFAULT_STRATEGY`
+
+The other options relate to settings that are negotiated via the protocol and
+can be used to set the local session's behaviour and control that of the peer:
+
+* `:no_context_takeover`: if `true`, stops the session reusing a deflate context
+  between messages
+* `:request_no_context_takeover`: if `true`, makes the session tell the other
+  peer not to reuse a deflate context between messages
+* `:max_window_bits`: an integer from `8` to `15` inclusive that sets the
+  maximum size of the session's sliding window; a lower window size will be used
+  if requested by the peer
+* `:request_max_window_bits`: an integer from `8` to `15` inclusive to ask the
+  other peer to use to set its maximum sliding window size, if supported
+
+## 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/permessage_deflate.rb

@@ -0,0 +1,41 @@
+require 'zlib'
+
+class PermessageDeflate
+  root = File.expand_path('..', __FILE__)
+  require root + '/permessage_deflate/session'
+  require root + '/permessage_deflate/client_session'
+  require root + '/permessage_deflate/server_session'
+
+  ConfigurationError = Class.new(ArgumentError)
+
+  module Extension
+    define_method(:name) { 'permessage-deflate' }
+    define_method(:type) { 'permessage' }
+    define_method(:rsv1) { true  }
+    define_method(:rsv2) { false }
+    define_method(:rsv3) { false }
+
+    def configure(options)
+      options = (@options || {}).merge(options)
+      PermessageDeflate.new(options)
+    end
+
+    def create_client_session
+      ClientSession.new(@options || {})
+    end
+
+    def create_server_session(offers)
+      offers.each do |offer|
+        return ServerSession.new(@options || {}, offer) if ServerSession.valid_params?(offer)
+      end
+      nil
+    end
+  end
+
+  include Extension
+  extend  Extension
+
+  def initialize(options)
+    @options = options
+  end
+end

data/lib/permessage_deflate/client_session.rb

@@ -0,0 +1,73 @@
+class PermessageDeflate
+  class ClientSession < Session
+
+    def self.valid_params?(params)
+      return false unless super
+
+      if params.has_key?('client_max_window_bits')
+        return false unless VALID_WINDOW_BITS.include?(params['client_max_window_bits'])
+      end
+
+      true
+    end
+
+    def generate_offer
+      offer = {}
+
+      if @accept_no_context_takeover
+        offer['client_no_context_takeover'] = true
+      end
+
+      if @accept_max_window_bits
+        unless VALID_WINDOW_BITS.include?(@accept_max_window_bits)
+          raise ConfigurationError, 'Invalid value for max_window_bits'
+        end
+        offer['client_max_window_bits'] = @accept_max_window_bits
+      else
+        offer['client_max_window_bits'] = true
+      end
+
+      if @request_no_context_takeover
+        offer['server_no_context_takeover'] = true
+      end
+
+      if @request_max_window_bits
+        unless VALID_WINDOW_BITS.include?(@request_max_window_bits)
+          raise ConfigurationError, 'Invalid value for request_max_window_bits'
+        end
+        offer['server_max_window_bits'] = @request_max_window_bits
+      end
+
+      offer
+    end
+
+    def activate(params)
+      return false unless ClientSession.valid_params?(params)
+
+      if @accept_max_window_bits and params['client_max_window_bits']
+        return false if params['client_max_window_bits'] > @accept_max_window_bits
+      end
+
+      if @request_no_context_takeover and !params['server_no_context_takeover']
+        return false
+      end
+
+      if @request_max_window_bits
+        return false unless params['server_max_window_bits']
+        return false if params['server_max_window_bits'] > @request_max_window_bits
+      end
+
+      @own_context_takeover = !(@accept_no_context_takeover || params['client_no_context_takeover'])
+      @own_window_bits = [
+        @accept_max_window_bits || DEFAULT_MAX_WINDOW_BITS,
+        params['client_max_window_bits'] || DEFAULT_MAX_WINDOW_BITS
+      ].min
+
+      @peer_context_takeover = !params['server_no_context_takeover']
+      @peer_window_bits = params['server_max_window_bits'] || DEFAULT_MAX_WINDOW_BITS
+
+      true
+    end
+
+  end
+end

data/lib/permessage_deflate/server_session.rb

@@ -0,0 +1,59 @@
+class PermessageDeflate
+  class ServerSession < Session
+
+    def self.valid_params?(params)
+      return false unless super
+
+      if params.has_key?('client_max_window_bits')
+        return false unless ([true] + VALID_WINDOW_BITS).include?(params['client_max_window_bits'])
+      end
+
+      true
+    end
+
+    def initialize(options, params)
+      super(options)
+      @params = params
+    end
+
+    def generate_response
+      params = {}
+
+      # https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression#section-8.1.1.1
+      if @accept_no_context_takeover or @params['server_no_context_takeover']
+        params['server_no_context_takeover'] = true
+      end
+
+      # https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression#section-8.1.1.2
+      if @request_no_context_takeover or @params['client_no_context_takeover']
+        params['client_no_context_takeover'] = true
+      end
+
+      # https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression#section-8.1.2.1
+      if @accept_max_window_bits or @params['server_max_window_bits']
+        accept_max = @accept_max_window_bits || DEFAULT_MAX_WINDOW_BITS
+        server_max = @params['server_max_window_bits'] || DEFAULT_MAX_WINDOW_BITS
+        params['server_max_window_bits'] = [accept_max, server_max].min
+      end
+
+      # https://tools.ietf.org/html/draft-ietf-hybi-permessage-compression#section-8.1.2.2
+      if client_max = @params['client_max_window_bits']
+        if client_max == true
+          params['client_max_window_bits'] = @request_max_window_bits if @request_max_window_bits
+        else
+          request_max = @request_max_window_bits || DEFAULT_MAX_WINDOW_BITS
+          params['client_max_window_bits'] = [request_max, client_max].min
+        end
+      end
+
+      @own_context_takeover = !params['server_no_context_takeover']
+      @own_window_bits = params['server_max_window_bits'] || DEFAULT_MAX_WINDOW_BITS
+
+      @peer_context_takeover = !params['client_no_context_takeover']
+      @peer_window_bits = params['client_max_window_bits'] || DEFAULT_MAX_WINDOW_BITS
+
+      params
+    end
+
+  end
+end

data/lib/permessage_deflate/session.rb

@@ -0,0 +1,97 @@
+class PermessageDeflate
+  class Session
+
+    VALID_PARAMS = [
+      'server_no_context_takeover',
+      'client_no_context_takeover',
+      'server_max_window_bits',
+      'client_max_window_bits'
+    ]
+
+    DEFAULT_MAX_WINDOW_BITS = 15
+    VALID_WINDOW_BITS = [8, 9, 10, 11, 12, 13, 14, 15]
+
+    def self.valid_params?(params)
+      return false unless params.keys.all? { |k| VALID_PARAMS.include?(k) }
+      return false if params.values.grep(Array).any?
+
+      if params.has_key?('server_no_context_takeover')
+        return false unless params['server_no_context_takeover'] == true
+      end
+
+      if params.has_key?('client_no_context_takeover')
+        return false unless params['client_no_context_takeover'] == true
+      end
+
+      if params.has_key?('server_max_window_bits')
+        return false unless VALID_WINDOW_BITS.include?(params['server_max_window_bits'])
+      end
+
+      true
+    end
+
+    def initialize(options)
+      @level     = options.fetch(:level,     Zlib::DEFAULT_COMPRESSION)
+      @mem_level = options.fetch(:mem_level, Zlib::DEF_MEM_LEVEL)
+      @strategy  = options.fetch(:strategy,  Zlib::DEFAULT_STRATEGY)
+
+      @accept_no_context_takeover  = options.fetch(:no_context_takeover, false)
+      @accept_max_window_bits      = options.fetch(:max_window_bits, nil)
+      @request_no_context_takeover = options.fetch(:request_no_context_takeover, false)
+      @request_max_window_bits     = options.fetch(:request_max_window_bits, nil)
+    end
+
+    def process_incoming_message(message)
+      return message unless message.rsv1
+
+      inflate = get_inflate
+
+      message.data = inflate.inflate(message.data) +
+                     inflate.inflate([0x00, 0x00, 0xff, 0xff].pack('C*'))
+
+      free(inflate) unless @inflate
+      message
+    end
+
+    def process_outgoing_message(message)
+      deflate = get_deflate
+
+      message.data = deflate.deflate(message.data, Zlib::SYNC_FLUSH)[0...-4]
+      message.rsv1 = true
+
+      free(deflate) unless @deflate
+      message
+    end
+
+    def close
+      free(@inflate)
+      @inflate = nil
+
+      free(@deflate)
+      @deflate = nil
+    end
+
+  private
+
+    def free(codec)
+      return if codec.nil?
+      codec.finish rescue nil
+      codec.close
+    end
+
+    def get_inflate
+      return @inflate if @inflate
+      inflate = Zlib::Inflate.new(-@peer_window_bits)
+      @inflate = inflate if @peer_context_takeover
+      inflate
+    end
+
+    def get_deflate
+      return @deflate if @deflate
+      deflate = Zlib::Deflate.new(@level, -@own_window_bits, @mem_level, @strategy)
+      @deflate = deflate if @own_context_takeover
+      deflate
+    end
+
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: permessage_deflate
+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/permessage_deflate.rb
+- lib/permessage_deflate/client_session.rb
+- lib/permessage_deflate/server_session.rb
+- lib/permessage_deflate/session.rb
+homepage: http://github.com/faye/permessage-deflate-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: Per-message DEFLATE compression extension for WebSocket connections
+test_files: []