gemstack-realtime 0.3.6 → 0.4.0

data/lib/gemstack/realtime.rb

@@ -6,17 +6,20 @@ require "gemstack/schema"
 require "gemstack/http"
 
 module GemStack
-  # Realtime updates to browsers (ARCHITECTURE §10).
+  # Realtime between server and browsers (ARCHITECTURE §10, docs/realtime.md).
   #
   #   GemStack.broadcast("orders:#{order.id}", "order.updated", order)   # anywhere: controllers, jobs, console
   #
-  #   // browser
+  #   // browser (frontend/lib/gemstack/realtime.ts)
   #   realtime.subscribe(`orders:${id}`, (event) => { ... })
+  #   await realtime.send("rooms:1", "message.create", { body })        // handled by `receive`
   #
-  # Transport: Server-Sent Events on `<api_path>/realtime`, one multiplexed
-  # stream per browser tab, served off the server's request threads. Fan-out
-  # between processes goes through a broker (PostgreSQL LISTEN/NOTIFY, or
-  # Redis). Channels are deny-by-default: declare them in config/channels.rb.
+  # Transports: one connection per browser tab on `<api_path>/realtime` (the
+  # same origin as the API) — a WebSocket, or a Server-Sent Events stream plus
+  # POSTs — held by an event loop off the server's request threads. Both carry
+  # subscriptions, client messages, presence and replay after reconnects.
+  # Fan-out between processes goes through a broker (PostgreSQL LISTEN/NOTIFY,
+  # or Redis). Channels are deny-by-default: declare them in config/channels.rb.
   module Realtime
     class Config < Settings
       setting :path, default: -> { "#{GemStack.config.http.api_path}/realtime" }
@@ -31,12 +34,32 @@ module GemStack
         else :memory
         end
       }
-      # Seconds between keep-alive comments (keeps proxies from closing idle streams).
+      # Seconds between WebSocket pings (keeps proxies from closing idle
+      # connections); a client silent for three heartbeats is disconnected.
       setting :heartbeat, default: 15
       # Recent events kept per process for Last-Event-ID replay after reconnects.
       setting :replay_size, default: 1_000
       setting :replay_ttl, default: 300
       setting :max_channels, default: 50
+      # Largest WebSocket message a browser may send (bytes); larger closes with 1009.
+      setting :max_message_size, default: 64 * 1024
+      # Subscribe/unsubscribe/message requests per connection per second.
+      setting :max_messages_per_second, default: 20
+      # Threads that run channel authorization and `receive` handlers.
+      setting :workers, default: 4
+      # Origins allowed to open a WebSocket. nil: the API's own origin plus
+      # config.http.cors.origins (browsers always send Origin; this blocks
+      # cross-site WebSocket hijacking).
+      setting :allowed_origins, default: nil
+      # Seconds between presence refreshes; an entry lapses after three.
+      setting :presence_interval, default: 15
+      # Seconds a dropped connection stays present (covers reconnects).
+      setting :presence_grace, default: 3
+      # Which transports the endpoint serves: :websocket (one connection,
+      # both directions) and :sse (Server-Sent Events down, POST up — works
+      # wherever plain HTTP does). The browser client's NEXT_PUBLIC_GEMSTACK_REALTIME
+      # picks one; "auto" tries WebSocket first and falls back to SSE.
+      setting :transports, default: %i[websocket sse]
       # A client that falls this far behind (bytes buffered) is disconnected.
       setting :max_buffer, default: 1024 * 1024
       # Reconnect delay the browser is told to use (ms).
@@ -54,7 +77,11 @@ module GemStack
     Message = Struct.new(:id, :channel, :event, :data) do
       def to_h = { id: id, channel: channel, event: event, data: data }
       def json = @json ||= HTTP::JSONCodec.default.dump(to_h)
-      def sse = "id: #{id}\ndata: #{json}\n\n"
+      # Without an id (presence changes, system events) there's no id line: an
+      # empty one would reset the browser's Last-Event-ID.
+      def sse = "#{"id: #{id}\n" if id}data: #{json}\n\n"
+      # Encoded once per broadcast, however many connections receive it.
+      def ws_frame = @ws_frame ||= WebSocket::Codec.text(%({"type":"event",#{json.delete_prefix("{")}))
 
       def self.from_json(string)
         hash = JSON.parse(string)
@@ -81,6 +108,28 @@ module GemStack
         @channels ||= Channels.new
       end
 
+      def presence
+        @presence || @mutex.synchronize { @presence ||= Presence.new }
+      end
+
+      # Who is on a presence channel right now, across processes:
+      #   GemStack::Realtime.present_on("rooms:1") # => [{ "id" => "7", "meta" => { "name" => "Ada" } }]
+      def present_on(channel) = presence.list(channel.to_s)
+
+      # identify's result → [key, meta] for presence. A Hash needs an :id; a
+      # model is keyed by #id; anything else by its string form.
+      def identity_key(identity)
+        case identity
+        when nil then nil
+        when Hash
+          meta = identity.transform_keys(&:to_s)
+          meta["id"].nil? ? nil : [meta["id"].to_s, meta]
+        else
+          id = identity.respond_to?(:id) ? identity.id : identity
+          [id.to_s, { "id" => id.to_s }]
+        end
+      end
+
       def build_broker(setting)
         case setting
         when :postgres, "postgres" then Brokers::Postgres.new
@@ -127,55 +176,107 @@ module GemStack
         @broker = nil
         @hub&.shutdown
         @hub = nil
+        @presence&.stop
+        @presence = nil
         @listening = nil
       end
 
-      private
-
       def next_id = "#{Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)}-#{SecureRandom.hex(4)}"
     end
 
-    # Channel authorization (config/channels.rb):
+    # config/channels.rb — what browsers may do, deny-by-default:
     #
     #   GemStack.channels do
-    #     channel "announcements"                       # anyone may subscribe
-    #     channel "orders:*" do |order_id, request|     # * = one segment, passed to the block
-    #       Order.find_by(id: order_id)&.visible_to?(current_user(request))
+    #     # Who is connecting (once per connection, from the handshake's cookies
+    #     # or headers); nil for anonymous. A Hash ({ id:, name: }) is also the
+    #     # presence metadata others see.
+    #     identify { |request| current_user(request)&.then { |user| { id: user.id, name: user.name } } }
+    #
+    #     channel "announcements"                        # anyone may subscribe
+    #     channel "orders:*" do |order_id, request|      # * = one segment, passed to the block
+    #       Order.find_by(id: order_id)&.user_id == identity(request)&.fetch(:id)
     #     end
-    #   end
+    #     channel "rooms:*", presence: true do |room_id, request| … end   # + who's here
     #
-    # Channels that match no rule are refused (403).
+    #     # Messages browsers send with realtime.send(channel, event, data);
+    #     # only to channels they're subscribed to. The return value is the reply.
+    #     receive "rooms:*" do |message|
+    #       post = Post.create!(room_id: message.params.first, body: message.data["body"],
+    #                           user_id: message.identity[:id])
+    #       GemStack.broadcast(message.channel, "post.created", post)
+    #     end
+    #   end
     class Channels
-      Rule = Struct.new(:pattern, :regex, :block)
+      Rule = Struct.new(:pattern, :regex, :block, :presence)
+      IDENTITY = "gemstack.realtime.identity"
 
       def initialize
         @rules = []
+        @receivers = []
+        @identify = nil
       end
 
       def draw(&) = instance_exec(&)
-      def clear = @rules.clear
       def rules = @rules.dup
 
-      def channel(pattern, &block)
-        pattern = pattern.to_s
-        unless pattern.split(":").all? { |part| part == "*" || CHANNEL_NAME.match?(part) }
-          raise ArgumentError, "invalid channel pattern #{pattern.inspect}"
-        end
+      def clear
+        @rules.clear
+        @receivers.clear
+        @identify = nil
+      end
+
+      def channel(pattern, presence: false, &block)
+        @rules << Rule.new(pattern.to_s, compile(pattern), block, presence)
+      end
+
+      def receive(pattern, &block)
+        raise ArgumentError, "receive needs a block" unless block
 
-        regex = Regexp.new("\\A#{pattern.split(":").map do |part|
-          part == "*" ? "([^:]+)" : Regexp.escape(part)
-        end.join(":")}\\z")
-        @rules << Rule.new(pattern, regex, block)
+        @receivers << Rule.new(pattern.to_s, compile(pattern), block, false)
       end
 
-      def authorized?(name, request)
+      def identify(&block)
+        @identify = block
+      end
+
+      # The identity of the connection a handshake request belongs to.
+      def identity(request) = request.env[IDENTITY]
+
+      def identify_request(request)
+        request.env[IDENTITY] = @identify&.call(request)
+      end
+
+      # The rule allowing `name`, or nil (the first matching rule decides).
+      def authorize(name, request)
         @rules.each do |rule|
           match = rule.regex.match(name) or next
-          return true unless rule.block
+          return rule if rule.block.nil? || rule.block.call(*match.captures, request)
 
-          return rule.block.call(*match.captures, request) ? true : false
+          return nil
+        end
+        nil
+      end
+
+      def authorized?(name, request) = !authorize(name, request).nil?
+
+      # [handler, params] for a message to `name`, or nil.
+      def receiver(name)
+        @receivers.each do |rule|
+          match = rule.regex.match(name) or next
+          return [rule.block, match.captures]
         end
-        false
+        nil
+      end
+
+      private
+
+      def compile(pattern)
+        pattern = pattern.to_s
+        unless pattern.split(":").all? { |part| part == "*" || CHANNEL_NAME.match?(part) }
+          raise ArgumentError, "invalid channel pattern #{pattern.inspect}"
+        end
+
+        Regexp.new("\\A#{pattern.split(":").map { |part| part == "*" ? "([^:]+)" : Regexp.escape(part) }.join(":")}\\z")
       end
     end
   end
@@ -192,9 +293,13 @@ module GemStack
   end
 end
 
+require_relative "realtime/websocket/codec"
 require_relative "realtime/hub"
+require_relative "realtime/presence"
+require_relative "realtime/dispatcher"
 require_relative "realtime/connection"
 require_relative "realtime/streamer"
+require_relative "realtime/websocket/connection"
 require_relative "realtime/middleware"
 require_relative "realtime/brokers/memory"
 require_relative "realtime/brokers/test"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-realtime
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: 0.4.0
 platform: ruby
 authors:
 - Adware Technologies
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.6
+        version: 0.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.3.6
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: nio4r
   requirement: !ruby/object:Gem::Requirement
@@ -53,10 +53,14 @@ files:
 - lib/gemstack/realtime/brokers/redis.rb
 - lib/gemstack/realtime/brokers/test.rb
 - lib/gemstack/realtime/connection.rb
+- lib/gemstack/realtime/dispatcher.rb
 - lib/gemstack/realtime/hub.rb
 - lib/gemstack/realtime/middleware.rb
+- lib/gemstack/realtime/presence.rb
 - lib/gemstack/realtime/streamer.rb
 - lib/gemstack/realtime/testing.rb
+- lib/gemstack/realtime/websocket/codec.rb
+- lib/gemstack/realtime/websocket/connection.rb
 homepage: https://github.com/gemstack-rb/gemstack
 licenses:
 - MIT
@@ -82,5 +86,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: 'GemStack realtime: GemStack.broadcast to browsers over Server-Sent Events'
+summary: 'GemStack realtime (WebSockets or Server-Sent Events): broadcasts, channels,
+  presence, messages'
 test_files: []