gemstack-realtime 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 383b5db1904ae2687941a4af6aac241b9d4a4d37e3187ae92f751fdbbe762b18
+  data.tar.gz: ac673f15bb730c70e0cce0da8c7fc6390905bf2bd18dd887fdd4222f866c8430
+SHA512:
+  metadata.gz: 76449b084ad86256f962c403afba444ee180a3b9add95f26f4fcb4ee25b7e093f7e01945931e0e5483ad543016e12e04647a0e6f805409facb75aadbde7b1ba1
+  data.tar.gz: 1b8310889e833012342f8b890217c496d639c7323b8f7b5339157d8ea3ae2cd3e05237c0f4cb05255f7daaea416f588d43d1fcb2ef75437c1f74d6a74f8425c7

data/CHANGELOG.md

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+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/README.md

@@ -0,0 +1,28 @@
+# gemstack-realtime
+
+GemStack realtime: GemStack.broadcast to browsers over Server-Sent Events.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Optional module — `gemstack add realtime`:
+
+```ruby
+gem "gemstack-realtime", "~> 0.1"
+```
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/realtime.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-realtime`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/realtime/brokers/memory.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    module Brokers
+      # Delivers within the current process only (the default without a
+      # database). Broadcasts made inside a database transaction are sent
+      # after it commits, like with the PostgreSQL broker.
+      class Memory
+        def start(&on_message)
+          @on_message = on_message
+          self
+        end
+
+        def publish(message)
+          after_commit { @on_message&.call(message) }
+        end
+
+        def stop = @on_message = nil
+
+        private
+
+        def after_commit(&)
+          db = defined?(GemStack::DB) && GemStack::DB.connected? ? GemStack::DB.connection : nil
+          db&.in_transaction? ? db.after_commit(&) : yield
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/brokers/postgres.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    module Brokers
+      # Fan-out between processes with PostgreSQL LISTEN/NOTIFY (the default
+      # with gemstack-db): a broadcast from a job worker reaches browsers
+      # connected to any API process, with no extra infrastructure.
+      #
+      # NOTIFY is transactional, so a broadcast inside a transaction is
+      # delivered only if — and when — it commits. Payloads are limited to
+      # ~8 KB by PostgreSQL: broadcast what changed (ids, small records) and
+      # let clients refetch larger data.
+      class Postgres
+        CHANNEL = "gemstack_realtime"
+        MAX_PAYLOAD = 7_900
+
+        def initialize(db: nil)
+          @db = db
+        end
+
+        def db
+          @db || begin
+            require "gemstack/db"
+            GemStack::DB.connection
+          end
+        end
+
+        def publish(message)
+          payload = message.json
+          if payload.bytesize > MAX_PAYLOAD
+            raise PayloadTooLarge, "realtime payload is #{payload.bytesize} bytes; the PostgreSQL broker allows " \
+                                   "#{MAX_PAYLOAD}. Broadcast ids or a smaller serializer, or use the Redis broker."
+          end
+          db.notify(CHANNEL, payload: payload)
+        end
+
+        # Listens on a dedicated connection in a background thread.
+        def start(&on_message)
+          @running = true
+          ready = Queue.new
+          @thread = Thread.new { listen(on_message, ready) }
+          ready.pop(timeout: 5)
+          self
+        end
+
+        def stop
+          @running = false
+          @thread&.join(2)
+        end
+
+        private
+
+        def listen(on_message, ready)
+          while @running
+            begin
+              db.listen(CHANNEL, loop: ->(_conn) { throw :stop unless @running }, timeout: 1,
+                                 after_listen: ->(_conn) { ready << true }) do |_channel, _pid, payload|
+                deliver(on_message, payload)
+              end
+            rescue Sequel::Error => e
+              GemStack.logger.warn("realtime: LISTEN failed, retrying", error: e.message)
+              sleep 1
+            end
+          end
+        end
+
+        def deliver(on_message, payload)
+          on_message.call(Message.from_json(payload))
+        rescue StandardError => e
+          GemStack.logger.error("realtime: delivery failed", error: e)
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/brokers/redis.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    module Brokers
+      # Fan-out through Redis pub/sub (add `gem "redis-client"`). Use it for
+      # large payloads or very high broadcast rates. Broadcasts inside a
+      # database transaction are published after commit.
+      class Redis
+        def initialize(url: Realtime.config.redis_url, channel: Realtime.config.redis_channel)
+          require "redis-client"
+          @config = RedisClient.config(url: url)
+          @channel = channel
+          @publisher = @config.new_pool(size: 5, timeout: 1.0)
+        rescue LoadError
+          raise ConfigurationError, 'the Redis realtime broker needs `gem "redis-client"` in the Gemfile'
+        end
+
+        def publish(message)
+          after_commit { @publisher.call("PUBLISH", @channel, message.json) }
+        end
+
+        def start(&on_message)
+          @running = true
+          ready = Queue.new
+          @thread = Thread.new { listen(on_message, ready) }
+          ready.pop(timeout: 5)
+          self
+        end
+
+        def stop
+          @running = false
+          @thread&.join(2)
+        end
+
+        private
+
+        def listen(on_message, ready)
+          while @running
+            begin
+              pubsub = @config.new_client.pubsub
+              pubsub.call("SUBSCRIBE", @channel)
+              ready << true
+              while @running
+                event = pubsub.next_event(1) or next
+                deliver(on_message, event[2]) if event[0] == "message"
+              end
+            rescue RedisClient::Error => e
+              GemStack.logger.warn("realtime: Redis subscription failed, retrying", error: e.message)
+              sleep 1
+            ensure
+              pubsub&.close
+            end
+          end
+        end
+
+        def deliver(on_message, payload)
+          on_message.call(Message.from_json(payload))
+        rescue StandardError => e
+          GemStack.logger.error("realtime: delivery failed", error: e)
+        end
+
+        def after_commit(&)
+          db = defined?(GemStack::DB) && GemStack::DB.connected? ? GemStack::DB.connection : nil
+          db&.in_transaction? ? db.after_commit(&) : yield
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/brokers/test.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    module Brokers
+      # Records broadcasts for assertions (the default in tests); see
+      # GemStack::Realtime::Testing.
+      class Test
+        attr_reader :messages
+
+        def initialize
+          @messages = []
+          @mutex = Mutex.new
+        end
+
+        def start(&on_message)
+          @on_message = on_message
+          self
+        end
+
+        def publish(message)
+          @mutex.synchronize { @messages << message }
+          @on_message&.call(message)
+        end
+
+        def clear = @mutex.synchronize { @messages.clear }
+        def stop = @on_message = nil
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/connection.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    # One browser's event stream on a hijacked socket. #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
+
+      def initialize(io, channels, streamer:, max_buffer: Realtime.config.max_buffer)
+        @io = io
+        @channels = channels.freeze
+        @streamer = streamer
+        @max_buffer = max_buffer
+        @buffer = String.new(encoding: Encoding::BINARY)
+        @mutex = Mutex.new
+        @closed = false
+      end
+
+      def closed? = @closed
+      def pending? = @mutex.synchronize { !@buffer.empty? }
+
+      def push(bytes)
+        wants_write = @mutex.synchronize do
+          return false if @closed
+
+          @buffer << bytes.b
+          if @buffer.bytesize > @max_buffer
+            GemStack.logger.warn("realtime: slow client disconnected", buffered: @buffer.bytesize)
+            close_locked
+            return false
+          end
+          !flush_locked
+        end
+        @streamer.want_write(self) if wants_write
+        true
+      end
+
+      # Writes as much as the socket accepts. Returns true when fully flushed.
+      def flush = @mutex.synchronize { @closed || flush_locked }
+
+      def close
+        @mutex.synchronize { close_locked }
+      end
+
+      private
+
+      def flush_locked
+        until @buffer.empty?
+          written = @io.write_nonblock(@buffer, exception: false)
+          return false if written == :wait_writable
+
+          @buffer = @buffer.byteslice(written, @buffer.bytesize) || String.new(encoding: Encoding::BINARY)
+        end
+        true
+      rescue IOError, SystemCallError
+        close_locked
+        true
+      end
+
+      def close_locked
+        return if @closed
+
+        @closed = true
+        @buffer.clear
+        @io.close unless @io.closed?
+        @streamer.closed(self)
+      rescue IOError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/hub.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+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.
+    class Hub
+      Entry = Struct.new(:message, :at)
+
+      def initialize(replay_size: Realtime.config.replay_size, replay_ttl: Realtime.config.replay_ttl)
+        # Identity sets: a subscriber is the same subscriber however its state changes.
+        @subscriptions = Hash.new { |hash, key| hash[key] = Set.new.compare_by_identity }
+        @history = []
+        @replay_size = replay_size
+        @replay_ttl = replay_ttl
+        @mutex = Mutex.new
+      end
+
+      def add(connection)
+        @mutex.synchronize { connection.channels.each { |channel| @subscriptions[channel] << connection } }
+        connection
+      end
+
+      def remove(connection)
+        @mutex.synchronize do
+          connection.channels.each do |channel|
+            subscribers = @subscriptions[channel]
+            subscribers.delete(connection)
+            @subscriptions.delete(channel) if subscribers.empty?
+          end
+        end
+      end
+
+      def connections = @mutex.synchronize { @subscriptions.values.flat_map(&:to_a).uniq(&:object_id) }
+
+      def subscriber_count(channel)
+        @mutex.synchronize { @subscriptions.key?(channel) ? @subscriptions[channel].size : 0 }
+      end
+
+      def deliver(message)
+        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.size
+      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.
+      def replay(channels, last_id)
+        return [[], false] if last_id.nil? || last_id.empty?
+
+        @mutex.synchronize do
+          cutoff = monotonic - @replay_ttl
+          @history.reject! { |entry| entry.at < cutoff }
+          index = @history.rindex { |entry| entry.message.id == last_id }
+          return [[], true] unless index
+
+          [@history[(index + 1)..].map(&:message).select { |m| channels.include?(m.channel) }, false]
+        end
+      end
+
+      def shutdown
+        connections.each(&:close)
+      end
+
+      private
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/gemstack/realtime/middleware.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Realtime
+    # GET <api_path>/realtime?channels=a,b[&last_event_id=...]
+    #
+    # 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.
+    class Middleware
+      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
+
+      def initialize(app, path: nil)
+        @app = app
+        @path = path
+      end
+
+      def call(env)
+        return @app.call(env) unless env[Rack::PATH_INFO] == path && env[Rack::REQUEST_METHOD] == "GET"
+
+        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")
+        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)
+      end
+
+      private
+
+      def path = @path ||= Realtime.config.path
+
+      def requested_channels(request)
+        channels = request.GET["channels"].to_s.split(",").map(&:strip).reject(&:empty?).uniq
+        raise BadRequest.new("Give at least one channel: ?channels=a,b", code: "channels_required") if channels.empty?
+
+        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)
+        if invalid.any?
+          raise InvalidChannel.new("Invalid channel name(s): #{invalid.join(", ")}",
+                                   code: "invalid_channel")
+        end
+
+        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)
+        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
+      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
+      end
+
+      # Servers without full hijack: stream from the request thread (holds it
+      # for the life of the connection).
+      def stream(channels, preamble)
+        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)
+        [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
+
+        def initialize(channels, preamble)
+          @channels = channels.freeze
+          @queue = Queue.new
+          @queue << preamble
+          Realtime.hub.add(self)
+        end
+
+        def push(bytes) = @queue << bytes
+        def closed? = @queue.closed?
+
+        def each
+          while (chunk = @queue.pop)
+            yield chunk
+          end
+        end
+
+        def close
+          Realtime.hub.remove(self)
+          @queue.close
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/streamer.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "nio"
+
+module GemStack
+  module Realtime
+    # A single event-loop thread (nio4r) that owns every open stream in the
+    # process: it notices disconnects (readable + EOF), flushes buffered
+    # writes when sockets become writable, and sends heartbeats. Request
+    # threads only hand connections over, so 10,000 open streams cost no
+    # server threads.
+    class Streamer
+      def initialize(heartbeat: Realtime.config.heartbeat, hub: Realtime.hub)
+        @heartbeat = heartbeat
+        @hub = hub
+        @selector = NIO::Selector.new
+        @commands = Queue.new
+        @monitors = {}
+        @thread = nil
+        @mutex = Mutex.new
+      end
+
+      def self.instance
+        @mutex ||= Mutex.new
+        @instance || @mutex.synchronize { @instance ||= new.start }
+      end
+
+      def self.reset!
+        @instance&.stop
+        @instance = nil
+      end
+
+      def start
+        @running = true
+        @thread = Thread.new { run }
+        self
+      end
+
+      def stop
+        @running = false
+        @selector.wakeup
+        @thread&.join(2)
+        @monitors.each_key(&:close)
+      end
+
+      def size = @monitors.size
+
+      # Called from request threads.
+      def add(connection) = command(:add, connection)
+      def want_write(connection) = command(:write, connection)
+      def closed(connection) = command(:remove, connection)
+
+      private
+
+      def command(name, connection)
+        @commands << [name, connection]
+        @selector.wakeup
+      end
+
+      def run
+        next_beat = monotonic + @heartbeat
+        while @running
+          @selector.select([next_beat - monotonic, 0.01].max) { |monitor| ready(monitor) }
+          drain_commands
+          next if monotonic < next_beat
+
+          @monitors.each_key { |connection| connection.push(": ping\n\n") }
+          next_beat = monotonic + @heartbeat
+        end
+      rescue StandardError => e
+        GemStack.logger.error("realtime streamer crashed", error: e, backtrace: Array(e.backtrace).first(10))
+        retry if @running
+      end
+
+      def drain_commands
+        until @commands.empty?
+          name, connection = @commands.pop
+          case name
+          when :add then register(connection)
+          when :write then @monitors[connection]&.interests = :rw
+          when :remove then deregister(connection)
+          end
+        end
+      end
+
+      def register(connection)
+        return if connection.closed? || @monitors.key?(connection)
+
+        monitor = @selector.register(connection.io, connection.pending? ? :rw : :r)
+        monitor.value = connection
+        @monitors[connection] = monitor
+      rescue IOError, SystemCallError
+        connection.close
+      end
+
+      def deregister(connection)
+        monitor = @monitors.delete(connection) or return
+        monitor.close
+        @hub.remove(connection)
+      end
+
+      def ready(monitor)
+        connection = monitor.value
+        if monitor.readable?
+          # SSE clients never send data after the request; readable means EOF.
+          data = connection.io.read_nonblock(1024, exception: false)
+          return connection.close if data.nil?
+        end
+        return unless monitor.writable?
+
+        monitor.interests = :r if connection.flush
+      rescue IOError, SystemCallError
+        connection.close
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/gemstack/realtime/testing.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "gemstack/realtime"
+
+module GemStack
+  module Realtime
+    # Test helpers (included into GemStack::TestCase by the generated test helper):
+    #
+    #   def test_updating_an_order_notifies_its_viewers
+    #     patch_json "/api/orders/#{order.id}", { status: "shipped" }
+    #
+    #     assert_broadcast "orders:#{order.id}", "order.updated"
+    #   end
+    module Testing
+      def self.included(base)
+        base.class_eval do
+          def before_setup
+            super
+            GemStack::Realtime.broker = GemStack::Realtime::Brokers::Test.new
+          end
+        end
+      end
+
+      def broadcasts = Realtime.broker.messages
+
+      # A broadcast on channel (optionally with this event name / data) happened.
+      def assert_broadcast(channel, event = nil, data: nil)
+        expected = data.nil? ? nil : as_json(data)
+        matching = broadcasts.select do |m|
+          m.channel == channel && (event.nil? || m.event == event.to_s) &&
+            (expected.nil? || as_json(m.data) == expected)
+        end
+        assert(!matching.empty?,
+               "Expected a broadcast on #{channel}#{" (#{event})" if event}; got #{broadcasts.map do |m|
+                 [m.channel, m.event]
+               end}")
+      end
+
+      # What a browser receives (string keys, decimals as strings, ...).
+      def as_json(value) = JSON.parse(HTTP::JSONCodec.default.dump(value))
+
+      def refute_broadcast(channel)
+        assert(broadcasts.none? { |m| m.channel == channel }, "Expected no broadcast on #{channel}")
+      end
+    end
+  end
+end

data/lib/gemstack/realtime.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "gemstack/core"
+require "gemstack/schema"
+require "gemstack/http"
+
+module GemStack
+  # Realtime updates to browsers (ARCHITECTURE §10, DECISIONS D-044).
+  #
+  #   GemStack.broadcast("orders:#{order.id}", "order.updated", order)   # anywhere: controllers, jobs, console
+  #
+  #   // browser
+  #   realtime.subscribe(`orders:${id}`, (event) => { ... })
+  #
+  # 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 by
+  # default). 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" }
+      # :postgres (default with gemstack-db), :memory (single process),
+      # :redis, :test (default in tests), or a broker object.
+      setting :broker, default: lambda {
+        if GemStack.env.test? then :test
+        elsif defined?(GemStack::DB) then :postgres
+        else :memory
+        end
+      }
+      # Seconds between keep-alive comments (keeps proxies from closing idle streams).
+      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
+      # 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).
+      setting :retry_ms, default: 3_000
+      setting :redis_url, default: -> { ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
+      setting :redis_channel, default: -> { "gemstack:realtime:#{GemStack.config.name}" }
+    end
+
+    CHANNEL_NAME = /\A[A-Za-z0-9_\-.:]{1,200}\z/
+
+    class InvalidChannel < BadRequest; end
+    class PayloadTooLarge < Error; end
+
+    # One broadcast.
+    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"
+
+      def self.from_json(string)
+        hash = JSON.parse(string)
+        new(hash["id"], hash["channel"], hash["event"], hash["data"])
+      end
+    end
+
+    @mutex = Mutex.new
+
+    class << self
+      def config = GemStack.config.realtime
+
+      def broker
+        @broker || @mutex.synchronize { @broker ||= build_broker(config.broker) }
+      end
+
+      attr_writer :broker
+
+      def hub
+        @hub || @mutex.synchronize { @hub ||= Hub.new }
+      end
+
+      def channels
+        @channels ||= Channels.new
+      end
+
+      def build_broker(setting)
+        case setting
+        when :postgres, "postgres" then Brokers::Postgres.new
+        when :memory, "memory" then Brokers::Memory.new
+        when :redis, "redis" then Brokers::Redis.new
+        when :test, "test" then Brokers::Test.new
+        else
+          unless setting.respond_to?(:publish)
+            raise ConfigurationError,
+                  "a realtime broker must respond to #publish and #start"
+          end
+
+          setting
+        end
+      end
+
+      def broadcast(channel, event, data = nil, context: {})
+        channel = channel.to_s
+        raise InvalidChannel, "invalid channel name #{channel.inspect}" unless CHANNEL_NAME.match?(channel)
+
+        message = Message.new(next_id, channel, event.to_s, Serializer.render(data, context))
+        broker.publish(message)
+        GemStack.logger.debug("realtime.broadcast", channel: channel, event: message.event, id: message.id)
+        message.id
+      end
+
+      # Starts delivering broker messages to this process's connections (idempotent).
+      def listen!
+        return true if @listening
+
+        # Resolve these before locking: both lazily take the same mutex.
+        active_broker = broker
+        active_hub = hub
+        @mutex.synchronize do
+          @listening ||= begin
+            active_broker.start { |message| active_hub.deliver(message) }
+            true
+          end
+        end
+      end
+
+      def reset!
+        @broker&.stop if @broker.respond_to?(:stop)
+        @broker = nil
+        @hub&.shutdown
+        @hub = nil
+        @listening = nil
+      end
+
+      private
+
+      def next_id = "#{Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)}-#{SecureRandom.hex(4)}"
+    end
+
+    # Channel authorization (config/channels.rb):
+    #
+    #   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))
+    #     end
+    #   end
+    #
+    # Channels that match no rule are refused (403).
+    class Channels
+      Rule = Struct.new(:pattern, :regex, :block)
+
+      def initialize
+        @rules = []
+      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
+
+        regex = Regexp.new("\\A#{pattern.split(":").map do |part|
+          part == "*" ? "([^:]+)" : Regexp.escape(part)
+        end.join(":")}\\z")
+        @rules << Rule.new(pattern, regex, block)
+      end
+
+      def authorized?(name, request)
+        @rules.each do |rule|
+          match = rule.regex.match(name) or next
+          return true unless rule.block
+
+          return rule.block.call(*match.captures, request) ? true : false
+        end
+        false
+      end
+    end
+  end
+
+  class << self
+    def broadcast(...) = Realtime.broadcast(...)
+
+    # config/channels.rb: GemStack.channels { channel "announcements" }
+    def channels(&)
+      return Realtime.channels unless block_given?
+
+      Realtime.channels.draw(&)
+    end
+  end
+end
+
+require_relative "realtime/hub"
+require_relative "realtime/connection"
+require_relative "realtime/streamer"
+require_relative "realtime/middleware"
+require_relative "realtime/brokers/memory"
+require_relative "realtime/brokers/test"
+require_relative "realtime/brokers/postgres"
+require_relative "realtime/brokers/redis"
+
+GemStack::Config.namespace(:realtime, GemStack::Realtime::Config)
+
+GemStack::Plugins.register(:realtime) do |app|
+  next unless app.respond_to?(:root)
+
+  stack = app.config.http.middleware
+  unless stack.include?(GemStack::Realtime::Middleware)
+    stack.insert_before(GemStack::HTTP::Middleware::HealthCheck, GemStack::Realtime::Middleware)
+  end
+  channels_file = app.root.join("config/channels.rb")
+  load_channels = lambda do
+    GemStack::Realtime.channels.clear
+    load channels_file.to_s if channels_file.file?
+  end
+  load_channels.call
+  app.on_reload(&load_channels) if app.respond_to?(:on_reload)
+  app.on_shutdown { GemStack::Realtime.reset! } if app.respond_to?(:on_shutdown)
+  # The broker's listener holds one database connection for the process.
+  app.config.db.pool_size += 1 if app.config.realtime.broker.to_s == "postgres" && app.config.respond_to?(:db)
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-realtime
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: gemstack-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: nio4r
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/realtime.rb
+- lib/gemstack/realtime/brokers/memory.rb
+- lib/gemstack/realtime/brokers/postgres.rb
+- lib/gemstack/realtime/brokers/redis.rb
+- lib/gemstack/realtime/brokers/test.rb
+- lib/gemstack/realtime/connection.rb
+- lib/gemstack/realtime/hub.rb
+- lib/gemstack/realtime/middleware.rb
+- lib/gemstack/realtime/streamer.rb
+- lib/gemstack/realtime/testing.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-realtime
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-realtime/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack realtime: GemStack.broadcast to browsers over Server-Sent Events'
+test_files: []