gemstack-realtime 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99221dd4e22c0d2d66849a4d1038f8c579c1560bd48a26a65a9c4a7459ac6d16
-  data.tar.gz: 9e2084b4bbe0926eb0920136017d54f627307f76b0bff561db8d46f694677138
+  metadata.gz: 59e752348de1175634362fbae61d888cd27dafc64e137b817864a6142ec79b7d
+  data.tar.gz: 22ce9e17ea1123b4e84e5081279d6b7bf981ed53185044200a03d145751bdc12
 SHA512:
-  metadata.gz: e7343b3dba100bde89e39182e9dde6315ac3ac302abc36ce7ef4e8da8ae6603b7b2ca44870b78aae194707e671d1ab471117d48cf9bf653dc9b646b68f08a81f
-  data.tar.gz: 557727578ba1bc834a3639c5dc0053954a477808a74576562a008c1b5d83315594db500e81d07f2ce248489dee5d69742fdb1d2bb812ce51b378363055dd9866
+  metadata.gz: 0ffddee26789b127d330c8e9659cb0a60dde9aa3963d30de442f3edf4a86d78094f707a315274c29078c14ae52d261f28ecc2e42e9eb47910b66d07179525d1a
+  data.tar.gz: cd9b65c59b693fbcc887678e027e1f3d0f8b20e130fc5dc55bc6f2af8e7f712cbb260bd0fed019c917ad4d13bc39f3a807bb4f932a43ee9ceab8e6eed741c61d

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.4.0
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.3.6
 
 See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,9 +1,9 @@
 # gemstack-realtime
 
-GemStack realtime: GemStack.broadcast to browsers over Server-Sent Events.
+GemStack realtime (WebSockets or Server-Sent Events): broadcasts, channels, presence, browser messages.
 
-Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby web application framework with
+a Next.js frontend, by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
 version.
 
 ## Installation
@@ -11,7 +11,7 @@ version.
 Optional module — `gemstack add realtime`:
 
 ```ruby
-gem "gemstack-realtime", "~> 0.3.6"
+gem "gemstack-realtime", "~> 0.4.0"
 ```
 
 ## Documentation

data/lib/gemstack/realtime/connection.rb

@@ -2,16 +2,19 @@
 
 module GemStack
   module Realtime
-    # One browser's event stream on a hijacked socket. #push never blocks:
+    # One browser connection on a hijacked socket — the Server-Sent Events
+    # stream; WebSocket::Connection builds on it. #push never blocks:
     # bytes the socket can't take yet are buffered and flushed by the
     # Streamer when it becomes writable. A client more than max_buffer bytes
     # behind is disconnected (it reconnects and replays or refetches).
     class Connection
-      attr_reader :io, :channels
+      attr_reader :io, :channels, :identity
 
-      def initialize(io, channels, streamer:, max_buffer: Realtime.config.max_buffer)
+      def initialize(io, channels, streamer:, identity: nil, max_buffer: Realtime.config.max_buffer)
         @io = io
-        @channels = channels.freeze
+        @identity = identity
+        @presence = {} # channel => identity key
+        @channels = Set.new(channels)
         @streamer = streamer
         @max_buffer = max_buffer
         @buffer = String.new(encoding: Encoding::BINARY)
@@ -22,6 +25,30 @@ module GemStack
       def closed? = @closed
       def pending? = @mutex.synchronize { !@buffer.empty? }
 
+      # Transport hooks: how a broadcast and a keep-alive are written. The
+      # keep-alive is a data event (comments are invisible to EventSource), so
+      # the browser can tell a quiet connection from a dead one.
+      def deliver(message) = push(message.sse)
+      def heartbeat = push(PING)
+      PING = "data: #{JSON.generate(id: nil, channel: nil, event: "gemstack.ping", data: nil)}\n\n".freeze
+
+      # SSE presence: the stream's presence channels, tracked while it's open.
+      def track_presence(channel)
+        key, meta = Realtime.identity_key(identity)
+        return [] unless key
+
+        @presence[channel] = key
+        Realtime.presence.track(channel, key, meta)
+        list = Realtime.presence.list(channel)
+        list.any? { |entry| entry["id"] == key } ? list : list + [{ "id" => key, "meta" => meta }]
+      end
+
+      # Called by the Streamer once the socket is gone.
+      def disconnected
+        @presence.each { |channel, key| Realtime.presence.untrack_later(channel, key) }
+        @presence.clear
+      end
+
       def push(bytes)
         wants_write = @mutex.synchronize do
           return false if @closed
@@ -38,8 +65,26 @@ module GemStack
         true
       end
 
-      # Writes as much as the socket accepts. Returns true when fully flushed.
-      def flush = @mutex.synchronize { @closed || flush_locked }
+      # Writes as much as the socket accepts. Returns true when fully flushed
+      # (and closes the socket if #close_after_flush asked for it).
+      def flush
+        @mutex.synchronize do
+          return true if @closed
+
+          flushed = flush_locked
+          close_locked if flushed && @close_after_flush
+          flushed
+        end
+      end
+
+      # Sends what's buffered, then closes (e.g. after a WebSocket close frame).
+      def close_after_flush
+        done = @mutex.synchronize do
+          @close_after_flush = true
+          flush_locked.tap { |flushed| close_locked if flushed }
+        end
+        @streamer.want_write(self) unless done
+      end
 
       def close
         @mutex.synchronize { close_locked }

data/lib/gemstack/realtime/dispatcher.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    # Runs application code for WebSocket connections — channel authorization
+    # and `receive` handlers — on a small thread pool, never on the event loop,
+    # so a slow query can't stall other connections. A connection's messages
+    # are handled one at a time, in the order they arrived (Connection keeps
+    # the inbox; the dispatcher only lends it a thread). Code runs under the
+    # application's interlock, like a request, so it never overlaps a reload.
+    class Dispatcher
+      def self.instance
+        @mutex ||= Mutex.new
+        @instance || @mutex.synchronize { @instance ||= new }
+      end
+
+      def self.reset!
+        @instance&.stop
+        @instance = nil
+      end
+
+      def initialize(size: Realtime.config.workers)
+        @queue = Queue.new
+        @threads = Array.new(size) { Thread.new { work } }
+      end
+
+      # Asks a worker to run connection.process_inbox (or a callable).
+      def schedule(connection) = @queue << connection
+
+      def stop
+        @queue.close
+        @threads.each { |thread| thread.join(2) }
+      end
+
+      private
+
+      # In an app (require "gemstack"), under its interlock so code reloading
+      # waits; the realtime gem used on its own has no application.
+      def with_application(&)
+        GemStack.respond_to?(:application) ? GemStack.application.interlock.shared(&) : yield
+      end
+
+      def work
+        while (connection = @queue.pop)
+          begin
+            with_application { connection.respond_to?(:process_inbox) ? connection.process_inbox : connection.call }
+          rescue StandardError => e
+            GemStack.logger.error("realtime: handler crashed", error: e, backtrace: Array(e.backtrace).first(10))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/hub.rb

@@ -2,8 +2,10 @@
 
 module GemStack
   module Realtime
-    # This process's subscriptions and replay history. The broker's listener
-    # calls #deliver; connections are only ever written to without blocking.
+    # This process's subscriptions and replay history, whatever the transport.
+    # The broker's listener calls #deliver; each connection encodes the message
+    # for its transport (a WebSocket frame, or an SSE event) and is only ever
+    # written to without blocking.
     class Hub
       Entry = Struct.new(:message, :at)
 
@@ -21,6 +23,23 @@ module GemStack
         connection
       end
 
+      # WebSocket connections subscribe and unsubscribe while open.
+      def subscribe(connection, channel)
+        @mutex.synchronize do
+          connection.channels << channel
+          @subscriptions[channel] << connection
+        end
+      end
+
+      def unsubscribe(connection, channel)
+        @mutex.synchronize do
+          connection.channels.delete(channel)
+          subscribers = @subscriptions[channel]
+          subscribers.delete(connection)
+          @subscriptions.delete(channel) if subscribers.empty?
+        end
+      end
+
       def remove(connection)
         @mutex.synchronize do
           connection.channels.each do |channel|
@@ -38,16 +57,25 @@ module GemStack
       end
 
       def deliver(message)
+        return Realtime.presence.receive(message) if message.channel == Presence::CHANNEL
+
         subscribers = @mutex.synchronize do
           @history << Entry.new(message, monotonic)
           @history.shift while @history.size > @replay_size
           @subscriptions.key?(message.channel) ? @subscriptions[message.channel].to_a : []
         end
-        payload = message.sse
-        subscribers.each { |connection| connection.push(payload) }
+        subscribers.each { |connection| connection.deliver(message) }
         subscribers.size
       end
 
+      # To this process's subscribers only, without replay history (presence changes).
+      def deliver_local(message)
+        subscribers = @mutex.synchronize do
+          @subscriptions.key?(message.channel) ? @subscriptions[message.channel].to_a : []
+        end
+        subscribers.each { |connection| connection.deliver(message) }
+      end
+
       # Events on `channels` published after the event with id `last_id`.
       # Returns [messages, gap]; gap is true when last_id is no longer in the
       # history, so the client may have missed events and should refetch.

data/lib/gemstack/realtime/middleware.rb

@@ -1,18 +1,26 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module GemStack
   module Realtime
-    # GET <api_path>/realtime?channels=a,b[&last_event_id=...]
+    # The realtime endpoint, <api_path>/realtime, with two transports
+    # (config.realtime.transports) behind the same channels, presence and
+    # handlers:
+    #
+    #   GET  + Upgrade: websocket   WebSocket: everything over one connection
+    #                               (WebSocket::Connection has the protocol)
+    #   GET  ?channels=a,b          Server-Sent Events: the stream of events
+    #        [&last_event_id=…]     for those channels (reopened to change them)
+    #   POST {channel, event, data} a browser message for a `receive` handler,
+    #                               when it isn't on a WebSocket
     #
-    # Validates and authorizes the channels (400 as a JSON error; 403 only when
-    # none is allowed — refused channels otherwise get a gemstack.denied event), then
-    # takes the socket over from the server (Rack full hijack, supported by
-    # Puma) and hands it to the Streamer, freeing the request thread. The
-    # response is a standard text/event-stream: events missed since
-    # Last-Event-ID are replayed first, or a `gemstack.gap` event tells the
-    # client to refetch because they're no longer available.
+    # Every request checks the Origin (the API's own, config.http.cors.origins
+    # or realtime.allowed_origins) and runs config/channels.rb's `identify`.
+    # Long-lived connections take the socket over from the server (Rack full
+    # hijack, as Puma supports) and live on the Streamer's event loop.
     class Middleware
-      HEADERS = [
+      SSE_HEADERS = [
         "HTTP/1.1 200 OK", "content-type: text/event-stream; charset=utf-8", "cache-control: no-cache, no-transform",
         "x-accel-buffering: no", "x-content-type-options: nosniff", "connection: close"
       ].freeze
@@ -23,25 +31,98 @@ module GemStack
       end
 
       def call(env)
-        return @app.call(env) unless env[Rack::PATH_INFO] == path && env[Rack::REQUEST_METHOD] == "GET"
+        return @app.call(env) unless env[Rack::PATH_INFO] == path
 
         request = Rack::Request.new(env)
-        requested = requested_channels(request)
-        channels, denied = requested.partition { |channel| Realtime.channels.authorized?(channel, request) }
-        if channels.empty?
-          raise Forbidden.new("Not allowed to subscribe to #{denied.join(", ")}",
-                              code: "channel_forbidden")
+        unless allowed_origin?(request)
+          raise Forbidden.new("Cross-origin realtime request refused",
+                              code: "origin_forbidden")
         end
 
-        Realtime.listen!
-        last_id = env["HTTP_LAST_EVENT_ID"] || request.GET["last_event_id"]
-        preamble = preamble(channels, last_id, denied)
-        env["rack.hijack?"] ? hijack(env, channels, preamble) : stream(channels, preamble)
+        case env[Rack::REQUEST_METHOD]
+        when "GET"
+          websocket = env["HTTP_UPGRADE"].to_s.casecmp?("websocket")
+          return transport_disabled(websocket ? :websocket : :sse) unless enabled?(websocket ? :websocket : :sse)
+
+          websocket ? WebSocketHandshake.call(env, request) : stream(env, request)
+        when "POST"
+          enabled?(:sse) ? Messages.call(request) : transport_disabled(:sse)
+        else
+          raise MethodNotAllowed.new("Use GET or POST", headers: { "allow" => "GET, POST" })
+        end
       end
 
       private
 
       def path = @path ||= Realtime.config.path
+      def enabled?(transport) = Realtime.config.transports.map(&:to_sym).include?(transport)
+
+      def transport_disabled(transport)
+        if transport == :websocket
+          raise NotFound.new("The WebSocket transport is disabled (config.realtime.transports)",
+                             code: "transport_disabled")
+        end
+
+        body = JSON.generate(error: { code: "transport_disabled",
+                                      message: "Server-Sent Events are disabled; use WebSocket" })
+        [426, { "upgrade" => "websocket", "content-type" => "application/json" }, [body]]
+      end
+
+      # Browsers always send Origin with a WebSocket or a POST; same-origin
+      # GETs and other clients (servers, mobile apps) may not, and aren't
+      # subject to cross-site hijacking.
+      def allowed_origin?(request)
+        origin = request.get_header("HTTP_ORIGIN")
+        return true if origin.nil? || origin.empty?
+
+        allowed = Realtime.config.allowed_origins
+        return allowed.include?(origin) if allowed
+        return true if GemStack.config.http.cors.origins.include?(origin)
+
+        same_origin?(request, origin)
+      end
+
+      def same_origin?(request, origin)
+        uri = URI.parse(origin)
+        uri.host.to_s.casecmp?(request.host) && uri.port == request.port
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # The stream's response bypasses the CORS middleware: an allowed other
+      # origin (EventSource withCredentials) needs these itself.
+      def cors_headers(request)
+        origin = request.get_header("HTTP_ORIGIN")
+        return [] if origin.nil? || origin.empty? || same_origin?(request, origin)
+
+        ["access-control-allow-origin: #{origin}", "access-control-allow-credentials: true", "vary: Origin"]
+      end
+
+      # ── Server-Sent Events ───────────────────────────────────────────────
+
+      # Authorizes each channel (a refused one gets `gemstack.denied` and the
+      # others keep working), tracks presence, replays what was missed since
+      # Last-Event-ID — or sends `gemstack.gap` — then streams.
+      def stream(env, request)
+        requested = requested_channels(request)
+        identity = Realtime.channels.identify_request(request)
+        rules = requested.to_h { |channel| [channel, Realtime.channels.authorize(channel, request)] }
+        channels = rules.select { |_, rule| rule }.keys
+        Realtime.listen!
+        last_id = env["HTTP_LAST_EVENT_ID"] || request.GET["last_event_id"]
+        return stream_on_request_thread(channels, identity, last_id, rules) unless env["rack.hijack?"]
+
+        io = env["rack.hijack"].call
+        io.write("#{(SSE_HEADERS + cors_headers(request)).join("\r\n")}\r\n\r\n")
+        streamer = Streamer.instance
+        connection = Connection.new(io, channels, streamer: streamer, identity: identity)
+        # Presence first, before the hub delivers to it: its own join isn't news to it.
+        text = preamble(connection, rules)
+        Realtime.hub.add(connection)
+        connection.push(text << replay(connection, last_id))
+        streamer.add(connection)
+        [200, {}, []] # ignored by the server after a full hijack
+      end
 
       def requested_channels(request)
         channels = request.GET["channels"].to_s.split(",").map(&:strip).reject(&:empty?).uniq
@@ -50,7 +131,7 @@ module GemStack
         max = Realtime.config.max_channels
         raise BadRequest.new("At most #{max} channels per connection", code: "too_many_channels") if channels.size > max
 
-        invalid = channels.grep_v(CHANNEL_NAME)
+        invalid = channels.grep_v(CHANNEL_NAME) + (channels & [Presence::CHANNEL])
         if invalid.any?
           raise InvalidChannel.new("Invalid channel name(s): #{invalid.join(", ")}",
                                    code: "invalid_channel")
@@ -59,54 +140,59 @@ module GemStack
         channels
       end
 
-      # One multiplexed stream serves many subscriptions, so a refused channel
-      # doesn't fail the others: its handlers get a `gemstack.denied` event.
-      def preamble(channels, last_id, denied)
-        messages, gap = Realtime.hub.replay(channels, last_id)
+      def preamble(connection, rules)
         text = "retry: #{Realtime.config.retry_ms}\n\n"
-        denied.each { |channel| text << system_event("gemstack.denied", channel) }
-        messages.each { |message| text << message.sse }
-        text << system_event("gemstack.gap", nil) if gap
+        text << system_event("gemstack.welcome", nil, { "connection_id" => SecureRandom.hex(8), "transport" => "sse",
+                                                        "heartbeat" => Realtime.config.heartbeat })
+        rules.each do |channel, rule|
+          if rule.nil?
+            text << system_event("gemstack.denied", channel, "forbidden")
+          elsif rule.presence
+            text << system_event("gemstack.presence", channel, connection.track_presence(channel))
+          end
+        end
         text
       end
 
-      def system_event(name, channel) = "data: #{Message.new(nil, channel, name, nil).json}\n\n"
-
-      def hijack(env, channels, preamble)
-        io = env["rack.hijack"].call
-        io.write("#{HEADERS.join("\r\n")}\r\n\r\n")
-        streamer = Streamer.instance
-        connection = Connection.new(io, channels, streamer: streamer)
-        Realtime.hub.add(connection)
-        connection.push(preamble)
-        streamer.add(connection)
-        [200, {}, []] # ignored by the server after a full hijack
+      def replay(connection, last_id)
+        messages, gap = Realtime.hub.replay(connection.channels.to_a, last_id.to_s)
+        text = messages.map(&:sse).join
+        gap ? text + system_event("gemstack.gap", nil) : text
       end
 
+      def system_event(name, channel, data = nil) = "data: #{Message.new(nil, channel, name, data).json}\n\n"
+
       # Servers without full hijack: stream from the request thread (holds it
-      # for the life of the connection).
-      def stream(channels, preamble)
+      # for the life of the connection; no presence).
+      def stream_on_request_thread(channels, identity, last_id, rules)
         unless @warned
           GemStack.logger.warn("realtime: server doesn't support rack.hijack; streaming on a request thread")
         end
         @warned = true
-        body = QueueBody.new(channels, preamble)
+        body = QueueBody.new(channels, identity)
+        body.push(rules.filter_map do |channel, rule|
+          system_event("gemstack.denied", channel, "forbidden") unless rule
+        end.join)
+        messages, gap = Realtime.hub.replay(channels, last_id.to_s)
+        messages.each { |message| body.push(message.sse) }
+        body.push(system_event("gemstack.gap", nil)) if gap
         [200, { "content-type" => "text/event-stream; charset=utf-8", "cache-control" => "no-cache, no-transform" },
          body]
       end
 
       # A Rack body fed by the hub (fallback path). Closing it unsubscribes.
       class QueueBody
-        attr_reader :channels
+        attr_reader :channels, :identity
 
-        def initialize(channels, preamble)
+        def initialize(channels, identity)
           @channels = channels.freeze
+          @identity = identity
           @queue = Queue.new
-          @queue << preamble
           Realtime.hub.add(self)
         end
 
         def push(bytes) = @queue << bytes
+        def deliver(message) = push(message.sse)
         def closed? = @queue.closed?
 
         def each
@@ -121,5 +207,81 @@ module GemStack
         end
       end
     end
+
+    # The WebSocket opening handshake: validates it, runs `identify` while the
+    # request's cookies are at hand, then hands the socket to the Streamer.
+    module WebSocketHandshake
+      module_function
+
+      def call(env, request)
+        key = env["HTTP_SEC_WEBSOCKET_KEY"]
+        unless env["HTTP_CONNECTION"].to_s.downcase.include?("upgrade") && WebSocket::Codec.valid_key?(key)
+          raise BadRequest.new("Invalid WebSocket handshake", code: "invalid_handshake")
+        end
+        unless env["HTTP_SEC_WEBSOCKET_VERSION"] == "13"
+          return [426, { "sec-websocket-version" => "13", "content-type" => "text/plain" }, ["WebSocket version 13"]]
+        end
+        unless env["rack.hijack?"]
+          raise ServiceUnavailable.new("WebSockets need a server with Rack hijacking, such as Puma",
+                                       code: "websocket_unsupported")
+        end
+
+        identity = Realtime.channels.identify_request(request)
+        Realtime.listen!
+        io = env["rack.hijack"].call
+        io.write(WebSocket::Codec.handshake_response(key))
+        streamer = Streamer.instance
+        connection = WebSocket::Connection.new(io, request: request, identity: identity, streamer: streamer)
+        connection.welcome
+        streamer.add(connection)
+        [200, {}, []] # ignored by the server after a full hijack
+      end
+    end
+
+    # POST <api_path>/realtime {"channel", "event", "data"} — a browser message
+    # for a `receive` handler over plain HTTP (the SSE transport's way up).
+    # Allowed when the sender may subscribe to the channel. The handler's
+    # return value is the response's "data"; its errors are the usual JSON
+    # error envelope.
+    module Messages
+      module_function
+
+      def call(request)
+        unless request.media_type == "application/json"
+          raise UnsupportedMediaType.new("Send JSON", code: "unsupported_media_type")
+        end
+
+        body = request.body.read(Realtime.config.max_message_size + 1).to_s
+        if body.bytesize > Realtime.config.max_message_size
+          raise GemStack::PayloadTooLarge.new("Message too large",
+                                              code: "message_too_big")
+        end
+
+        message = JSON.parse(body)
+        raise BadRequest.new("Expected a JSON object", code: "invalid_message") unless message.is_a?(Hash)
+
+        handle(request, message["channel"].to_s, message["event"].to_s, message["data"])
+      rescue JSON::ParserError
+        raise BadRequest.new("Invalid JSON", code: "invalid_json")
+      end
+
+      def handle(request, channel, event, data)
+        raise InvalidChannel.new("Invalid channel #{channel.inspect}", code: "invalid_channel") unless
+          CHANNEL_NAME.match?(channel) && channel != Presence::CHANNEL
+
+        Realtime.channels.identify_request(request)
+        Realtime.channels.authorize(channel, request) or
+          raise Forbidden.new("Not allowed on #{channel}", code: "forbidden")
+        handler, params = Realtime.channels.receiver(channel)
+        raise NotFound.new("#{channel} doesn't accept messages", code: "no_handler") unless handler
+
+        sender = Sender.new(request, request.env[Channels::IDENTITY])
+        result = handler.call(WebSocket::Incoming.new(channel, event, data, params, sender))
+        [200, { "content-type" => "application/json" },
+         [HTTP::JSONCodec.default.dump({ data: Serializer.render(result) })]]
+      end
+
+      Sender = Struct.new(:request, :identity)
+    end
   end
 end