supabase-rb 3.1.1 → 3.2.0

data/lib/supabase/realtime/channel.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "callback_safety"
 require_relative "errors"
 require_relative "message"
 require_relative "presence"
 require_relative "push"
+require_relative "timer"
 require_relative "types"
 
 module Supabase
@@ -16,7 +18,7 @@ module Supabase
     #
     # Should be constructed via {Client#channel}, not directly.
     class Channel
-      attr_reader :topic, :params, :state, :join_push, :presence, :pending_pushes
+      attr_reader :topic, :params, :state, :join_push, :presence, :pending_pushes, :rejoin_timer
 
       def initialize(topic, params: nil, socket: nil)
         @topic   = topic
@@ -24,7 +26,7 @@ module Supabase
         @socket  = socket
         @state   = Types::ChannelStates::CLOSED
         @joined_once = false
-        @presence = Presence.new
+        @presence = Presence.new(logger: logger)
 
         @broadcast_callbacks        = []   # [{ event:, callback: }]
         @postgres_changes_callbacks = []   # [{ event:, schema:, table:, filter:, callback: }]
@@ -38,12 +40,31 @@ module Supabase
         @join_push = Push.new(self, Types::ChannelEvents::JOIN, @params)
         @subscribe_callback = nil
 
+        # py rejoin uses `lambda tries: 2**tries` with no cap
+        # (`realtime/_async/channel.py:109-111`). Timer (US-006) bumps `tries`
+        # before invoking this lambda with `tries + 1`, so the curve for the
+        # first five attempts is 4, 8, 16, 32, 64 s — identical to py.
+        @rejoin_timer = Timer.new(
+          callback: -> { rejoin if @joined_once && !leaving? && !closed? },
+          backoff:  ->(tries) { 2.0**tries }
+        )
+
         @join_push
           .receive(Types::AckStatus::OK)      { |p| on_join_ok(p) }
           .receive(Types::AckStatus::ERROR)   { |p| on_join_error(p) }
           .receive(Types::AckStatus::TIMEOUT) { |_| on_join_timeout }
       end
 
+      # Logger used by {CallbackSafety} when a user callback raises. Resolved
+      # lazily from the realtime client (`@socket` in this class is the
+      # {Realtime::Client}, which exposes its injected logger via
+      # `Client#logger`). When the underlying transport doesn't carry a logger
+      # (e.g. tests that pass a bare {TestSocket} as `socket:`), `safe` falls
+      # through to `Kernel#warn`.
+      def logger
+        @socket.respond_to?(:logger) ? @socket.logger : nil
+      end
+
       # ----- State predicates -----
 
       def closed?;  @state == Types::ChannelStates::CLOSED;  end
@@ -65,6 +86,11 @@ module Supabase
 
         inject_postgres_changes_bindings
         @join_push.instance_variable_set(:@ref, @socket&.next_ref)
+        # Make subscribe a one-call entry point: if the caller hasn't already
+        # connected the underlying transport, open it now so the join frame
+        # actually reaches the wire instead of being held forever in the
+        # Client#send_buffer. Matches supabase-py's `channel.subscribe()` ergonomics.
+        @socket.connect if @socket && !@socket.connected?
         send_push(@join_push, register_pending: true)
         self
       end
@@ -231,13 +257,19 @@ module Supabase
         when Types::ChannelEvents::PRESENCE_DIFF
           @presence.sync_diff(message.payload)
         when Types::ChannelEvents::SYSTEM
-          @system_callbacks.each { |cb| cb.call(message.payload) }
+          @system_callbacks.each do |cb|
+            CallbackSafety.safe(logger, "system") { cb.call(message.payload) }
+          end
         when Types::ChannelEvents::CLOSE
           @state = Types::ChannelStates::CLOSED
-          @close_callbacks.each { |cb| cb.call(message.payload) }
+          @close_callbacks.each do |cb|
+            CallbackSafety.safe(logger, "phx_close") { cb.call(message.payload) }
+          end
         when Types::ChannelEvents::ERROR
           @state = Types::ChannelStates::ERRORED
-          @error_callbacks.each { |cb| cb.call(message.payload) }
+          @error_callbacks.each do |cb|
+            CallbackSafety.safe(logger, "phx_error") { cb.call(message.payload) }
+          end
         end
 
         true
@@ -260,7 +292,10 @@ module Supabase
       # so the server filters before sending, instead of shipping every change
       # for the topic and forcing the client to drop most of them. Also flips
       # config.presence.enabled when any presence callback is attached, so the
-      # server starts emitting presence_state/diff frames.
+      # server starts emitting presence_state/diff frames. Finally, pulls the
+      # current socket access_token onto config.access_token so RLS sees the
+      # caller's JWT — private channels reject the join otherwise. The token
+      # source is identical to what set_auth rotates (single source of truth).
       def inject_postgres_changes_bindings
         config = (@join_push.payload["config"] ||= {})
         config["postgres_changes"] = @postgres_changes_callbacks.map do |binding|
@@ -273,6 +308,8 @@ module Supabase
 
         presence_cfg = (config["presence"] ||= {})
         presence_cfg["enabled"] = true if @presence.any_callbacks?
+
+        config["access_token"] = @socket&.access_token
       end
 
       # If a presence callback is added after the channel is already joined,
@@ -296,7 +333,7 @@ module Supabase
           join_ref: @join_push.ref
         )
 
-        if can_send?
+        if can_send?(push)
           if register_pending && push.ref
             @pending_pushes[push.ref] = push
             # Arm the timeout only once the push is actually on the wire — if it
@@ -314,14 +351,15 @@ module Supabase
         @pending_pushes.delete(ref)
       end
 
-      def can_send?
-        # The join push flushes while joining; the leave push flushes while leaving.
-        # Everything else (broadcasts, presence, custom pushes) only sends once joined.
-        [
-          Types::ChannelStates::JOINED,
-          Types::ChannelStates::JOINING,
-          Types::ChannelStates::LEAVING
-        ].include?(@state)
+      # The join push flushes while joining; the leave push flushes while leaving.
+      # Everything else (broadcasts, presence, custom pushes) only sends once
+      # joined — calls made before subscribe() / between subscribe() and the
+      # phx_reply ack are buffered and replayed by flush_push_buffer on JOINED.
+      def can_send?(push)
+        return joining? || joined? if push.equal?(@join_push)
+        return leaving? if push.event == Types::ChannelEvents::LEAVE
+
+        joined?
       end
 
       def dispatch_reply(message)
@@ -341,20 +379,35 @@ module Supabase
         change_type = data["type"]
         schema      = data["schema"]
         table       = data["table"]
+        ids         = message.payload["ids"]
 
         @postgres_changes_callbacks.each do |binding|
           next unless binding[:event] == change_type || binding[:event] == "*"
           next if binding[:schema] && binding[:schema] != schema
           next if binding[:table]  && binding[:table]  != table
-
-          binding[:callback].call(message.payload)
+          # Server-side binding-id routing: once on_join_ok has recorded the
+          # server-assigned :id, an inbound frame's payload.ids tells us which
+          # bindings the server intended to fire. This is how two bindings on
+          # the same (schema, table) but different :filter get demultiplexed —
+          # without it both would fire on every change. Before the join-ack
+          # (no :id yet) we fall through and the legacy event/schema/table
+          # filtering remains the sole gate.
+          next if binding[:id] && ids.is_a?(Array) && !ids.include?(binding[:id])
+
+          CallbackSafety.safe(logger, "postgres_changes:#{binding[:event]}") do
+            binding[:callback].call(message.payload)
+          end
         end
       end
 
       def dispatch_broadcast(message)
         event = message.payload["event"]
         @broadcast_callbacks.each do |binding|
-          binding[:callback].call(message.payload) if binding[:event] == event
+          next unless binding[:event] == event
+
+          CallbackSafety.safe(logger, "broadcast:#{event}") do
+            binding[:callback].call(message.payload)
+          end
         end
       end
 
@@ -391,7 +444,7 @@ module Supabase
             err = Errors::RealtimeError.new(
               "mismatch between server and client bindings for postgres changes"
             )
-            @subscribe_callback&.call(Types::SubscribeStates::CHANNEL_ERROR, err)
+            fire_subscribe_callback(Types::SubscribeStates::CHANNEL_ERROR, err)
             return
           end
 
@@ -399,18 +452,29 @@ module Supabase
         end
 
         @state = Types::ChannelStates::JOINED
+        @rejoin_timer.reset
         flush_push_buffer
-        @subscribe_callback&.call(Types::SubscribeStates::SUBSCRIBED, nil)
+        fire_subscribe_callback(Types::SubscribeStates::SUBSCRIBED, nil)
       end
 
       def on_join_error(payload)
         @state = Types::ChannelStates::ERRORED
-        @subscribe_callback&.call(Types::SubscribeStates::CHANNEL_ERROR, payload)
+        @rejoin_timer.schedule_timeout
+        fire_subscribe_callback(Types::SubscribeStates::CHANNEL_ERROR, payload)
       end
 
       def on_join_timeout
         @state = Types::ChannelStates::ERRORED
-        @subscribe_callback&.call(Types::SubscribeStates::TIMED_OUT, nil)
+        @rejoin_timer.schedule_timeout
+        fire_subscribe_callback(Types::SubscribeStates::TIMED_OUT, nil)
+      end
+
+      def fire_subscribe_callback(state, error_or_payload)
+        return unless @subscribe_callback
+
+        CallbackSafety.safe(logger, "subscribe:#{state}") do
+          @subscribe_callback.call(state, error_or_payload)
+        end
       end
 
       def flush_push_buffer
@@ -421,7 +485,9 @@ module Supabase
 
       def on_leave_ack
         @state = Types::ChannelStates::CLOSED
-        @close_callbacks.each { |cb| cb.call({}) }
+        @close_callbacks.each do |cb|
+          CallbackSafety.safe(logger, "phx_close") { cb.call({}) }
+        end
       end
     end
   end

data/lib/supabase/realtime/client.rb

@@ -3,6 +3,7 @@
 require "json"
 require "uri"
 
+require_relative "callback_safety"
 require_relative "channel"
 require_relative "errors"
 require_relative "message"
@@ -16,35 +17,44 @@ module Supabase
     # and dispatches inbound frames to whichever channel owns the topic.
     #
     # Bring your own {Socket} (e.g. websocket-client-simple adapter or async-websocket
-    # adapter). For unit tests, pass a {TestSocket}.
+    # adapter). For unit tests, pass a {TestSocket}. If no transport is supplied,
+    # a default {Sockets::WebsocketClientSimple} adapter is constructed
+    # automatically so `Supabase.create_client(...).realtime.channel(...).subscribe`
+    # works out of the box.
     #
-    #   socket   = Supabase::Realtime::TestSocket.new
     #   client   = Supabase::Realtime::Client.new(
     #     url: "wss://project.supabase.co/realtime/v1",
-    #     params: { apikey: key },
-    #     socket: socket
+    #     params: { apikey: key }
     #   )
-    #   client.connect
     #
     #   channel = client.channel("realtime:public:users")
     #   channel.on_postgres_changes("*", schema: "public", table: "users") { |p| puts p }
     #   channel.subscribe
     class Client
       attr_reader :url, :params, :access_token, :channels, :socket, :timeout,
-                  :heartbeat_interval, :auto_reconnect, :max_retries, :initial_backoff
+                  :heartbeat_interval, :auto_reconnect, :max_retries, :initial_backoff,
+                  :logger
 
       # @param url    [String] WebSocket endpoint (ws:// or wss://). Plain http(s) are upgraded.
       # @param params [Hash]   query-string params merged onto the URL (e.g. apikey/access_token)
-      # @param socket [Socket, nil] inject your own transport (defaults to nil — caller wires it up)
+      # @param transport [Socket, nil] inject your own transport. If nil, the production
+      #   websocket-client-simple adapter is constructed from URL+params.
+      # @param socket [Socket, nil] deprecated alias for `transport:` — kept for back compat.
       # @param timeout [Numeric] default per-push timeout (seconds)
       # @param heartbeat_interval [Numeric] seconds between automatic heartbeat pushes (0 disables)
       # @param auto_reconnect [Boolean] reconnect on unexpected socket close
       # @param max_retries [Integer] maximum reconnect attempts before giving up
       # @param initial_backoff [Numeric] seconds of delay before the first reconnect attempt;
       #   doubles each attempt up to a 60s cap (matches supabase-py)
-      def initialize(url:, params: {}, socket: nil, timeout: Types::DEFAULT_TIMEOUT_SECONDS,
+      # @param logger [#warn, nil] optional logger for non-fatal events. Used by
+      #   {CallbackSafety} to record exceptions raised inside user-supplied
+      #   channel/presence/push callbacks without killing the read-thread
+      #   (US-002). Falls back to `Kernel#warn` ($stderr) when nil.
+      def initialize(url:, params: {}, transport: nil, socket: nil,
+                     timeout: Types::DEFAULT_TIMEOUT_SECONDS,
                      heartbeat_interval: Types::DEFAULT_HEARTBEAT_INTERVAL_SECONDS,
-                     auto_reconnect: true, max_retries: 5, initial_backoff: 1.0)
+                     auto_reconnect: true, max_retries: 5, initial_backoff: 1.0,
+                     logger: nil)
         unless Transformers.is_ws_url(url)
           raise ArgumentError,
                 "Invalid Realtime URL #{url.inspect}: expected ws://, wss://, http://, or https://"
@@ -53,8 +63,8 @@ module Supabase
         @url     = normalize_url(url, params)
         @params  = params
         @access_token = params[:access_token] || params["access_token"]
-        @channels = {}
-        @socket   = socket
+        @channels = []
+        @socket   = transport || socket || build_default_transport
         @timeout  = timeout
         @ref      = 0
 
@@ -62,15 +72,38 @@ module Supabase
         @auto_reconnect     = auto_reconnect
         @max_retries        = max_retries
         @initial_backoff    = initial_backoff
+        @logger             = logger
         @heartbeat_thread   = nil
         @reconnect_thread   = nil
         @intentionally_closed = false
         @send_buffer        = [] # frames queued while no socket / not connected
         @send_buffer_mutex  = Mutex.new
+        @reconnect_failed_callbacks = []
 
         attach_socket if @socket
       end
 
+      # Register a callback fired exactly once when the background reconnect
+      # loop exhausts `max_retries` without re-establishing the socket. The
+      # callback receives the last underlying exception raised by the
+      # transport's `connect` (or `nil` if no attempt was made — currently
+      # unreachable but kept for forward-compat).
+      #
+      # Why this exists (US-003 / FR-4): supabase-py's `connect()` is a single
+      # coroutine that raises on permanent failure. The rb port runs reconnect
+      # on a background thread, so a `raise` would die unobserved. This
+      # callback is the rb-shaped equivalent — see
+      # `lib/supabase/realtime/README.md` "Realtime reconnect: отличие от
+      # supabase-py".
+      #
+      # Multiple registrations are allowed; each fires in registration order.
+      # The user block is wrapped in {CallbackSafety.safe} so a raise inside
+      # one callback never blocks the next one (consistent with US-002).
+      def on_reconnect_failed(&block)
+        @reconnect_failed_callbacks << block
+        self
+      end
+
       # Plug in a transport after construction (e.g. a websocket-client-simple wrapper).
       def use_socket(socket)
         @socket = socket
@@ -79,7 +112,10 @@ module Supabase
       end
 
       def connect
-        raise Errors::RealtimeError, "no socket attached — call #use_socket(socket) first" unless @socket
+        unless @socket
+          @socket = build_default_transport
+          attach_socket
+        end
 
         @intentionally_closed = false
         @socket.connect
@@ -91,7 +127,7 @@ module Supabase
         stop_reconnect
         stop_heartbeat
         @socket&.close
-        @channels.each_value { |ch| ch.instance_variable_set(:@state, Types::ChannelStates::CLOSED) }
+        @channels.each { |ch| ch.instance_variable_set(:@state, Types::ChannelStates::CLOSED) }
         self
       end
 
@@ -102,8 +138,10 @@ module Supabase
         @socket && @socket.connected?
       end
 
-      # Get or create a Channel for the given topic. Subsequent calls with the
-      # same topic return the same Channel instance, matching phoenix.js semantics.
+      # Always returns a **new** Channel instance, matching supabase-py. The
+      # client-side topic registry is a flat list, so multiple channels can
+      # share a topic (each with its own join_ref / subscription lifecycle).
+      # To look up an existing channel, walk `get_channels.find { |c| c.topic == ... }`.
       #
       # Topic names are auto-prefixed with `"realtime:"` to match supabase-py:
       # `client.channel("public:users")` reaches the same channel as
@@ -111,46 +149,61 @@ module Supabase
       # alone so existing code keeps working.
       def channel(topic, params: nil)
         full_topic = topic.start_with?("realtime:") ? topic : "realtime:#{topic}"
-        @channels[full_topic] ||= Channel.new(full_topic, params: params, socket: self)
+        ch = Channel.new(full_topic, params: params, socket: self)
+        @channels << ch
+        ch
       end
 
       def get_channels
-        @channels.values
+        @channels.dup
       end
 
       def remove_channel(channel)
         channel.unsubscribe
-        @channels.delete(channel.topic)
+        @channels.delete(channel)
+        @socket&.close if @channels.empty?
       end
 
+      # Unsubscribe every tracked channel and clear the registry. Iterates over a
+      # snapshot (`@channels.dup`) so a channel that removes itself during
+      # `unsubscribe` doesn't shift the array mid-loop. Idempotent: a follow-up
+      # call on an empty registry is a no-op.
+      # @see supabase-py supabase/_sync/client.py:234
       def remove_all_channels
-        @channels.values.each { |ch| ch.unsubscribe }
+        @channels.dup.each { |ch| ch.unsubscribe }
         @channels.clear
+        self
       end
 
       # Update the access token, send it to every joined channel so RLS reflects
       # the new auth context, and remember it for future joins.
+      #
+      # Safe to call before `connect`: the token is always written to
+      # `@access_token` / `@params` so the next subscribe picks it up via
+      # `Channel#inject_postgres_changes_bindings`. The ACCESS_TOKEN frame fan-out
+      # only runs once the socket is actually connected.
       def set_auth(token)
         @access_token = token
         @params["access_token"] = token if @params.is_a?(Hash)
-        return unless @socket && @socket.connected?
-
-        @channels.each_value do |channel|
-          next unless channel.joined?
-
-          msg = Message.new(
-            event:   Types::ChannelEvents::ACCESS_TOKEN,
-            topic:   channel.topic,
-            payload: { "access_token" => token },
-            ref:     next_ref
-          )
-          @socket.send(JSON.generate(
-            "event"    => msg.event,
-            "topic"    => msg.topic,
-            "payload"  => msg.payload,
-            "ref"      => msg.ref,
-            "join_ref" => nil
-          ))
+
+        if connected?
+          @channels.each do |channel|
+            next unless channel.joined?
+
+            msg = Message.new(
+              event:   Types::ChannelEvents::ACCESS_TOKEN,
+              topic:   channel.topic,
+              payload: { "access_token" => token },
+              ref:     next_ref
+            )
+            @socket.send(JSON.generate(
+              "event"    => msg.event,
+              "topic"    => msg.topic,
+              "payload"  => msg.payload,
+              "ref"      => msg.ref,
+              "join_ref" => nil
+            ))
+          end
         end
       end
 
@@ -198,6 +251,16 @@ module Supabase
 
       private
 
+      # Lazy-construct the production WebSocket transport. Lives behind an autoload
+      # so that callers who inject their own `transport:` don't pay the cost of
+      # `require "websocket-client-simple"`, and so that the dependency only loads
+      # once it's actually needed (matches the per-adapter require pattern in
+      # lib/supabase/realtime/sockets/*).
+      def build_default_transport
+        require_relative "sockets/websocket_client_simple"
+        Sockets::WebsocketClientSimple.new(url: @url)
+      end
+
       def attach_socket
         @socket.on_message { |raw| handle_inbound(raw) }
         @socket.on_open    { handle_socket_open }
@@ -270,7 +333,9 @@ module Supabase
 
         @reconnect_thread = Thread.new do
           Thread.current.report_on_exception = false
-          retries = 0
+          retries    = 0
+          last_error = nil
+          reconnected = false
           while retries < max_tries
             retries += 1
             wait = [initial * (2**(retries - 1)), 60.0].min
@@ -279,12 +344,27 @@ module Supabase
 
             begin
               @socket.connect
+              reconnected = true
               break # on_open will fire and restart heartbeat + rejoin channels
-            rescue StandardError
+            rescue StandardError => e
+              last_error = e
               # Try again until max_retries is hit.
             end
           end
           @reconnect_thread = nil
+          fire_reconnect_failed(last_error) unless reconnected || @intentionally_closed
+        end
+      end
+
+      # Fan-out the on_reconnect_failed callback. Wrapped in CallbackSafety so
+      # an exception inside a user block does not propagate up the background
+      # reconnect thread (which has `report_on_exception = false`) and get
+      # swallowed silently.
+      def fire_reconnect_failed(last_error)
+        return if @reconnect_failed_callbacks.empty?
+
+        @reconnect_failed_callbacks.each do |cb|
+          CallbackSafety.safe(@logger, "reconnect_failed") { cb.call(last_error) }
         end
       end
 
@@ -295,9 +375,13 @@ module Supabase
       end
 
       def rejoin_channels
-        @channels.each_value do |channel|
-          next unless channel.instance_variable_get(:@joined_once)
-          next if channel.joining?
+        @channels.each do |channel|
+          # Only rejoin channels the caller still cares about: JOINED (live
+          # subscription that the socket close interrupted) or JOINING (join
+          # handshake was in flight when the socket dropped). After
+          # `unsubscribe` a channel is LEAVING or CLOSED — rejoining it would
+          # silently revive a subscription the caller explicitly tore down.
+          next unless channel.joined? || channel.joining?
 
           channel.rejoin
         end
@@ -305,9 +389,11 @@ module Supabase
 
       def handle_inbound(raw)
         message = Message.parse(raw)
-        return if message.topic.nil?
+        # `parse` returns nil on malformed JSON (US-017) — skip the frame so the
+        # socket adapter's read-loop keeps running for the next valid frame.
+        return if message.nil? || message.topic.nil?
 
-        @channels.each_value do |channel|
+        @channels.each do |channel|
           channel.dispatch(message) if channel.topic == message.topic
         end
       end

data/lib/supabase/realtime/errors.rb

@@ -9,21 +9,8 @@ module Supabase
       # instance — the Phoenix protocol only allows one join per channel.
       class AlreadyJoinedError < RealtimeError; end
 
-      # Raised when a push waits longer than its timeout for a reply.
-      class PushTimeoutError < RealtimeError; end
-
       # Raised when a non-JSON or malformed frame arrives on the WebSocket.
       class ProtocolError < RealtimeError; end
-
-      # Raised when an operation requires an active WebSocket connection but
-      # the client hasn't connected (or has been closed). Mirrors py
-      # NotConnectedError so call sites can rescue the same class name.
-      class NotConnectedError < RealtimeError; end
-
-      # Raised when the server rejects a join push for authentication reasons
-      # (typical case: missing/invalid apikey or access_token). Mirrors py
-      # AuthorizationError.
-      class AuthorizationError < RealtimeError; end
     end
   end
 end

data/lib/supabase/realtime/message.rb

@@ -19,8 +19,12 @@ module Supabase
         )
       end
 
-      # Parse a raw JSON frame received on the WebSocket into a Message. Raises
-      # ProtocolError if the frame isn't well-formed JSON.
+      # Parse a raw JSON frame received on the WebSocket into a Message. Returns
+      # nil (and logs a warning) when the frame isn't well-formed JSON — the
+      # caller (read-loop in {Client#handle_inbound}) treats nil as "skip this
+      # frame" so a single garbled byte sequence can't kill the loop. Closes
+      # US-017 / F-C-minor: previously raised ProtocolError and propagated up
+      # into the socket adapter, taking down the read thread on first bad frame.
       def self.parse(raw)
         json = JSON.parse(raw)
         new(
@@ -31,7 +35,13 @@ module Supabase
           join_ref: json["join_ref"]
         )
       rescue JSON::ParserError => e
-        raise Errors::ProtocolError, "Malformed Phoenix frame: #{e.message}"
+        msg = "[Supabase::Realtime] Skipping malformed Phoenix frame: #{e.message}"
+        if defined?(@logger) && @logger.respond_to?(:warn)
+          @logger.warn(msg)
+        else
+          warn(msg)
+        end
+        nil
       end
     end
   end