supabase-rb 2.0.0

data/lib/supabase/realtime/message.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+
+module Supabase
+  module Realtime
+    # A Phoenix Channel frame: { event, topic, payload, ref, join_ref }.
+    # Used both for outbound pushes and parsed inbound messages.
+    Message = Struct.new(:event, :topic, :payload, :ref, :join_ref, keyword_init: true) do
+      def to_json(*)
+        JSON.generate(
+          "event"    => event,
+          "topic"    => topic,
+          "payload"  => payload,
+          "ref"      => ref,
+          "join_ref" => join_ref
+        )
+      end
+
+      # Parse a raw JSON frame received on the WebSocket into a Message. Raises
+      # ProtocolError if the frame isn't well-formed JSON.
+      def self.parse(raw)
+        json = JSON.parse(raw)
+        new(
+          event:    json["event"],
+          topic:    json["topic"],
+          payload:  json["payload"] || {},
+          ref:      json["ref"],
+          join_ref: json["join_ref"]
+        )
+      rescue JSON::ParserError => e
+        raise Errors::ProtocolError, "Malformed Phoenix frame: #{e.message}"
+      end
+    end
+  end
+end

data/lib/supabase/realtime/presence.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    # Tracks presence state for one channel and implements the Phoenix Presence
+    # sync algorithm: presence_state replaces the local snapshot, presence_diff
+    # applies joins/leaves on top of it.
+    #
+    # The algorithm mirrors phoenix.js's Presence.syncState / Presence.syncDiff so
+    # callers porting from JS/Python see identical behavior.
+    class Presence
+      attr_reader :state
+
+      def initialize
+        @state = {}
+        @on_sync_callbacks = []
+        @on_join_callbacks = []
+        @on_leave_callbacks = []
+      end
+
+      # The first presence_state message after joining sends the full state. Any
+      # local metas we already have for a key but the server doesn't are emitted
+      # as leaves; anything new is emitted as a join.
+      def sync_state(new_state)
+        joins  = {}
+        leaves = {}
+
+        @state.each do |key, presence|
+          leaves[key] = presence unless new_state.key?(key)
+        end
+
+        new_state.each do |key, new_presence|
+          current = @state[key]
+          if current
+            joined = []
+            left   = []
+            current_refs = metas(current).map { |m| m["phx_ref"] }
+            new_refs     = metas(new_presence).map { |m| m["phx_ref"] }
+            joined = metas(new_presence).reject { |m| current_refs.include?(m["phx_ref"]) }
+            left   = metas(current).reject     { |m| new_refs.include?(m["phx_ref"]) }
+            joins[key]  = { "metas" => joined } unless joined.empty?
+            leaves[key] = { "metas" => left }   unless left.empty?
+          else
+            joins[key] = new_presence
+          end
+        end
+
+        @state = deep_copy(new_state)
+        emit_joins(joins)
+        emit_leaves(leaves)
+        @on_sync_callbacks.each(&:call)
+        @state
+      end
+
+      # Subsequent presence_diff messages carry only joins/leaves to apply.
+      def sync_diff(diff)
+        joins  = diff["joins"]  || {}
+        leaves = diff["leaves"] || {}
+
+        joins.each do |key, presence|
+          if @state[key]
+            existing_refs = metas(@state[key]).map { |m| m["phx_ref"] }
+            new_metas     = metas(presence).reject { |m| existing_refs.include?(m["phx_ref"]) }
+            @state[key]   = { "metas" => metas(@state[key]) + new_metas }
+          else
+            @state[key] = presence
+          end
+        end
+
+        leaves.each do |key, presence|
+          next unless @state[key]
+
+          leaving_refs   = metas(presence).map { |m| m["phx_ref"] }
+          remaining      = metas(@state[key]).reject { |m| leaving_refs.include?(m["phx_ref"]) }
+          if remaining.empty?
+            @state.delete(key)
+          else
+            @state[key] = { "metas" => remaining }
+          end
+        end
+
+        emit_joins(joins)
+        emit_leaves(leaves)
+        @on_sync_callbacks.each(&:call)
+        @state
+      end
+
+      # List every meta currently tracked, flat. Useful when callers don't care
+      # about the per-key grouping.
+      def list
+        @state.values.flat_map { |presence| metas(presence) }
+      end
+
+      def on_sync(&block)
+        @on_sync_callbacks << block
+        self
+      end
+
+      def on_join(&block)
+        @on_join_callbacks << block
+        self
+      end
+
+      def on_leave(&block)
+        @on_leave_callbacks << block
+        self
+      end
+
+      def any_callbacks?
+        [@on_sync_callbacks, @on_join_callbacks, @on_leave_callbacks].any? { |list| !list.empty? }
+      end
+
+      private
+
+      def metas(presence)
+        Array(presence && presence["metas"])
+      end
+
+      def emit_joins(joins)
+        joins.each do |key, presence|
+          @on_join_callbacks.each { |cb| cb.call(key, presence) }
+        end
+      end
+
+      def emit_leaves(leaves)
+        leaves.each do |key, presence|
+          @on_leave_callbacks.each { |cb| cb.call(key, presence) }
+        end
+      end
+
+      def deep_copy(obj)
+        Marshal.load(Marshal.dump(obj))
+      end
+    end
+  end
+end

data/lib/supabase/realtime/push.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "types"
+
+module Supabase
+  module Realtime
+    # One outbound Phoenix push, awaiting a reply. The channel matches incoming
+    # phx_reply messages to pushes by `ref` and fires the appropriate handler.
+    #
+    # `receive(:ok / :error / :timeout) { |payload| ... }` registers handlers
+    # before the push is sent, mirroring phoenix.js's Push API.
+    class Push
+      attr_reader :ref, :event, :payload, :received_status
+
+      def initialize(channel, event, payload = {}, ref: nil)
+        @channel  = channel
+        @event    = event
+        @payload  = payload
+        @ref      = ref
+        @handlers = Hash.new { |h, k| h[k] = [] }
+        @received_status = nil
+        @received_payload = nil
+      end
+
+      def receive(status, &block)
+        if @received_status == status
+          # Reply already arrived before this handler was attached — fire immediately.
+          block.call(@received_payload)
+        else
+          @handlers[status] << block
+        end
+        self
+      end
+
+      # Called by the Channel when a phx_reply with matching ref arrives.
+      def resolve(status:, payload:)
+        @received_status  = status
+        @received_payload = payload
+        @handlers[status].each { |h| h.call(payload) }
+      end
+
+      # Called by the Channel if no reply arrives within the timeout window.
+      def time_out
+        resolve(status: Types::AckStatus::TIMEOUT, payload: {})
+      end
+    end
+  end
+end

data/lib/supabase/realtime/socket.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    # Transport interface that {Client} talks to. A real implementation wraps a
+    # WebSocket; {TestSocket} stays in-memory for specs.
+    #
+    # Implementations must provide:
+    #
+    #   - `connect`           — open the underlying transport
+    #   - `close`             — tear it down
+    #   - `send(payload)`     — push one raw JSON frame to the server
+    #   - `connected?`        — boolean state predicate
+    #   - `on_message(&blk)`  — register an inbound-frame callback (raw JSON string)
+    #   - `on_open(&blk)`     — register an on-open callback
+    #   - `on_close(&blk)`    — register an on-close callback
+    #
+    # The Client never assumes a specific WebSocket library; bring your own
+    # (websocket-client-simple for sync, async-websocket for async, etc.) by
+    # implementing this interface.
+    module Socket
+      # The minimum surface. Including it gives default no-op implementations so
+      # subclasses can override piecemeal.
+      def connect; raise NotImplementedError; end
+      def close;   raise NotImplementedError; end
+      def send(_payload); raise NotImplementedError; end
+      def connected?; raise NotImplementedError; end
+
+      def on_message(&blk); message_callbacks << blk; end
+      def on_open(&blk);    open_callbacks    << blk; end
+      def on_close(&blk);   close_callbacks   << blk; end
+      def on_error(&blk);   error_callbacks   << blk; end
+
+      def message_callbacks; @message_callbacks ||= []; end
+      def open_callbacks;    @open_callbacks    ||= []; end
+      def close_callbacks;   @close_callbacks   ||= []; end
+      def error_callbacks;   @error_callbacks   ||= []; end
+    end
+  end
+end

data/lib/supabase/realtime/sockets/async_websocket.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/endpoint"
+require "async/websocket/client"
+require "protocol/websocket/message"
+
+require_relative "../errors"
+require_relative "../socket"
+
+module Supabase
+  module Realtime
+    module Sockets
+      # {Socket} implementation backed by the async-websocket gem (socketry/async).
+      #
+      # Unlike {WebsocketClientSimple} — which spawns a background OS thread for
+      # the read loop — this adapter runs entirely inside the calling fiber's
+      # Async reactor. Pick it when:
+      #
+      #   - your app already runs on the socketry/async stack (Falcon, or
+      #     supabase-rb's own async REST clients via async-http-faraday), so
+      #     a single reactor owns all I/O;
+      #   - you want cooperative concurrency without cross-thread callback
+      #     hops or mutexes on listener state.
+      #
+      #   require "async"
+      #   require "supabase/realtime"
+      #   require "supabase/realtime/sockets/async_websocket"
+      #
+      #   Async do
+      #     socket  = Supabase::Realtime::Sockets::AsyncWebsocket.new(url: ws_url)
+      #     client  = Supabase::Realtime::Client.new(url: ws_url, socket: socket)
+      #     client.connect
+      #
+      #     channel = client.channel("realtime:public:users")
+      #     channel.on_postgres_changes("INSERT", schema: "public", table: "users") { |p| puts p }
+      #     channel.subscribe
+      #   end
+      #
+      # All callbacks (on_open / on_message / on_close / on_error, and every
+      # downstream channel listener) run inside the Async reactor on the same
+      # fiber tree as the caller — no thread hops, no mutexes required for
+      # state owned by the reactor.
+      class AsyncWebsocket
+        include Socket
+
+        # @param url       [String]   ws(s):// URL including query params
+        # @param headers   [Hash]     extra HTTP headers sent on the upgrade request
+        # @param parent    [Async::Task, nil] reactor task to attach the session
+        #   to. Defaults to {Async::Task.current?} resolved at connect-time, so
+        #   callers must be inside an `Async { ... }` block.
+        # @param connector [#connect] dependency-injection seam — defaults to
+        #   {Async::WebSocket::Client}. Tests pass a fake that returns a stub
+        #   connection so no real socket is opened.
+        def initialize(url:, headers: {}, parent: nil, connector: ::Async::WebSocket::Client)
+          @url        = url
+          @headers    = headers
+          @parent     = parent
+          @connector  = connector
+          @connection = nil
+          @session    = nil
+        end
+
+        def connect
+          return if connected?
+
+          parent = @parent || ::Async::Task.current?
+          unless parent
+            raise Errors::RealtimeError,
+                  "Supabase::Realtime::Sockets::AsyncWebsocket#connect must run inside an Async { ... } block " \
+                  "(or be constructed with parent:)"
+          end
+
+          endpoint = ::Async::HTTP::Endpoint.parse(@url)
+          ready    = ::Async::Promise.new
+
+          @session = parent.async do
+            @connector.connect(endpoint, headers: header_pairs) do |connection|
+              @connection = connection
+              fire_open
+              ready.resolve(true)
+
+              read_loop(connection)
+            end
+          rescue => err
+            fire_error(err)
+            ready.reject(err) unless ready.resolved?
+          ensure
+            fire_close
+          end
+
+          # Cooperative wait — Promise buffers the resolution, so this returns
+          # immediately whether the session task got there first or not. After
+          # this, callers can rely on connected?.
+          ready.wait
+          nil
+        end
+
+        def close
+          conn    = @connection
+          session = @session
+          @connection = nil
+          @session    = nil
+
+          # Closing the connection makes #read return nil → read_loop exits →
+          # the session task terminates naturally. This is more reliable than
+          # task.stop, which doesn't always interrupt a fiber blocked on a
+          # non-IO suspend point (queues, notifications).
+          begin
+            conn&.close
+          rescue StandardError
+            # Connection may already be torn down — ignore.
+          end
+
+          # Belt-and-braces: if the connection didn't unblock the read, stop
+          # the task as a fallback. No-op if it already finished.
+          session&.stop
+        end
+
+        def send(payload)
+          conn = @connection
+          return unless conn
+
+          # Connection#write auto-wraps UTF-8 strings in a text frame, which is
+          # what the Phoenix protocol expects.
+          conn.write(payload)
+          conn.flush
+        end
+
+        def connected?
+          !@connection.nil?
+        end
+
+        # ----- Internal callback fan-outs (public so the read task can reach them) -----
+
+        def fire_open
+          open_callbacks.each(&:call)
+        end
+
+        def fire_message(payload)
+          message_callbacks.each { |cb| cb.call(payload) }
+        end
+
+        def fire_close
+          return if @connection.nil? && close_callbacks.empty?
+
+          @connection = nil
+          close_callbacks.each(&:call)
+        end
+
+        def fire_error(err)
+          error_callbacks.each { |cb| cb.call(err) }
+        end
+
+        private
+
+        def header_pairs
+          @headers.map { |k, v| [k.to_s, v.to_s] }
+        end
+
+        def read_loop(connection)
+          while (message = connection.read)
+            next unless message.is_a?(::Protocol::WebSocket::TextMessage)
+
+            fire_message(message.buffer.to_s)
+          end
+        rescue ::Async::Stop
+          # graceful shutdown — initiated by #close
+        rescue => err
+          fire_error(err)
+        end
+      end
+    end
+  end
+end

data/lib/supabase/realtime/sockets/websocket_client_simple.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "websocket-client-simple"
+
+require_relative "../socket"
+
+module Supabase
+  module Realtime
+    module Sockets
+      # {Socket} implementation backed by the websocket-client-simple gem.
+      #
+      # The underlying gem spawns a background thread to read frames from the
+      # server, so every callback this adapter fires (on_open / on_message /
+      # on_close / on_error — and downstream, every user listener registered
+      # on a Channel) runs on **that background thread**. Callers are
+      # responsible for thread-safety in their listeners.
+      #
+      #   require "supabase/realtime"
+      #   require "supabase/realtime/sockets/websocket_client_simple"
+      #
+      #   socket = Supabase::Realtime::Sockets::WebsocketClientSimple.new(url: ws_url)
+      #   client = Supabase::Realtime::Client.new(url: ws_url, socket: socket)
+      #   client.connect
+      class WebsocketClientSimple
+        include Socket
+
+        # @param url     [String] full ws(s):// URL including query params
+        # @param headers [Hash]   extra HTTP headers sent on the upgrade request
+        # @param connector [#connect] dependency injection seam — defaults to
+        #   ::WebSocket::Client::Simple. Tests pass a fake that returns a stub
+        #   WS client so we never open a real socket.
+        def initialize(url:, headers: {}, connector: ::WebSocket::Client::Simple)
+          @url       = url
+          @headers   = headers
+          @connector = connector
+          @ws        = nil
+        end
+
+        def connect
+          return if connected?
+
+          self_ref = self
+          @ws = @connector.connect(@url, headers: @headers) do |client|
+            client.on(:open)    { self_ref.fire_open }
+            client.on(:message) { |msg| self_ref.fire_message(msg) }
+            client.on(:close)   { |reason| self_ref.fire_close(reason) }
+            client.on(:error)   { |err| self_ref.fire_error(err) }
+          end
+          nil
+        end
+
+        def close
+          @ws&.close
+          @ws = nil
+        end
+
+        def send(payload)
+          @ws&.send(payload)
+        end
+
+        def connected?
+          !@ws.nil? && @ws.open?
+        end
+
+        # ----- Internal callback shims (called by the WS background thread) -----
+        # Public so the connect block can reach them, not part of the Socket
+        # contract callers should use.
+
+        def fire_open
+          open_callbacks.each(&:call)
+        end
+
+        # websocket-client-simple yields a Frame::Incoming object whose #data
+        # holds the payload and whose #type is :text / :binary / :ping / etc.
+        # We only forward text frames — Phoenix doesn't use binary.
+        def fire_message(msg)
+          return unless msg.respond_to?(:type) ? msg.type == :text : true
+
+          payload = msg.respond_to?(:data) ? msg.data : msg.to_s
+          message_callbacks.each { |cb| cb.call(payload) }
+        end
+
+        def fire_close(_reason = nil)
+          @ws = nil
+          close_callbacks.each(&:call)
+        end
+
+        def fire_error(err)
+          error_callbacks.each { |cb| cb.call(err) }
+        end
+      end
+    end
+  end
+end

data/lib/supabase/realtime/test_socket.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "socket"
+
+module Supabase
+  module Realtime
+    # In-memory {Socket} implementation for specs and local prototyping. Captures
+    # every frame the client sends in `sent_frames`, and exposes `inject(frame)`
+    # so a test can simulate a server response.
+    #
+    # Not intended for production use — bring a real WebSocket adapter for that.
+    class TestSocket
+      include Socket
+
+      attr_reader :sent_frames
+
+      def initialize
+        @connected   = false
+        @sent_frames = []
+      end
+
+      def connect
+        @connected = true
+        open_callbacks.each(&:call)
+      end
+
+      def close
+        @connected = false
+        close_callbacks.each(&:call)
+      end
+
+      def send(payload)
+        @sent_frames << payload
+      end
+
+      def connected?
+        @connected
+      end
+
+      # ----- Test helpers -----
+
+      # Push a JSON frame as if it came from the server. Accepts a JSON String
+      # or a Hash (which gets JSON-encoded for you).
+      def inject(frame)
+        raw = frame.is_a?(String) ? frame : JSON.generate(frame)
+        message_callbacks.each { |cb| cb.call(raw) }
+      end
+
+      # Convenience: the last frame the client pushed, parsed back to a Hash.
+      def last_sent_frame
+        return nil if @sent_frames.empty?
+
+        JSON.parse(@sent_frames.last)
+      end
+
+      def sent_events
+        @sent_frames.map { |f| JSON.parse(f)["event"] }
+      end
+
+      def reset_sent_frames
+        @sent_frames = []
+      end
+    end
+  end
+end

data/lib/supabase/realtime/transformers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    # Mirrors realtime-py's `realtime.transformers`. Today this is a single
+    # helper used to derive the HTTP endpoint from the WebSocket URL so callers
+    # can hit the realtime REST surface (e.g. /api/broadcast, /connections).
+    module Transformers
+      module_function
+
+      # Converts a realtime socket URL into its HTTP equivalent.
+      #
+      #   http_endpoint_url("wss://x.supabase.co/realtime/v1/websocket")
+      #   # => "https://x.supabase.co/realtime/v1"
+      #
+      # Replaces the leading `ws`/`wss` scheme with `http`/`https`, strips any
+      # `/socket/websocket`, `/socket`, or `/websocket` suffix, and trims
+      # trailing slashes. Mirrors py's regex chain verbatim.
+      def http_endpoint_url(socket_url)
+        url = socket_url.to_s.sub(/\Aws/i, "http")
+        url = url.sub(%r{(/socket/websocket|/socket|/websocket)/?\z}i, "")
+        url.sub(%r{/+\z}, "")
+      end
+    end
+  end
+end

data/lib/supabase/realtime/types.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    module Types
+      # Phoenix protocol version this client speaks. Matches supabase-py.
+      VSN = "1.0.0"
+
+      DEFAULT_TIMEOUT_SECONDS = 10
+      DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 25
+
+      # The special topic the Phoenix server uses for heartbeats and connection-level
+      # control messages.
+      PHOENIX_TOPIC = "phoenix"
+
+      # Phoenix event names — mirror supabase-py's ChannelEvents enum 1:1 so docs
+      # and message dumps line up.
+      module ChannelEvents
+        CLOSE            = "phx_close"
+        ERROR            = "phx_error"
+        JOIN             = "phx_join"
+        REPLY            = "phx_reply"
+        LEAVE            = "phx_leave"
+        HEARTBEAT        = "heartbeat"
+        ACCESS_TOKEN     = "access_token"
+        BROADCAST        = "broadcast"
+        PRESENCE         = "presence"
+        PRESENCE_STATE   = "presence_state"
+        PRESENCE_DIFF    = "presence_diff"
+        SYSTEM           = "system"
+        POSTGRES_CHANGES = "postgres_changes"
+      end
+
+      # Channel lifecycle states.
+      module ChannelStates
+        CLOSED  = :closed
+        ERRORED = :errored
+        JOINED  = :joined
+        JOINING = :joining
+        LEAVING = :leaving
+        ALL = [CLOSED, ERRORED, JOINED, JOINING, LEAVING].freeze
+      end
+
+      # States passed to Channel#subscribe's callback so callers know whether the
+      # join succeeded.
+      module SubscribeStates
+        SUBSCRIBED    = "SUBSCRIBED"
+        TIMED_OUT     = "TIMED_OUT"
+        CLOSED        = "CLOSED"
+        CHANNEL_ERROR = "CHANNEL_ERROR"
+      end
+
+      # Server replies to a phx_join push with one of these statuses.
+      module AckStatus
+        OK      = "ok"
+        ERROR   = "error"
+        TIMEOUT = "timeout"
+      end
+
+      # Postgres-change event filters callers pass to Channel#on_postgres_changes.
+      # "*" subscribes to all three events.
+      module PostgresChangesEvent
+        ALL    = "*"
+        INSERT = "INSERT"
+        UPDATE = "UPDATE"
+        DELETE = "DELETE"
+      end
+    end
+  end
+end