startback-websocket 0.14.0 → 0.14.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296fd63b702924e7a5952b60a67bbb90e89b99a415be62e52a4f7f63e5638753
-  data.tar.gz: 8234e5f95a05e91f6698da787bc8479ce924a2bfc537866ea68d188f89df7b54
+  metadata.gz: 2909a07d46bc34a032aa02e2f44bcce0bf3404967eb99ef9e60b92d6c547febb
+  data.tar.gz: e9df9bef24c2985f95b1214d3e2df7acbada61e3f2b84346e4b6562dcf4fae0b
 SHA512:
-  metadata.gz: 48169cfbda94301c4a8ebbfea5f0ba93bedba26f59860a4b8d5376d51ec19cf0f23dcbbda9d7c8c366d483f1bd22d9d36dec2ce90ec362870adc731e7c28a7f6
-  data.tar.gz: e304a39fb8f4ce6a3c3df896c014f8b60eda3a58b18b4e9f52c7de1eeee67b3f7fd3b12e9652d7e50ccc7344377a9c289fd9c0aa14d4a6c13dd9ee75fcf39fab
+  metadata.gz: 00dc98c0337281af6b7d18a148553428983f7494cc709c120259901e9e58ea8e38b02796f26edd5c520de288dd586e0086aa2e7e205136e254297bef83048b62
+  data.tar.gz: a545063482457190d47d13daf336af65b5275a87a708dea7e5b5b7b7ede6dc8e344930f4de222a9293f46cc1ed5e1fb55897f02efb29e6cf2cff5a279e006326

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/dist/client.js

@@ -0,0 +1 @@
+var StartbackWebsocket;(()=>{"use strict";var e,r={d:(e,s)=>{for(var t in s)r.o(s,t)&&!r.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:s[t]})},o:(e,r)=>Object.prototype.hasOwnProperty.call(e,r),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},s={};r.r(s),r.d(s,{Client:()=>t,HubClient:()=>l});class t extends class{#e;constructor(){this.#e={}}on(e,r){this.#e[e]||=[],this.#e[e].push(r)}emit(e,r){this.#e[e]||=[],this.#e[e].forEach((s=>{if(s)try{s(r)}catch(r){console.error("Error while calling event handler for",e),console.error(r)}}))}}{#r;#s;constructor(e){super(),this.#r=e}send(e){this.#s.send(e)}connect(){if(this.#s)throw new Error("Already connected");this.#s=new WebSocket(this.#r),["close","error","message","open"].forEach((e=>{this.#s.addEventListener(e,(r=>{this.emit(e,r)}))}))}}class o{#t;#o;#n;constructor(e,r){this.#t=e,this.#o=r,this.#n={}}send(e,r={}){this.#o.send(e,{...r,room:this.#t})}on(e,r){if(["message"].indexOf(e)<0)throw new Error("You can only subscribe to the 'message' event on rooms");this.#n[e]||=[],this.#n[e].push(r)}execute(e,r,s={}){return this.#o.execute(e,r,{...s,room:this.#t})}process(e){this.#n.message||=[],this.#n.message.forEach((r=>{r(e)}))}}var n=new Uint8Array(16);function i(){if(!e&&!(e="undefined"!=typeof crypto&&crypto.getRandomValues&&crypto.getRandomValues.bind(crypto)||"undefined"!=typeof msCrypto&&"function"==typeof msCrypto.getRandomValues&&msCrypto.getRandomValues.bind(msCrypto)))throw new Error("crypto.getRandomValues() not supported. See https://github.com/uuidjs/uuid#getrandomvalues-not-supported");return e(n)}const a=/^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i,c=function(e){return"string"==typeof e&&a.test(e)};for(var d=[],h=0;h<256;++h)d.push((h+256).toString(16).substr(1));const u=function(e,r,s){var t=(e=e||{}).random||(e.rng||i)();if(t[6]=15&t[6]|64,t[8]=63&t[8]|128,r){s=s||0;for(var o=0;o<16;++o)r[s+o]=t[o];return r}return function(e){var r=arguments.length>1&&void 0!==arguments[1]?arguments[1]:0,s=(d[e[r+0]]+d[e[r+1]]+d[e[r+2]]+d[e[r+3]]+"-"+d[e[r+4]]+d[e[r+5]]+"-"+d[e[r+6]]+d[e[r+7]]+"-"+d[e[r+8]]+d[e[r+9]]+"-"+d[e[r+10]]+d[e[r+11]]+d[e[r+12]]+d[e[r+13]]+d[e[r+14]]+d[e[r+15]]).toLowerCase();if(!c(s))throw TypeError("Stringified UUID is invalid");return s}(t)};class l extends t{#i;#a;constructor(e){super(e),this.#i={},this.#a={}}send(e,r={}){super.send(JSON.stringify({headers:r,body:e}))}connect(){super.connect(),this.on("message",(e=>{const r=JSON.parse(e.data);if(!r.headers)return;const s=r.headers["in-reply-to"];if(s){const e=this.#a[s];e&&(e.resolve(r),delete this.#a[s])}return r.headers.room?this.#i[r.headers.room].process(r):void 0}))}execute(e,r={},s={}){const t=u();return new Promise(((o,n)=>{this.#a[t]={resolve:o,reject:n},this.send(r,{...s,command:e,"reply-to":t})}))}room(e){return this.#i[e]||=new o(e,this)}}StartbackWebsocket=s})();

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