pakyow-realtime 0.10.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4444748188cdd7131282b72c485e4560c9c1b1a5
+  data.tar.gz: 7a1a719e074da37c83369b4cd4f0ee0151d0d0e5
+SHA512:
+  metadata.gz: 10c2680a1c78d956357641ae71e57b96d8f2addd024558fe7c7d7edd07927cdd15e703559e5b13ac47354abc0edaef38bdc3fab87bea0cd6becba730e52694b0
+  data.tar.gz: 3c128c335c1fae854c751439a7b1b8848c976e31dda66052a68890c6d4e6017d5ca18ac021f054669c4156ca0a6dc79b2a654a22f1d69d7812aae64da78f4eed

data/pakyow-realtime/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.10.0 (to be released)
+
+  * Initial release

data/pakyow-realtime/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015 Bryan Powell
+
+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/pakyow-realtime/README.md

@@ -0,0 +1,164 @@
+# pakyow-realtime
+
+Brings realtime capabilities to Pakyow by creating a pub/sub
+connection between client and server using WebSockets.
+
+## Overview
+
+Clients can be subscribed to channels. Realtime keeps track of what channels a
+client has been subscribed to and tracks subscriptions across requests. Routes
+can push messages down channels to one or more subscribed clients through an
+established WebSocket.
+
+WebSockets are established by hijacking an HTTP request. Once hijacked, the
+WebSocket is forked into an async object via the highly performant [Concurrent
+Ruby](https://github.com/ruby-concurrency/concurrent-ruby) library. This
+approach allows each app instance to manage its own WebSockets while still
+serving normal requests.
+
+In addition to pushing messages from the server to the client, the client can
+send messages to the server. For example, out of the box Realtime supports
+calling routes over a WebSocket, with the response being pushed down once
+processing is complete.
+
+## Establishing a WebSocket connection to the server.
+
+Using the native Javascript `WebSocket` support in modern browsers, simply open
+a connection to your app. You'll need to include the connection id associated
+with your client, which tells Realtime what channels the connection should
+listen to. This connection id is automatically set on the `body` tag in a
+rendered view.
+
+Here's some example Javascript code that establishes a WebSocket connection:
+
+```javascript
+var wsUrl = '';
+
+var host = window.location.hostname;
+var port = window.location.port;
+
+if (window.location.protocol === 'http:') {
+  wsUrl += 'ws://';
+} else if (window.location.protocol === 'https:') {
+  wsUrl += 'wss://';
+}
+
+wsUrl += host;
+
+if (port) {
+  wsUrl += ':' + port;
+}
+
+var conn = document.getElementsByTagName('body')[0].getAttribute('data-socket-connection-id');
+wsUrl += '/?socket_connection_id=' + conn;
+
+console.log('Opening connection with id: ' + conn);
+window.socket = new WebSocket(wsUrl);
+
+window.socket.onopen = function (event) {
+  console.log('Socket opened.');
+};
+```
+
+A full example is available in the [example app](https://github.com/bryanp/pakyow-example-realtime).
+
+### Security
+
+The connection id is an important security feature of Realtime. Channel
+subscriptions are managed with a socket digest, generated from a key and
+connection id. The key is stored in the session object for a single client. If a
+socket is established with an incorrect connection id for the current client,
+the connection won't receive messages directed at that client (although the
+connection will appear to have been properly established) because the digest
+generated will also be incorrect.
+
+## Subscribing a client to a channel.
+
+From a route, simply call the `subscribe` method on the socket:
+
+```ruby
+socket.subscribe(:chan1)
+```
+
+To unsubscribe, call `unsubscribe`:
+
+```ruby
+socket.unsubscribe(:chan1)
+```
+
+## Pushing messages through a channel to one or more clients.
+
+To push a message down a channel, call `push` from a route:
+
+```ruby
+socket.push({ foo: 'bar' }, :chan1)
+```
+
+The first argument is the message and the second argument is a single channel or
+list of channels to push the message through. Each client subscribed to the
+channel will receive the message as a JSON object.
+
+## Calling routes from the client.
+
+Realtime also provides a mechanism for round trip client -> server -> client
+communication. Bundled with the library is a handler for calling routes through
+a WebSocket. An example of this is included in the example app.
+
+## Running in production.
+
+Redis is leveraged in production to handle:
+
+1. Tracking what clients are subscribed to what channels.
+2. Communicating between WebSocket connections contained on various app
+instances. Redis must be used to scale beyond a single app instance.
+
+The Redis registry will automatically be used when running in a `production`
+environment. But, in case you ever need to configure manually, add the following
+code to the appropriate `configure` block in `app/setup.rb`:
+
+```ruby
+realtime.registry = Pakyow::Realtime::RedisRegistry
+```
+
+To configure the Redis connection itself, configure like this:
+
+```ruby
+realtime.redis = { url: 'redis://localhost:6379' }
+```
+
+## Defining custom message handlers.
+
+Custom handlers can be defined for letting clients tell the server to do specific
+things. Check out the bundled [`call_route` handler](https://github.com/pakyow/pakyow/blob/master/pakyow-realtime/lib/pakyow-realtime/message_handlers/call_route.rb), with a usage example in the
+[example app](https://github.com/bryanp/pakyow-example-realtime).
+
+# Download
+
+The latest version of Pakyow Realtime can be installed with RubyGems:
+
+```
+gem install pakyow-realtime
+```
+
+Source code can be downloaded as part of the Pakyow project on Github:
+
+- https://github.com/pakyow/pakyow/tree/master/pakyow-realtime
+
+# License
+
+Pakyow Realtime is released free and open-source under the [MIT
+License](http://opensource.org/licenses/MIT).
+
+# Support
+
+Documentation is available here:
+
+- http://pakyow.org/docs/realtime
+
+Found a bug? Tell us about it here:
+
+- https://github.com/pakyow/pakyow/issues
+
+We'd love to have you in the community:
+
+- http://pakyow.org/get-involved

data/pakyow-realtime/lib/pakyow-realtime.rb

@@ -0,0 +1,21 @@
+require 'securerandom'
+require 'json'
+
+require 'pakyow-support'
+require 'pakyow-core'
+
+require_relative 'pakyow-realtime/helpers'
+require_relative 'pakyow-realtime/hooks'
+require_relative 'pakyow-realtime/context'
+require_relative 'pakyow-realtime/delegate'
+require_relative 'pakyow-realtime/registries/simple_registry'
+require_relative 'pakyow-realtime/registries/redis_registry'
+require_relative 'pakyow-realtime/redis_subscription'
+require_relative 'pakyow-realtime/websocket'
+require_relative 'pakyow-realtime/config'
+require_relative 'pakyow-realtime/exceptions'
+require_relative 'pakyow-realtime/message_handler'
+require_relative 'pakyow-realtime/message_handlers/call_route'
+require_relative 'pakyow-realtime/message_handlers/ping'
+
+require_relative 'pakyow-realtime/ext/request'

data/pakyow-realtime/lib/pakyow-realtime/config.rb

@@ -0,0 +1,22 @@
+require_relative 'registries/simple_registry'
+require_relative 'registries/redis_registry'
+
+Pakyow::Config.register(:realtime) { |config|
+  # The registry to use when keeping up with connections.
+  config.opt :registry, Pakyow::Realtime::SimpleRegistry
+
+  # The Redis config hash.
+  config.opt :redis, url: 'redis://127.0.0.1:6379'
+
+  # The key used to keep track of channels in Redis.
+  config.opt :redis_key, 'pw:channels'
+
+  # Whether or not realtime should be enabled.
+  config.opt :enabled, true
+}.env(:development) { |opts|
+  opts.registry = Pakyow::Realtime::SimpleRegistry
+}.env(:staging) { |opts|
+  opts.registry = Pakyow::Realtime::RedisRegistry
+}.env(:production) { |opts|
+  opts.registry = Pakyow::Realtime::RedisRegistry
+}

data/pakyow-realtime/lib/pakyow-realtime/connection.rb

@@ -0,0 +1,18 @@
+require_relative 'config'
+
+module Pakyow
+  module Realtime
+    # Represents a realtime connection (e.g. websocket).
+    #
+    # @api private
+    class Connection
+      def delegate
+        Delegate.instance
+      end
+
+      def logger
+        Pakyow.logger
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/context.rb

@@ -0,0 +1,60 @@
+require_relative 'websocket'
+require_relative 'config'
+
+module Pakyow
+  module Realtime
+    # Deals with realtime connections in context of an app. Instances are
+    # returned by the `socket` helper method during routing.
+    #
+    # @api public
+    class Context
+      # @api private
+      def initialize(app)
+        @app = app
+      end
+
+      # Subscribe the current session's connection to one or more channels.
+      #
+      # @api public
+      def subscribe(*channels)
+        channels = Array.ensure(channels).flatten
+        fail ArgumentError if channels.empty?
+
+        delegate.subscribe(
+          @app.socket_digest(@app.socket_connection_id),
+          channels
+        )
+      end
+
+      # Unsubscribe the current session's connection to one or more channels.
+      #
+      # @api public
+      def unsubscribe(*channels)
+        channels = Array.ensure(channels).flatten
+        fail ArgumentError if channels.empty?
+
+        delegate.unsubscribe(
+          @app.socket_digest(@app.socket_connection_id),
+          channels
+        )
+      end
+
+      # Push a message down one or more channels.
+      #
+      # @api public
+      def push(msg, *channels)
+        channels = Array.ensure(channels).flatten
+        fail ArgumentError if channels.empty?
+
+        delegate.push(msg, channels)
+      end
+
+      # Returns an instance of the connection delegate.
+      #
+      # @api private
+      def delegate
+        Delegate.instance
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/delegate.rb

@@ -0,0 +1,95 @@
+module Pakyow
+  module Realtime
+    # A singleton for delegating socket traffic using the configured registry.
+    #
+    # @api private
+    class Delegate
+      include Singleton
+
+      attr_reader :registry, :connections, :channels
+
+      def initialize
+        @registry = Config.realtime.registry.instance
+
+        @connections = {}
+        @channels = {}
+      end
+
+      # Registers a websocket instance with a unique key.
+      def register(key, connection)
+        @connections[key] = connection
+
+        channels = registry.channels_for_key(key)
+
+        channels.each do |channel|
+          next if connection.nil?
+          @channels[channel] ||= []
+
+          next if @channels[channel].include?(connection)
+          @channels[channel] << connection
+        end
+
+        registry.subscribe_for_propagation(channels) if registry.propagates?
+      end
+
+      # Unregisters a connection by its key.
+      def unregister(key)
+        registry.unregister_key(key)
+
+        connection = @connections.delete(key)
+        @channels.each do |_channel, connections|
+          connections.delete(connection)
+        end
+      end
+
+      # Subscribes a websocket identified by its key to one or more channels.
+      def subscribe(key, channels)
+        registry.subscribe_to_channels_for_key(channels, key)
+
+        # register the connection again since we've added channels
+        register(key, @connections[key])
+      end
+
+      # Unsubscribes a websocket identified by its key to one or more channels.
+      def unsubscribe(key, channels)
+        registry.unsubscribe_to_channels_for_key(channels, key)
+      end
+
+      # Pushes a message down channels from server to client.
+      def push(message, channels)
+        if registry.propagates? && !propagated?(message)
+          return propagate(message, channels)
+        elsif propagated?(message)
+          message.delete(:__propagated)
+        end
+
+        # push to this instances connections
+        channels.each do |channel_query|
+          connections_for_channel(channel_query).each_pair do |channel, conns|
+            conns.each do |connection|
+              connection.push(payload: message, channel: channel)
+            end
+          end
+        end
+      end
+
+      private
+
+      def propagate(message, channels)
+        registry.propagate(message, channels)
+      end
+
+      def propagated?(message)
+        message.include?(:__propagated)
+      end
+
+      def connections_for_channel(channel_query)
+        regexp = Regexp.new("^#{channel_query.to_s.gsub('*', '([^;]*)')}$")
+
+        @channels.select { |channel, _conns|
+          channel.match(regexp)
+        }
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/exceptions.rb

@@ -0,0 +1,6 @@
+module Pakyow
+  module Realtime
+    class HandshakeError < Error; end
+    class MissingMessageHandler < Error; end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/ext/request.rb

@@ -0,0 +1,10 @@
+module Pakyow
+  class Request
+    # Returns true if the request occurred over a WebSocket.
+    # 
+    # @api public
+    def socket?
+      env['pakyow.socket'] == true
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/helpers.rb

@@ -0,0 +1,33 @@
+module Pakyow
+  module Helpers
+    # Returns a working realtime context for the current app context.
+    #
+    # @api public
+    def socket
+      Realtime::Context.new(self)
+    end
+
+    # Returns the session's unique realtime key.
+    #
+    # @api private
+    def socket_key
+      return params[:socket_key] if params[:socket_key]
+      session[:socket_key] ||= SecureRandom.hex(32)
+    end
+
+    # Returns the unique connection id for this request lifecycle.
+    #
+    # @api private
+    def socket_connection_id
+      return params[:socket_connection_id] if params[:socket_connection_id]
+      @socket_connection_id ||= SecureRandom.hex(32)
+    end
+
+    # Returns a digest created from the connection id and socket_key.
+    #
+    # @api private
+    def socket_digest(socket_connection_id)
+      Digest::SHA1.hexdigest("--#{socket_key}--#{socket_connection_id}--")
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/hooks.rb

@@ -0,0 +1,30 @@
+Pakyow::App.before :route do
+  # we want to hijack websocket requests
+  #
+  if req.env['HTTP_UPGRADE'] == 'websocket'
+    if Pakyow::Config.realtime.enabled
+      socket_connection_id = params[:socket_connection_id]
+      socket_digest = socket_digest(socket_connection_id)
+
+      conn = Pakyow::Realtime::Websocket.new(req, socket_digest)
+
+      # register the connection with a unique key
+      Pakyow::Realtime::Delegate.instance.register(socket_digest, conn)
+    end
+
+    halt
+  end
+end
+
+Pakyow::App.after :process do
+  # mixin the socket connection id into the body tag
+  # this id is used by pakyow.js to idenfity itself with the server
+  #
+  if response.header['Content-Type'] == 'text/html' && Pakyow::Config.realtime.enabled
+    body = response.body[0]
+    next if body.nil?
+
+    mixin = '<body data-socket-connection-id="' + socket_connection_id + '"'
+    body.gsub!(/<body/, mixin)
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/message_handler.rb

@@ -0,0 +1,57 @@
+require_relative 'exceptions'
+
+module Pakyow
+  module Realtime
+    # Convenience method for registering a new message handler.
+    #
+    # @api public
+    def self.handler(name, &block)
+      MessageHandler.register(name, &block)
+    end
+
+    # A message handler registry. Handlers subscribe to some action and handle
+    # incoming messages for that action, returning a response.
+    #
+    # @api private
+    class MessageHandler
+      # Registers a handler for some action name.
+      #
+      # @api private
+      def self.register(name, &block)
+        handlers[name.to_sym] = block
+      end
+
+      # Calls a handler for a received websocket message.
+      #
+      # @api private
+      def self.handle(message, session)
+        id = message.fetch('id') {
+          fail ArgumentError, "Expected message to contain key 'id'"
+        }
+
+        action = message.fetch('action') {
+          fail ArgumentError, "Expected message to contain key 'action'"
+        }
+
+        handler = handlers.fetch(action.to_sym) {
+          fail MissingMessageHandler, "No message handler named #{action}"
+        }
+
+        handler.call(message, session, id: id)
+      end
+
+      # Resets the message handlers.
+      #
+      # @api private
+      def self.reset
+        @handlers = nil
+      end
+
+      private
+
+      def self.handlers
+        @handlers ||= {}
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/message_handlers/call_route.rb

@@ -0,0 +1,33 @@
+# Calls an app route and returns a response, just like an HTTP request!
+#
+Pakyow::Realtime.handler :'call-route' do |message, session, response|
+  path, qs = message['uri'].split('?')
+  path_parts = path.split('/')
+  path_parts[-1] += '.json'
+  uri = [path_parts.join('/'), qs].join('?')
+
+  env = Rack::MockRequest.env_for(uri, method: message['method'])
+  env['pakyow.socket'] = true
+  env['pakyow.data'] = message['input']
+  env['rack.session'] = session
+
+  # TODO: in production we want to push the message to a queue and
+  # let the next available app instance pick it up, rather than
+  # the current instance to handle all traffic on this socket
+  app = Pakyow.app.dup
+  res = app.process(env)
+
+  container = message['container']
+
+  if container
+    composer = app.presenter.composer
+    body = composer.container(container.to_sym).includes(composer.partials).to_s
+  else
+    body = res[2].body
+  end
+
+  response[:status]  = res[0]
+  response[:headers] = res[1]
+  response[:body]    = body
+  response
+end

data/pakyow-realtime/lib/pakyow-realtime/message_handlers/ping.rb

@@ -0,0 +1,8 @@
+# Handles pings to keep the WebSocket alive.
+#
+Pakyow::Realtime.handler :ping do |_message, _session, response|
+  response[:status] = 200
+  response[:headers] = {}
+  response[:body] = 'pong'
+  response
+end

data/pakyow-realtime/lib/pakyow-realtime/redis_subscription.rb

@@ -0,0 +1,58 @@
+require 'redis'
+require 'concurrent'
+
+module Pakyow
+  module Realtime
+    # Manages channel subscriptions for this application instance's WebSockets.
+    #
+    # @api private
+    class RedisSubscription
+      include Concurrent::Async
+
+      def initialize
+        @redis = ::Redis.new(Config.realtime.redis)
+        @channels = []
+
+        ObjectSpace.define_finalizer(self, self.class.finalize)
+      end
+
+      def self.finalize
+        -> {
+          unsubscribe
+          @redis.quit
+        }
+      end
+
+      def subscribe(channels)
+        return if channels.empty?
+        @channels = channels
+
+        run
+      end
+
+      def unsubscribe
+        return if @channels.empty?
+        @redis.unsubscribe(*@channels)
+      end
+
+      private
+
+      def run
+        @redis.subscribe(*@channels) do |on|
+          on.message do |channel, msg|
+            msg = JSON.parse(msg)
+
+            if msg.is_a?(Hash)
+              msg[:__propagated] = true
+            elsif msg.is_a?(Array)
+              msg << :__propagated
+            end
+
+            context = Pakyow::Realtime::Context.new(Pakyow.app)
+            context.push(msg, channel)
+          end
+        end
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/registries/redis_registry.rb

@@ -0,0 +1,94 @@
+require 'json'
+require 'redis'
+require 'singleton'
+
+require_relative '../redis_subscription'
+
+module Pakyow
+  module Realtime
+    def self.redis
+      $redis ||= Redis.new(Config.realtime.redis)
+    end
+    # Manages WebSocket connections and their subscriptions in Redis.
+    #
+    # This is the default registry in production systems and is required in
+    # deployments with more than one app instance.
+    #
+    # @api private
+    class RedisRegistry
+      include Singleton
+
+      attr_reader :subscriber
+
+      def initialize
+        @channels = []
+      end
+
+      def channels_for_key(key)
+        channels(key)
+      end
+
+      def unregister_key(key)
+        Pakyow::Realtime.redis.hdel(channel_key, key)
+      end
+
+      def subscribe_to_channels_for_key(channels, key)
+        new_channels = channels(key).concat(Array.ensure(channels)).uniq
+        Pakyow::Realtime.redis.hset(channel_key, key, new_channels.to_json)
+
+        @channels.concat(channels).uniq!
+        resubscribe
+      end
+
+      def unsubscribe_to_channels_for_key(channels, key)
+        new_channels = channels(key) - Array.ensure(channels)
+        Pakyow::Realtime.redis.hset(channel_key, key, new_channels.to_json)
+
+        channels.each { |channel| @channels.delete(channel) }
+        resubscribe
+      end
+
+      def propagates?
+        true
+      end
+
+      def propagate(message, channels)
+        message_json = message.to_json
+
+        channels.each do |channel|
+          Pakyow::Realtime.redis.publish(channel, message_json)
+        end
+      end
+
+      def subscribe_for_propagation(channels)
+        @channels.concat(channels).uniq!
+        resubscribe
+      end
+
+      private
+
+      # Terminates the current subscriber and creates a new
+      # subscriber with the current channels.
+      def resubscribe
+        if @subscriber
+          @subscriber.async.unsubscribe
+        else
+          @subscriber = RedisSubscription.new
+        end
+
+        @subscriber.async.subscribe(@channels)
+      end
+
+      # Returns the key used to store channels.
+      def channel_key
+        Config.realtime.redis_key
+      end
+
+      # Returns the channels for a specific key, or all channels.
+      def channels(key)
+        value = Pakyow::Realtime.redis.hget(channel_key, key)
+        (value ? JSON.parse(value) : []).map(&:to_sym)
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/registries/simple_registry.rb

@@ -0,0 +1,40 @@
+require 'singleton'
+
+module Pakyow
+  module Realtime
+    # Manages WebSocket connections and their subscriptions in memory.
+    #
+    # Intended only for use in development or single app-instance deployments.
+    #
+    # @api private
+    class SimpleRegistry
+      include Singleton
+
+      def initialize
+        @channels = {}
+      end
+
+      def channels_for_key(key)
+        @channels.fetch(key, [])
+      end
+
+      def unregister_key(key)
+        @channels.delete(key)
+      end
+
+      def subscribe_to_channels_for_key(channels, key)
+        @channels[key] ||= []
+        @channels[key].concat(Array.ensure(channels.map(&:to_sym))).uniq!
+      end
+
+      def unsubscribe_to_channels_for_key(channels, key)
+        @channels[key] ||= []
+        @channels[key] = @channels[key] - Array.ensure(channels.map(&:to_sym))
+      end
+      
+      def propagates?
+        false
+      end
+    end
+  end
+end

data/pakyow-realtime/lib/pakyow-realtime/websocket.rb

@@ -0,0 +1,188 @@
+require 'concurrent'
+require 'websocket_parser'
+
+require_relative 'connection'
+
+module Pakyow
+  module Realtime
+    # Hijacks a request, performs the handshake, and creates an async object
+    # for handling incoming and outgoing messages in an asynchronous manner.
+    #
+    # @api private
+    class Websocket < Connection
+      attr_reader :parser, :socket, :key
+
+      @event_handlers = {}
+
+      def initialize(req, key)
+        @req = req
+        @key = key
+
+        @handshake = handshake!(req)
+        @socket = hijack!(req)
+
+        handle_handshake
+      end
+
+      def shutdown
+        delegate.unregister(@key)
+        self.class.handle_event(:leave, @req)
+
+        @socket.close if @socket && !@socket.closed?
+        @shutdown = true
+
+        @reader = nil
+      end
+
+      def shutdown?
+        @shutdown == true
+      end
+
+      def push(msg)
+        json = JSON.pretty_generate(msg)
+        logger.debug "(ws.#{@key}) sending message: #{json}\n"
+        WebSocket::Message.new(json).write(@socket)
+      end
+
+      def self.on(event, &block)
+        (@event_handlers[event.to_sym] ||= []) << block
+      end
+
+      private
+
+      def handshake!(req)
+        WebSocket::ClientHandshake.new(:get, req.url, handshake_headers(req))
+      end
+
+      def hijack!(req)
+        if req.env['rack.hijack']
+          req.env['rack.hijack'].call
+          return req.env['rack.hijack_io']
+        else
+          logger.info "there's no socket to hijack :("
+        end
+      end
+
+      def handshake_headers(req)
+        {
+          'Upgrade' => req.env['HTTP_UPGRADE'],
+          'Sec-WebSocket-Version' => req.env['HTTP_SEC_WEBSOCKET_VERSION'],
+          'Sec-Websocket-Key' => req.env['HTTP_SEC_WEBSOCKET_KEY']
+        }
+      end
+
+      def handle_handshake
+        return if @socket.nil?
+
+        if @handshake.valid?
+          accept_handshake
+          setup
+        else
+          fail_handshake
+        end
+      end
+
+      def accept_handshake
+        response = @handshake.accept_response
+        response.render(@socket)
+      end
+
+      def fail_handshake
+        error = @handshake.errors.first
+
+        response = Rack::Response.new(400)
+        response.render(@socket)
+
+        fail HandshakeError, "(ws.#{@key}) error during handshake: #{error}"
+      end
+
+      def setup
+        logger.info "(ws.#{@key}) client established connection"
+        handle_ws_join
+
+        @parser = WebSocket::Parser.new
+
+        @parser.on_message do |message|
+          handle_ws_message(message)
+        end
+
+        @parser.on_error do |error|
+          logger.error "(ws.#{@key}) encountered error #{error}"
+          handle_ws_error(error)
+        end
+
+        @parser.on_close do |status, message|
+          logger.info "(ws.#{@key}) client closed connection"
+          handle_ws_close(status, message)
+        end
+
+        @parser.on_ping do |payload|
+          handle_ws_ping(payload)
+        end
+
+        @reader = Concurrent::Future.execute {
+          begin
+            loop do
+              break if shutdown?
+              @parser << @socket.read_nonblock(16_384)
+            end
+          rescue ::IO::WaitReadable
+            IO.select([@socket])
+            retry
+          rescue EOFError
+            @parent.delegate.unregister(@key)
+            @parent.shutdown
+          end
+        }
+      end
+
+      def handle_ws_message(message)
+        parsed = JSON.parse(message)
+        logger.debug "(ws.#{@key}) received message: #{JSON.pretty_generate(parsed)}\n"
+        push(MessageHandler.handle(parsed, @req.env['rack.session']))
+      rescue StandardError => e
+        logger.error "(#{@key}): WebSocket encountered an error:"
+        logger.error e.message
+
+        e.backtrace.each do |line|
+          logger.error line
+        end
+      end
+
+      def handle_ws_error(_error)
+        shutdown
+      end
+
+      def handle_ws_join
+        self.class.handle_event(:join, @req)
+      end
+
+      def handle_ws_close(_status, _message)
+        @socket << WebSocket::Message.close.to_data
+        shutdown
+      end
+
+      def handle_ws_ping(payload)
+        @socket << WebSocket::Message.pong(payload).to_data
+      end
+
+      def self.handle_event(event, req)
+        if Pakyow.app
+          app = Pakyow.app.dup
+          app.context = AppContext.new(req)
+
+          ui = Pakyow.app.instance_variable_get(:@ui)
+          app.context.ui = ui.dup if ui
+        end
+
+        event_handlers(event).each do |block|
+          app.instance_exec(&block)
+        end
+      end
+
+      def self.event_handlers(event = nil)
+        @event_handlers.fetch(event, [])
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: pakyow-realtime
+version: !ruby/object:Gem::Version
+  version: 0.10.0
+platform: ruby
+authors:
+- Bryan Powell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pakyow-support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: pakyow-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: websocket_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: WebSockets and realtime channels for Pakyow
+email: bryan@metabahn.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- pakyow-realtime/CHANGELOG.md
+- pakyow-realtime/LICENSE
+- pakyow-realtime/README.md
+- pakyow-realtime/lib/pakyow-realtime.rb
+- pakyow-realtime/lib/pakyow-realtime/config.rb
+- pakyow-realtime/lib/pakyow-realtime/connection.rb
+- pakyow-realtime/lib/pakyow-realtime/context.rb
+- pakyow-realtime/lib/pakyow-realtime/delegate.rb
+- pakyow-realtime/lib/pakyow-realtime/exceptions.rb
+- pakyow-realtime/lib/pakyow-realtime/ext/request.rb
+- pakyow-realtime/lib/pakyow-realtime/helpers.rb
+- pakyow-realtime/lib/pakyow-realtime/hooks.rb
+- pakyow-realtime/lib/pakyow-realtime/message_handler.rb
+- pakyow-realtime/lib/pakyow-realtime/message_handlers/call_route.rb
+- pakyow-realtime/lib/pakyow-realtime/message_handlers/ping.rb
+- pakyow-realtime/lib/pakyow-realtime/redis_subscription.rb
+- pakyow-realtime/lib/pakyow-realtime/registries/redis_registry.rb
+- pakyow-realtime/lib/pakyow-realtime/registries/simple_registry.rb
+- pakyow-realtime/lib/pakyow-realtime/websocket.rb
+homepage: http://pakyow.org
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- pakyow-realtime/lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Pakyow Realtime
+test_files: []