startback-websocket 0.14.0 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296fd63b702924e7a5952b60a67bbb90e89b99a415be62e52a4f7f63e5638753
-  data.tar.gz: 8234e5f95a05e91f6698da787bc8479ce924a2bfc537866ea68d188f89df7b54
+  metadata.gz: 6d94ab898d70e35e0d5b188c459af5ab40070ae0e5e7a1d23bbbfc6aad61694f
+  data.tar.gz: 333ed1fbf65609758827015d725dbbed14224249141e979204b7203fa3d75405
 SHA512:
-  metadata.gz: 48169cfbda94301c4a8ebbfea5f0ba93bedba26f59860a4b8d5376d51ec19cf0f23dcbbda9d7c8c366d483f1bd22d9d36dec2ce90ec362870adc731e7c28a7f6
-  data.tar.gz: e304a39fb8f4ce6a3c3df896c014f8b60eda3a58b18b4e9f52c7de1eeee67b3f7fd3b12e9652d7e50ccc7344377a9c289fd9c0aa14d4a6c13dd9ee75fcf39fab
+  metadata.gz: 687b5855a911d1d434bbfd6c9569d26a10b9615d7b4c06f10671d5fa645c4b62b053c9c3beacb49d252ebaa595144d9192b8e165ff73f2e4733bc56c677bb99b
+  data.tar.gz: 9852ab507c3a9ad302bd7c323914ff248452e39d30a8bd4408e8f7c6407bf820aaafaa2abc7f7a20ec321ff80217a02dbf884bf82ada6be6802af8c505653a9d

data/Gemfile

@@ -1,3 +1,4 @@
 source "https://rubygems.org"
-gem 'startback', path: "."
-gemspec :name => 'startback-web'
+gemspec
+
+gem 'startback', path: '../..'

data/README.md

@@ -1,13 +1,68 @@
-# Startback - Got Your Ruby Back
+## Hub
 
-Yet another ruby framework, I'm afraid. Here, we srongly seperate between:
+The `Hub:App` provides an opinionated protocol that eases
+the handling of real-time, websocket-based, applications.
 
-1. the web layer, in charge of a quality HTTP handling
-2. the operations layer, in charge of the high-level software operations
-3. the database layer, abstracted using the Relations As First Class Citizen pattern
+### Protocol
 
-Currently,
+The protocol is mainly based on JSON-serialized messages containing both a `headers` map and a `body` property.
 
-1. is handled using extra support on top of Sinatra
-2. is handled using Startback specific classes
-3. is handled using Bmg
+#### Rooms
+
+Rooms provide an abstraction allowing messages to be broadcasted to a set of `participants`.
+
+Messages are sent/received to/from rooms by providing the special `'room' header`, eg:
+
+```json
+{
+  "header": {
+    "room": "a-room-name"
+  },
+  "body": {} || "" // can be anything
+}
+```
+
+#### Commands
+
+Commands provide an abstraction allowing the execution of remote processing that can provide a result.
+
+Commands are executed by providing the special `'command‘ header` and an additional `'reply-to' header`, eg:
+
+```json
+{
+  "header": {
+    "command": "a-command",
+    "reply-to": "cc3ce43a-a494-4c38-bb01-654223ee24a5" // uuid v4
+  },
+  "body": {} || "" // can be anything
+}
+```
+
+The protocol contract between the Hub-servers and Hub-clients is that the result of a command execution can be sent back to the client by sending a message re-using the uuid provided in the `reply-to header` in the following way:
+
+```json
+{
+  "header": {
+    // same as the reply-to value of the original message
+    "in-reply-to": "cc3ce43a-a494-4c38-bb01-654223ee24a5"
+  },
+  "body": {} || "" // the result of the command run
+}
+```
+
+#### Combination
+
+The several aspects of the protocol can be combined.
+
+For instance a command can be executed in a specific room:
+
+```json
+{
+  "header": {
+    "command": "a-command",
+    "room": "a-certain-room",
+    "reply-to": "323b7293-91f4-49ab-b374-006087b56e07"
+  },
+  "body": {} || "" // can be anything
+}
+```

data/lib/startback/ext/context.rb

@@ -0,0 +1,6 @@
+module Startback
+  class Context
+    attr_accessor :websocket_app
+
+  end
+end

data/lib/startback/ext.rb

@@ -1,2 +1 @@
-require_relative 'ext/date_time'
-require_relative 'ext/time'
+require_relative 'ext/context'

data/lib/startback/websocket/app.rb

@@ -0,0 +1,82 @@
+
+module Startback
+  module Websocket
+    #
+    # Can be used to easily implement a custom websocket protocol inside a Startback
+    # application.
+    #
+    # Please note that this rack app is not 100% Rack compliant, since it raises
+    # any error that the block itself raises. This class aims at being backed up
+    # by a Shield and/or CatchAll middleware.
+    #
+    class App
+
+      JS_CLIENT = Path.dir/'../../../dist/client.js'
+
+      def initialize(context)
+        @context = context
+        @context.websocket_app = self
+        @connections = []
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        if Faye::WebSocket.websocket?(env)
+          ws = factor_and_keep(env)
+          ws.rack_response
+        elsif request.path_info === '/client.js'
+          [200, { 'Content-Type' => 'application/javascript' }, JS_CLIENT.readlines]
+        else
+          [400, { 'Content-Type' => 'text/plain' }, ['Websocket only!']]
+        end
+      end
+
+      def broadcast(data)
+        data = data.to_json unless data.is_a?(String)
+
+        @connections.each do |socket|
+          socket.send(data)
+        end
+      end
+
+      def on_open(event, ws, env)
+      end
+
+      def on_close(event, ws, env)
+      end
+
+      def on_error(event, ws, env)
+      end
+
+      def on_message(event, ws, env)
+      end
+
+    private
+
+      def factor_and_keep(env)
+        ws = Faye::WebSocket.new(env)
+
+        ws.on :open do |event|
+          @connections << ws
+          on_open(event, ws, env)
+        end
+
+        ws.on :close do |event|
+          @connections.delete(ws)
+          on_close(event, ws, env)
+        end
+
+        ws.on :message do |event|
+          on_message(event, ws, env)
+        end
+
+        ws.on :error do |event|
+          on_error(event, ws, env)
+        end
+
+        ws
+      end
+
+    end # class App
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/app.rb

@@ -0,0 +1,28 @@
+
+module Startback
+  module Websocket
+    module Hub
+      #
+      # The Hub is a very opinionated websocket protocol based on room and
+      # subscriptions, allowing users to subscribe to rooms etc etc... # TODO
+      #
+      class App < Websocket::App
+
+        def initialize(context, rooms, handler)
+          super(context)
+          @handler = handler
+          @rooms = rooms
+        end
+
+        def room(name)
+          @rooms[name]
+        end
+
+        def on_message(event, ws, env)
+          @handler.call(Message.new(event.data, ws), ws, env)
+        end
+
+      end # class App
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/builder.rb

@@ -0,0 +1,55 @@
+
+module Startback
+  module Websocket
+    module Hub
+      class Builder
+
+        def initialize(context, default_handler = nil, *bl_args, &bl)
+          @context = context
+          @default_handler = default_handler
+          @middlewares = []
+          @commands = {}
+          @rooms = {}
+          @bl_args
+          instance_exec *bl_args, &bl
+        end
+
+        def use(middleware, *opts)
+          @middlewares << proc { |app| middleware.new(app, *opts) }
+        end
+
+        def command(name, &bl)
+          cname = name.to_sym
+          raise "Command #{name} already defined: #{name}" if @commands[cname]
+          @commands[cname] = proc { |app| Middleware::CommandHandler.new(app, { :name => name }, &bl) }
+          @middlewares << @commands[cname]
+        end
+
+        def room(name, &bl)
+          raise "Room names must be strings" unless name.is_a? String
+          raise "Room '#{name}' already defined" if @rooms[name]
+
+          @rooms[name] ||= Room.new(name)
+          handler = Builder.new(@context, nil, @rooms[name], &bl).to_handler
+          middleware = proc { |app| Middleware::RoomHandler.new(app, @rooms[name], handler) }
+
+          @middlewares << middleware
+        end
+
+        def to_handler
+          default_handler = @default_handler || proc {}
+          @middlewares
+            .reverse
+            .reduce(default_handler) do |handler, mw|
+              mw.call(handler)
+            end
+        end
+
+        def to_websocket_app
+          App.new(@context, @rooms, to_handler)
+        end
+
+      end # class Builder
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/errors.rb

@@ -0,0 +1,9 @@
+
+module Startback
+  module Websocket
+    module Hub
+      class Error < Startback::Errors::Error
+      end # class Error
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/message.rb

@@ -0,0 +1,29 @@
+
+module Startback
+  module Websocket
+    module Hub
+      class Message
+
+        def initialize(data, socket)
+          data = JSON.parse(data, symbolize_names: true)
+          @headers = data[:headers] || {}
+          @body = data[:body] || {}
+          @socket = socket
+        end
+        attr_reader :headers, :body, :socket
+
+        def reply(message)
+          raise "No reply-to header found" unless headers[:'reply-to']
+          response = {
+            headers: {
+              :'in-reply-to' => headers[:'reply-to']
+            },
+            body: message
+          }
+          @socket.send(response.to_json)
+        end
+
+      end # class Message
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/middleware/command_handler.rb

@@ -0,0 +1,34 @@
+
+module Startback
+  module Websocket
+    module Hub
+      module Middleware
+        class CommandHandler
+
+          def initialize(app, opts, &bl)
+            @app = app
+            @opts = opts
+            @handler = bl
+          end
+
+          def call(event, socket, env)
+            who = matches?(event) ? @handler : @app
+            who.call(event, socket, env)
+          end
+
+        private
+
+          def matches?(event)
+            if event.headers[:command]
+              event.headers[:command]&.to_sym === @opts[:name]
+            else
+              false
+            end
+          end
+
+        end # class CommandHandler
+      end # module Middleware
+    end # module Hub
+  end # module Websocket
+end # module Startback
+

data/lib/startback/websocket/hub/middleware/room_handler.rb

@@ -0,0 +1,30 @@
+
+module Startback
+  module Websocket
+    module Hub
+      module Middleware
+        class RoomHandler
+
+          def initialize(app, room, handler)
+            @app = app
+            @room = room
+            @handler = handler
+          end
+
+          def call(event, socket, env)
+            who = matches?(event) ? @handler : @app
+            who.call(event, socket, env)
+          end
+
+          private
+
+          def matches?(event)
+            event.headers[:room] === @room.name
+          end
+
+        end # class RoomHandler
+      end # module Middleware
+    end # module Hub
+  end # module Websocket
+end # module Startback
+

data/lib/startback/websocket/hub/middleware.rb

@@ -0,0 +1,12 @@
+
+module Startback
+  module Websocket
+    module Hub
+      module Middleware
+      end # module Middleware
+    end # module Hub
+  end # module Websocket
+end # module Startback
+
+require_relative "middleware/command_handler"
+require_relative "middleware/room_handler"

data/lib/startback/websocket/hub/participant.rb

@@ -0,0 +1,16 @@
+module Startback
+  module Websocket
+    module Hub
+      class Participant
+
+        def initialize(socket, context, metadata={})
+          @socket = socket
+          @context = context
+          @metadata = metadata
+        end
+        attr_reader :socket, :context, :metadata
+
+      end # class Participant
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub/room.rb

@@ -0,0 +1,46 @@
+
+module Startback
+  module Websocket
+    module Hub
+      class Room < App
+
+        def initialize(name)
+          @name = name
+          @participants = []
+        end
+        attr_reader :name, :participants
+
+        def add(participant)
+          raise "Participant instance expected" unless participant.is_a? Participant
+          @participants << participant
+          participant.socket.on :close do |event|
+            remove(participant)
+          end
+        end
+
+        def remove(participant)
+          raise "Participant instance expected" unless participant.is_a? Participant
+          @participants.delete participant
+        end
+
+        def include?(participant)
+          raise "Participant instance expected" unless participant.is_a? Participant
+          @participants.include? participant
+        end
+
+        def broadcast(message)
+          puts "Broadcasting to #{@participants.size} participants"
+          @participants.each do |p|
+            p.socket.send({
+              headers: {
+                room: @name,
+              },
+              body: message
+            }.to_json)
+          end
+        end
+
+      end # class Room
+    end # module Hub
+  end # module Websocket
+end # module Startback

data/lib/startback/websocket/hub.rb

@@ -0,0 +1,15 @@
+
+module Startback
+  module Websocket
+    module Hub
+    end # module Hub
+  end # module Websocket
+end # module Startback
+
+require_relative "hub/errors"
+require_relative "hub/message"
+require_relative "hub/middleware"
+require_relative "hub/participant"
+require_relative "hub/room"
+require_relative "hub/app"
+require_relative "hub/builder"

data/lib/startback/websocket.rb

@@ -0,0 +1,8 @@
+require 'faye/websocket'
+module Startback
+  module Websocket
+  end # module Websocket
+end # module Startback
+require_relative 'ext'
+require_relative 'websocket/app'
+require_relative 'websocket/hub'

data/spec/spec_helper.rb

@@ -1,49 +1,38 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'startback'
-require 'startback/event'
-require 'startback/support/fake_logger'
+require 'startback/websocket'
 require 'rack/test'
-require 'ostruct'
 
 module SpecHelpers
-end
-
-RSpec.configure do |c|
-  c.include SpecHelpers
-end
-
-class SubContext < Startback::Context
 
-  attr_accessor :foo
-
-  h_factory do |c,h|
-    c.foo = h["foo"]
+  class SubContext < Startback::Context
+    attr_accessor :websocket_app
   end
 
-  h_dump do |h|
-    h.merge!("foo" => foo)
-  end
+  class MockSocket
+    attr_reader :last_message
 
-  world(:partner) do
-    Object.new
-  end
-
-end
-
-class SubContext
+    def send(msg)
+      @last_message = msg
+    end
 
-  attr_accessor :bar
+    def close()
+    end
 
-  h_factory do |c,h|
-    c.bar = h["bar"]
+    def on(event, &bl)
+    end
   end
 
-  h_dump do |h|
-    h.merge!("bar" => bar)
+  class MockFayeEvent
+    def initialize(event)
+      @data = event[:data]
+      @headers = event[:headers] || {}
+    end
+    attr_reader :data, :headers
   end
 
 end
 
-class User
-  class Changed < Startback::Event
-  end
+RSpec.configure do |c|
+  c.include SpecHelpers
 end