gemstack-realtime 0.3.6 → 0.4.0

data/lib/gemstack/realtime/presence.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GemStack
+  module Realtime
+    # Who is on a presence channel (`channel "rooms:*", presence: true`),
+    # across every process.
+    #
+    # Each process counts its own connections per (channel, identity) and
+    # announces the first join and the last leave through the broker, then
+    # re-announces what it has every `presence_interval` seconds. Every process
+    # (this one included) builds the same registry from those announcements;
+    # an entry a process stops refreshing — it crashed or lost its broker —
+    # expires after three intervals. Browsers get `presence.join`/`presence.leave`
+    # when an identity appears or disappears (a second tab is not a new join).
+    class Presence
+      # Broker-only channel; browsers can't subscribe to it.
+      CHANNEL = "gemstack:presence"
+      # Keeps each announcement under the PostgreSQL broker's payload limit.
+      BATCH = 50
+
+      def initialize(interval: Realtime.config.presence_interval, grace: Realtime.config.presence_grace)
+        @interval = interval
+        @ttl = interval * 3
+        @grace = grace
+        @later = Queue.new
+        @mutex = Mutex.new
+        @local = {}   # [channel, key] => { count:, meta: }
+        @state = {}   # channel => { key => { meta:, nodes: { node => expires_at } } }
+      end
+
+      # This process's id; a forked process (Puma worker) gets its own.
+      def node
+        return @node if @node_pid == Process.pid
+
+        @node_pid = Process.pid
+        @node = "#{Process.pid}-#{SecureRandom.hex(4)}"
+      end
+
+      # A connection identified as `key` subscribed to a presence channel.
+      def track(channel, key, meta)
+        first = @mutex.synchronize do
+          entry = (@local[[channel, key]] ||= { count: 0, meta: meta })
+          entry[:count] += 1
+          entry[:count] == 1
+        end
+        start_timer
+        announce("join", [[channel, key, meta]]) if first
+      end
+
+      def untrack(channel, key)
+        last = @mutex.synchronize do
+          entry = @local[[channel, key]] or return
+          entry[:count] -= 1
+          @local.delete([channel, key]) if entry[:count] <= 0
+          entry[:count] <= 0
+        end
+        announce("leave", [[channel, key, nil]]) if last
+      end
+
+      # A dropped connection leaves only after `presence_grace` seconds, so a
+      # reconnect (or an SSE stream reopened with other channels) doesn't
+      # flicker the user out and back in. Runs off the event loop.
+      def untrack_later(channel, key)
+        @later << [monotonic + @grace, channel, key]
+        @mutex.synchronize { @leaver = Thread.new { leave_loop } unless @leaver&.alive? }
+      end
+
+      # [{ "id" => key, "meta" => {...} }, ...] for a channel, across processes.
+      def list(channel)
+        @mutex.synchronize do
+          (@state[channel] || {}).map { |key, entry| { "id" => key, "meta" => entry[:meta] } }
+        end
+      end
+
+      # An announcement from the broker (from any process, this one included).
+      def receive(message)
+        node = message.data["node"]
+        changes = @mutex.synchronize do
+          message.data["entries"].filter_map do |channel, key, meta|
+            if message.event == "leave"
+              [:leave, channel, key, nil] if drop(channel, key, node)
+            elsif add(channel, key, meta, node)
+              [:join, channel, key, meta]
+            end
+          end
+        end
+        notify(changes)
+      end
+
+      # Re-announces this process's entries and expires everyone else's stale ones.
+      def tick
+        entries = @mutex.synchronize { @local.map { |(channel, key), entry| [channel, key, entry[:meta]] } }
+        entries.each_slice(BATCH) { |batch| announce("refresh", batch) }
+        notify(@mutex.synchronize { expire })
+      end
+
+      def stop
+        [@timer, @leaver].each { |thread| thread&.kill }
+        @timer = @leaver = nil
+      end
+
+      private
+
+      def add(channel, key, meta, node)
+        entry = ((@state[channel] ||= {})[key] ||= { meta: meta, nodes: {} })
+        fresh = entry[:nodes].empty?
+        entry[:meta] = meta if meta
+        entry[:nodes][node] = monotonic + @ttl
+        fresh
+      end
+
+      def drop(channel, key, node)
+        entry = @state.dig(channel, key) or return false
+        entry[:nodes].delete(node)
+        return false unless entry[:nodes].empty?
+
+        remove(channel, key)
+        true
+      end
+
+      def expire
+        now = monotonic
+        lapsed = @state.flat_map do |channel, keys|
+          keys.filter_map do |key, entry|
+            entry[:nodes].delete_if { |_, expires_at| expires_at < now }
+            [:leave, channel, key, nil] if entry[:nodes].empty?
+          end
+        end
+        lapsed.each { |_, channel, key, _| remove(channel, key) }
+      end
+
+      def remove(channel, key)
+        @state[channel].delete(key)
+        @state.delete(channel) if @state[channel].empty?
+      end
+
+      def notify(changes)
+        changes.each do |op, channel, key, meta|
+          event = Message.new(nil, channel, "presence.#{op}", { "id" => key, "meta" => meta }.compact)
+          Realtime.hub.deliver_local(event)
+        end
+      end
+
+      def announce(kind, entries)
+        Realtime.broker.publish(Message.new(Realtime.next_id, CHANNEL, kind, { "node" => node, "entries" => entries }))
+      rescue StandardError => e
+        GemStack.logger.warn("realtime: presence announcement failed", error: e)
+      end
+
+      def start_timer
+        return if @timer&.alive? # a forked process has no timer thread: it starts one
+
+        @mutex.synchronize do
+          @timer = Thread.new { timer_loop } unless @timer&.alive?
+        end
+      end
+
+      # Same delay for everyone, so the queue is in due order.
+      def leave_loop
+        while (due, channel, key = @later.pop)
+          wait = due - monotonic
+          sleep(wait) if wait.positive?
+          untrack(channel, key)
+        end
+      rescue StandardError => e
+        GemStack.logger.warn("realtime: presence leave failed", error: e)
+        retry
+      end
+
+      def timer_loop
+        loop do
+          sleep @interval
+          begin
+            tick
+          rescue StandardError => e
+            GemStack.logger.warn("realtime: presence refresh failed", error: e)
+          end
+        end
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/gemstack/realtime/streamer.rb

@@ -4,11 +4,11 @@ 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.
+    # A single event-loop thread (nio4r) that owns every open connection in
+    # the process: it reads what clients send (WebSocket frames; for SSE only
+    # the EOF of a disconnect), flushes buffered writes when sockets become
+    # writable, and sends each transport's heartbeat. Request threads only
+    # hand connections over, so 10,000 open connections cost no server threads.
     class Streamer
       def initialize(heartbeat: Realtime.config.heartbeat, hub: Realtime.hub)
         @heartbeat = heartbeat
@@ -64,7 +64,7 @@ module GemStack
           drain_commands
           next if monotonic < next_beat
 
-          @monitors.each_key { |connection| connection.push(": ping\n\n") }
+          @monitors.each_key(&:heartbeat)
           next_beat = monotonic + @heartbeat
         end
       rescue StandardError => e
@@ -97,14 +97,17 @@ module GemStack
         monitor = @monitors.delete(connection) or return
         monitor.close
         @hub.remove(connection)
+        connection.disconnected if connection.respond_to?(:disconnected)
       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?
+          data = connection.io.read_nonblock(16 * 1024, exception: false)
+          return connection.close if data.nil? # EOF: the client went away
+
+          # WebSocket frames; SSE clients send nothing after the request.
+          connection.receive(data) if data.is_a?(String) && connection.respond_to?(:receive)
         end
         return unless monitor.writable?
 

data/lib/gemstack/realtime/testing.rb

@@ -21,7 +21,7 @@ module GemStack
         end
       end
 
-      def broadcasts = Realtime.broker.messages
+      def broadcasts = Realtime.broker.messages.reject { |m| m.channel == Presence::CHANNEL }
 
       # A broadcast on channel (optionally with this event name / data) happened.
       def assert_broadcast(channel, event = nil, data: nil)

data/lib/gemstack/realtime/websocket/codec.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module GemStack
+  module Realtime
+    module WebSocket
+      # The wire format of RFC 6455 for the server side: the opening handshake,
+      # an incremental frame parser for (masked) client frames and the encoder
+      # for (unmasked) server frames. No extensions are negotiated. It only
+      # turns bytes into messages and back; Connection decides what they mean,
+      # so another implementation can replace it.
+      module Codec
+        GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+        OPCODES = { continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xA }.freeze
+        NAMES = OPCODES.invert.freeze
+
+        # Close codes (RFC 6455 §7.4.1).
+        NORMAL = 1000
+        GOING_AWAY = 1001
+        PROTOCOL_ERROR = 1002
+        UNSUPPORTED_DATA = 1003
+        INVALID_PAYLOAD = 1007
+        POLICY_VIOLATION = 1008
+        MESSAGE_TOO_BIG = 1009
+        INTERNAL_ERROR = 1011
+
+        class Error < StandardError
+          attr_reader :code
+
+          def initialize(message, code: PROTOCOL_ERROR)
+            super(message)
+            @code = code
+          end
+        end
+
+        module_function
+
+        # Sec-WebSocket-Accept for a client's Sec-WebSocket-Key.
+        def accept_key(key) = [Digest::SHA1.digest("#{key}#{GUID}")].pack("m0")
+
+        # A valid Sec-WebSocket-Key is 16 random bytes, base64-encoded.
+        def valid_key?(key) = key.to_s.match?(%r{\A[A-Za-z0-9+/]{22}==\z})
+
+        def handshake_response(key)
+          "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" \
+            "Sec-WebSocket-Accept: #{accept_key(key)}\r\n\r\n"
+        end
+
+        def text(string) = frame(:text, string.encode(Encoding::UTF_8))
+        def ping(payload = "") = frame(:ping, payload)
+        def pong(payload = "") = frame(:pong, payload)
+        def close(code = NORMAL, reason = "") = frame(:close, [code].pack("n") + reason.to_s.byteslice(0, 123))
+
+        # One final, unmasked frame.
+        def frame(type, payload)
+          payload = payload.b
+          length = payload.bytesize
+          head = [0x80 | OPCODES.fetch(type)].pack("C")
+          head << if length < 126 then [length].pack("C")
+                  elsif length < 65_536 then [126, length].pack("Cn")
+                  else [127, length].pack("CQ>")
+                  end
+          head << payload
+        end
+
+        # Applies (or removes) a 4-byte masking key.
+        def unmask(payload, mask)
+          return payload if payload.empty?
+
+          key = mask.unpack("C4")
+          bytes = payload.unpack("C*")
+          bytes.each_index { |i| bytes[i] ^= key[i & 3] }
+          bytes.pack("C*")
+        end
+
+        # feed(bytes) yields [:text, String] / [:ping, String] / [:pong, String] /
+        # [:close, code, reason] as complete messages arrive (fragmented messages
+        # are reassembled; control frames may arrive between fragments). Raises
+        # Codec::Error, with the close code to send, on any protocol violation.
+        class Parser
+          def initialize(max_message_size:)
+            @max = max_message_size
+            @buffer = String.new(encoding: Encoding::BINARY)
+            @fragments = nil
+          end
+
+          def feed(bytes)
+            @buffer << bytes.b
+            while (frame = next_frame)
+              message = assemble(*frame)
+              yield message if message
+            end
+          end
+
+          private
+
+          # [opcode, fin, payload] of the next complete frame, or nil.
+          def next_frame
+            return nil if @buffer.bytesize < 2
+
+            first, second = @buffer.unpack("CC")
+            raise Error, "reserved bits set (no extensions are negotiated)" if first.anybits?(0x70)
+            raise Error, "client frames must be masked" unless second.anybits?(0x80)
+
+            fin = first.anybits?(0x80)
+            opcode = first & 0x0F
+            length, offset = payload_length(second & 0x7F)
+            return nil unless length
+
+            control = opcode >= 0x8
+            raise Error, "control frames can't be fragmented or exceed 125 bytes" if control && (!fin || length > 125)
+            raise Error.new("message is larger than #{@max} bytes", code: MESSAGE_TOO_BIG) if length > @max
+            return nil if @buffer.bytesize < offset + 4 + length
+
+            mask = @buffer.byteslice(offset, 4)
+            payload = Codec.unmask(@buffer.byteslice(offset + 4, length), mask)
+            @buffer = @buffer.byteslice(offset + 4 + length, @buffer.bytesize)
+            [opcode, fin, payload]
+          end
+
+          def payload_length(short)
+            case short
+            when 126
+              return nil if @buffer.bytesize < 4
+
+              [@buffer.byteslice(2, 2).unpack1("n"), 4]
+            when 127
+              return nil if @buffer.bytesize < 10
+
+              length = @buffer.byteslice(2, 8).unpack1("Q>")
+              raise Error, "invalid payload length" if length >= 2**63
+
+              [length, 10]
+            else [short, 2]
+            end
+          end
+
+          def assemble(opcode, fin, payload)
+            case NAMES[opcode]
+            when :ping, :pong then [NAMES[opcode], payload]
+            when :close then close_frame(payload)
+            when :text, :binary then start_message(opcode, fin, payload)
+            when :continuation then continue_message(fin, payload)
+            else raise Error, "unknown opcode #{opcode}"
+            end
+          end
+
+          def close_frame(payload)
+            return [:close, NORMAL, ""] if payload.empty?
+            raise Error, "close frame with a 1-byte payload" if payload.bytesize == 1
+
+            reason = payload.byteslice(2, payload.bytesize).force_encoding(Encoding::UTF_8)
+            raise Error.new("close reason isn't UTF-8", code: INVALID_PAYLOAD) unless reason.valid_encoding?
+
+            [:close, payload.unpack1("n"), reason]
+          end
+
+          def start_message(opcode, fin, payload)
+            raise Error, "new message before the previous one finished" if @fragments
+
+            @type = opcode
+            @fragments = payload
+            fin ? finish_message : nil
+          end
+
+          def continue_message(fin, payload)
+            raise Error, "continuation frame without a message" unless @fragments
+            if @fragments.bytesize + payload.bytesize > @max
+              raise Error.new("message is larger than #{@max} bytes", code: MESSAGE_TOO_BIG)
+            end
+
+            @fragments << payload
+            fin ? finish_message : nil
+          end
+
+          def finish_message
+            data = @fragments
+            @fragments = nil
+            raise Error.new("binary messages aren't supported", code: UNSUPPORTED_DATA) if @type == OPCODES[:binary]
+
+            text = data.force_encoding(Encoding::UTF_8)
+            raise Error.new("text message isn't valid UTF-8", code: INVALID_PAYLOAD) unless text.valid_encoding?
+
+            [:text, text]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/realtime/websocket/connection.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module GemStack
+  module Realtime
+    module WebSocket
+      # One browser's WebSocket. Frames are parsed on the event loop; anything
+      # that runs application code (authorizing a subscription, a `receive`
+      # handler) goes through the connection's inbox to the Dispatcher, in order.
+      #
+      # Messages are JSON objects with a "type":
+      #
+      #   browser → server
+      #     { type: "subscribe", channel, last_id?, ref? }   replays events after last_id
+      #     { type: "unsubscribe", channel, ref? }
+      #     { type: "message", channel, event, data?, ref? } handled by `receive` in config/channels.rb
+      #     { type: "ping" }
+      #
+      #   server → browser
+      #     { type: "welcome", connection_id, heartbeat }
+      #     { type: "subscribed", channel, ref?, presence? } / { type: "unsubscribed", channel, ref? }
+      #     { type: "denied", channel, ref?, code }          the channel was refused
+      #     { type: "event", id, channel, event, data }      a broadcast
+      #     { type: "gap", channel }                         events missed while away are gone: refetch
+      #     { type: "presence", channel, event: "join"|"leave", id, meta? }
+      #     { type: "reply", ref, ok, data? | error? }       the result of a "message"
+      #     { type: "error", code, message }  { type: "pong" }
+      class Connection < Realtime::Connection
+        attr_reader :id, :request, :identity
+
+        MAX_INBOX = 100
+
+        def initialize(io, request:, identity:, streamer:, dispatcher: Dispatcher.instance,
+                       max_buffer: Realtime.config.max_buffer)
+          super(io, [], streamer: streamer, max_buffer: max_buffer)
+          @id = SecureRandom.hex(8)
+          @request = request
+          @identity = identity
+          @dispatcher = dispatcher
+          @parser = Codec::Parser.new(max_message_size: Realtime.config.max_message_size)
+          @inbox = []
+          @inbox_mutex = Mutex.new
+          @processing = false
+          @presence = {} # channel => identity key
+          @last_seen = monotonic
+          @window = [monotonic.floor, 0]
+        end
+
+        def welcome = send_json(type: "welcome", connection_id: id, heartbeat: Realtime.config.heartbeat)
+
+        # ── event loop ───────────────────────────────────────────────────
+
+        def deliver(message)
+          if message.event.start_with?("presence.")
+            send_json(type: "presence", channel: message.channel, event: message.event.delete_prefix("presence."),
+                      **message.data.transform_keys(&:to_sym))
+          else
+            push(message.ws_frame)
+          end
+        end
+
+        # A ping frame every heartbeat; a client silent for three is gone.
+        def heartbeat
+          return fail_connection(Codec::GOING_AWAY, "heartbeat timeout") if silent?
+
+          push(Codec.ping)
+        end
+
+        def receive(bytes)
+          @last_seen = monotonic
+          @parser.feed(bytes) { |type, payload, reason| frame(type, payload, reason) }
+        rescue Codec::Error => e
+          fail_connection(e.code, e.message)
+        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
+
+        # ── dispatcher ───────────────────────────────────────────────────
+
+        def process_inbox
+          while (message = next_message)
+            handle(message) unless closed?
+          end
+        end
+
+        private
+
+        def frame(type, payload, reason)
+          case type
+          when :text then incoming(payload)
+          when :ping then push(Codec.pong(payload))
+          when :close
+            push(Codec.close(payload == 1005 ? Codec::NORMAL : payload, reason.to_s))
+            close_after_flush
+          end
+        end
+
+        def incoming(text)
+          message = JSON.parse(text)
+          return error("invalid_message", "expected a JSON object") unless message.is_a?(Hash)
+
+          case message["type"]
+          when "ping" then send_json(type: "pong")
+          when "subscribe", "unsubscribe", "message" then enqueue(message)
+          else error("unknown_type", "unknown message type #{message["type"].inspect}", message["ref"])
+          end
+        rescue JSON::ParserError
+          error("invalid_json", "messages are JSON objects")
+        end
+
+        def enqueue(message)
+          return reply_error(message["ref"], "rate_limited", "too many messages") if rate_limited?
+
+          start = @inbox_mutex.synchronize do
+            return reply_error(message["ref"], "busy", "too many pending messages") if @inbox.size >= MAX_INBOX
+
+            @inbox << message
+            !@processing && (@processing = true)
+          end
+          @dispatcher.schedule(self) if start
+        end
+
+        def next_message
+          @inbox_mutex.synchronize do
+            @inbox.shift.tap { |message| @processing = false unless message }
+          end
+        end
+
+        def handle(message)
+          case message["type"]
+          when "subscribe" then subscribe(message["channel"].to_s, message["last_id"], message["ref"])
+          when "unsubscribe" then unsubscribe(message["channel"].to_s, message["ref"])
+          when "message" then receive_message(message)
+          end
+        end
+
+        def subscribe(channel, last_id, ref)
+          return send_json(type: "subscribed", channel: channel, ref: ref) if channels.include?(channel)
+          return deny(channel, ref, "invalid_channel") unless subscribable?(channel)
+          return deny(channel, ref, "too_many_channels") if channels.size >= Realtime.config.max_channels
+
+          rule = Realtime.channels.authorize(channel, request) or return deny(channel, ref, "forbidden")
+          tracked = track(channel, rule) # announce first: our own join isn't sent back to us
+          Realtime.hub.subscribe(self, channel)
+          send_json({ type: "subscribed", channel: channel, ref: ref,
+                      presence: presence_list(channel, tracked) }.compact)
+          messages, gap = Realtime.hub.replay([channel], last_id.to_s)
+          messages.each { |message| deliver(message) }
+          send_json(type: "gap", channel: channel) if gap
+        end
+
+        def unsubscribe(channel, ref)
+          Realtime.hub.unsubscribe(self, channel)
+          key = @presence.delete(channel)
+          Realtime.presence.untrack(channel, key) if key
+          send_json({ type: "unsubscribed", channel: channel, ref: ref }.compact)
+        end
+
+        # Presence channels: [key, meta] of an identified connection (tracked),
+        # false for an anonymous one, nil for channels without presence.
+        def track(channel, rule)
+          return nil unless rule.presence
+
+          key, meta = Realtime.identity_key(identity)
+          return false unless key
+
+          @presence[channel] = key
+          Realtime.presence.track(channel, key, meta)
+          [key, meta]
+        end
+
+        # Who's here, including this connection right away (its announcement
+        # may still be travelling through the broker).
+        def presence_list(channel, tracked)
+          return nil if tracked.nil?
+
+          list = Realtime.presence.list(channel)
+          key, meta = tracked
+          return list if !key || list.any? { |entry| entry["id"] == key }
+
+          list + [{ "id" => key, "meta" => meta }]
+        end
+
+        def receive_message(message)
+          channel = message["channel"].to_s
+          ref = message["ref"]
+          return reply_error(ref, "not_subscribed", "subscribe to #{channel} first") unless channels.include?(channel)
+
+          handler, params = Realtime.channels.receiver(channel)
+          return reply_error(ref, "no_handler", "#{channel} doesn't accept messages") unless handler
+
+          incoming = Incoming.new(channel, message["event"].to_s, message["data"], params, self)
+          result = handler.call(incoming)
+          send_json({ type: "reply", ref: ref, ok: true, data: Serializer.render(result) }.compact) if ref
+        rescue GemStack::Error => e
+          reply_error(ref, e.code, e.message)
+        rescue StandardError => e
+          GemStack.logger.error("realtime: receive handler failed", channel: channel, error: e,
+                                                                    backtrace: Array(e.backtrace).first(10))
+          reply_error(ref, "internal_error", "the message couldn't be handled")
+        end
+
+        def subscribable?(channel) = CHANNEL_NAME.match?(channel) && channel != Presence::CHANNEL
+
+        def deny(channel, ref, code) = send_json({ type: "denied", channel: channel, ref: ref, code: code }.compact)
+
+        def reply_error(ref, code, message)
+          return error(code, message) unless ref
+
+          send_json(type: "reply", ref: ref, ok: false, error: { code: code, message: message })
+        end
+
+        def error(code, message, ref = nil)
+          send_json({ type: "error", code: code, message: message, ref: ref }.compact)
+        end
+
+        def send_json(hash) = push(Codec.text(HTTP::JSONCodec.default.dump(hash)))
+
+        def fail_connection(code, reason)
+          GemStack.logger.debug("realtime: closing websocket", code: code, reason: reason)
+          push(Codec.close(code, reason))
+          close_after_flush
+        end
+
+        def silent? = monotonic - @last_seen > Realtime.config.heartbeat * 3
+
+        # At most max_messages_per_second messages that run application code.
+        def rate_limited?
+          second = monotonic.floor
+          @window = [second, 0] unless @window.first == second
+          @window[1] += 1
+          @window[1] > Realtime.config.max_messages_per_second
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # What a `receive` handler gets (config/channels.rb):
+      #   message.channel, message.event, message.data, message.params (the * segments),
+      #   message.identity (from `identify`), message.request (the WebSocket handshake).
+      Incoming = Struct.new(:channel, :event, :data, :params, :connection) do
+        def identity = connection.identity
+        def request = connection.request
+      end
+    end
+  end
+end