supabase-rb 2.0.0

data/lib/supabase/postgrest/types.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Postgrest
+    module Types
+      module CountMethod
+        EXACT = "exact"
+        PLANNED = "planned"
+        ESTIMATED = "estimated"
+        ALL = [EXACT, PLANNED, ESTIMATED].freeze
+      end
+
+      module ReturnMethod
+        MINIMAL = "minimal"
+        REPRESENTATION = "representation"
+      end
+
+      module RequestMethod
+        GET = "GET"
+        POST = "POST"
+        PATCH = "PATCH"
+        PUT = "PUT"
+        DELETE = "DELETE"
+        HEAD = "HEAD"
+      end
+
+      # PostgREST filter operators. Names mirror supabase-py's Filters enum 1:1
+      # — see postgrest-py/src/postgrest/types.py.
+      module Filters
+        NOT = "not"
+        EQ = "eq"
+        NEQ = "neq"
+        GT = "gt"
+        GTE = "gte"
+        LT = "lt"
+        LTE = "lte"
+        IS = "is"
+        LIKE = "like"
+        LIKE_ALL = "like(all)"
+        LIKE_ANY = "like(any)"
+        ILIKE = "ilike"
+        ILIKE_ALL = "ilike(all)"
+        ILIKE_ANY = "ilike(any)"
+        FTS = "fts"
+        PLFTS = "plfts"
+        PHFTS = "phfts"
+        WFTS = "wfts"
+        IN = "in"
+        CS = "cs"
+        CD = "cd"
+        OV = "ov"
+        SL = "sl"
+        SR = "sr"
+        NXL = "nxl"
+        NXR = "nxr"
+        ADJ = "adj"
+      end
+    end
+  end
+end

data/lib/supabase/postgrest/utils.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Postgrest
+    module Utils
+      module_function
+
+      RESERVED_CHARS = ",:()"
+
+      # Quote values that contain PostgREST reserved characters so they aren't
+      # interpreted as operator separators. Mirrors supabase-py's sanitize_param.
+      def sanitize_param(param)
+        s = param.to_s
+        return %("#{s}") if s.chars.any? { |c| RESERVED_CHARS.include?(c) }
+
+        s
+      end
+
+      def sanitize_pattern_param(pattern)
+        sanitize_param(pattern.to_s.gsub("%", "*"))
+      end
+    end
+  end
+end

data/lib/supabase/postgrest/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Postgrest
+    VERSION = "0.1.0"
+  end
+end

data/lib/supabase/postgrest.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "postgrest/version"
+require_relative "postgrest/types"
+require_relative "postgrest/errors"
+require_relative "postgrest/utils"
+require_relative "postgrest/request_builder"
+require_relative "postgrest/client"
+
+module Supabase
+  module Postgrest
+  end
+end

data/lib/supabase/realtime/README.md

@@ -0,0 +1,90 @@
+# `supabase-realtime`
+
+Ruby client for [Supabase Realtime](https://supabase.com/docs/guides/realtime).
+Implements the [Phoenix Channels](https://hexdocs.pm/phoenix/channels.html)
+protocol against a **pluggable Socket interface**. Broadcast, Presence, and
+Postgres Change Data Capture (CDC) — same surface as
+[`realtime`](https://github.com/supabase/supabase-py/tree/main/src/realtime)
+in Python.
+
+- Source: [github.com/supabase-rb/client](https://github.com/supabase-rb/client)
+
+## Installation
+
+```ruby
+gem "supabase-realtime"
+```
+
+Then `bundle install`. (Requires Ruby >= 3.0.)
+
+## Design
+
+The protocol layer (channel state machine, presence sync, listener routing,
+push/reply tracking) is fully implemented and tested. A real WebSocket
+transport plugs in through the `Supabase::Realtime::Socket` interface; the
+gem ships one production adapter built on `websocket-client-simple`.
+
+This mirrors `supabase-py`'s decision to ship sync realtime as
+`NotImplementedError`: WebSocket I/O is fundamentally event-driven and a
+naive sync wrapper is more harmful than no wrapper at all. The
+websocket-client-simple adapter runs the read loop on a background thread,
+which means listener callbacks fire on that thread — bring your own
+thread-safety to anything they touch.
+
+## Usage
+
+```ruby
+require "supabase/realtime"
+require "supabase/realtime/sockets/websocket_client_simple"
+
+socket = Supabase::Realtime::Sockets::WebsocketClientSimple.new(
+  url: "wss://your-project.supabase.co/realtime/v1/websocket?apikey=#{key}"
+)
+client = Supabase::Realtime::Client.new(
+  url:    "wss://your-project.supabase.co/realtime/v1",
+  params: { apikey: key, access_token: jwt },
+  socket: socket
+)
+client.connect
+
+channel = client.channel("realtime:public:users")
+channel.on_postgres_changes("INSERT", schema: "public", table: "users") { |p| puts p }
+channel.on_postgres_changes("*", schema: "public", table: "users") { |p| puts p }
+channel.on_broadcast("message") { |p| puts p }
+channel.subscribe do |status, err|
+  puts status   # "SUBSCRIBED" / "CHANNEL_ERROR" / "TIMED_OUT"
+end
+
+channel.send_broadcast("typing", { user: "u1" })
+channel.track({ status: "online" })
+
+# Presence
+channel.presence.on_sync  { puts channel.presence.state }
+channel.presence.on_join  { |key, presence| ... }
+channel.presence.on_leave { |key, presence| ... }
+```
+
+## Testing
+
+For unit testing, use `Supabase::Realtime::TestSocket` — an in-memory Socket
+implementation with `inject(frame)` and `sent_frames` capture. See
+[`spec/supabase/realtime/`](../../../spec/supabase/realtime/) in the repo
+for usage.
+
+## Implementing your own Socket adapter
+
+Implement these methods (the only contract `Client` assumes):
+
+```ruby
+class MyAdapter
+  include Supabase::Realtime::Socket
+
+  def connect; ...; open_callbacks.each(&:call); end
+  def close;   ...; close_callbacks.each(&:call); end
+  def send(payload); ...; end
+  def connected?; ...; end
+
+  # Whenever a frame arrives:
+  #   message_callbacks.each { |cb| cb.call(raw_json_string) }
+end
+```

data/lib/supabase/realtime/channel.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "message"
+require_relative "presence"
+require_relative "push"
+require_relative "types"
+
+module Supabase
+  module Realtime
+    # A topic subscription on a shared Socket connection. Each Channel:
+    # - tracks its own lifecycle state (closed/joining/joined/leaving/errored)
+    # - holds the listener callbacks for postgres changes / broadcast / presence / system
+    # - dispatches inbound messages from the Client to those callbacks
+    # - owns its Presence sync state
+    #
+    # Should be constructed via {Client#channel}, not directly.
+    class Channel
+      attr_reader :topic, :params, :state, :join_push, :presence, :pending_pushes
+
+      def initialize(topic, params: nil, socket: nil)
+        @topic   = topic
+        @params  = params || default_params
+        @socket  = socket
+        @state   = Types::ChannelStates::CLOSED
+        @joined_once = false
+        @presence = Presence.new
+
+        @broadcast_callbacks        = []   # [{ event:, callback: }]
+        @postgres_changes_callbacks = []   # [{ event:, schema:, table:, filter:, callback: }]
+        @system_callbacks           = []
+        @close_callbacks            = []
+        @error_callbacks            = []
+
+        @pending_pushes = {} # ref => Push, for matching phx_reply
+        @push_buffer    = [] # outbound pushes queued while not yet joined
+
+        @join_push = Push.new(self, Types::ChannelEvents::JOIN, @params)
+        @subscribe_callback = nil
+
+        @join_push
+          .receive(Types::AckStatus::OK)      { |_| on_join_ok }
+          .receive(Types::AckStatus::ERROR)   { |p| on_join_error(p) }
+          .receive(Types::AckStatus::TIMEOUT) { |_| on_join_timeout }
+      end
+
+      # ----- State predicates -----
+
+      def closed?;  @state == Types::ChannelStates::CLOSED;  end
+      def errored?; @state == Types::ChannelStates::ERRORED; end
+      def joined?;  @state == Types::ChannelStates::JOINED;  end
+      def joining?; @state == Types::ChannelStates::JOINING; end
+      def leaving?; @state == Types::ChannelStates::LEAVING; end
+
+      # ----- Subscription -----
+
+      # Start the join handshake. Optional block fires when the join completes,
+      # receiving the SubscribeStates value (SUBSCRIBED / CHANNEL_ERROR / TIMED_OUT).
+      def subscribe(&block)
+        raise Errors::AlreadyJoinedError, "subscribe can only be called once per channel" if @joined_once
+
+        @joined_once = true
+        @subscribe_callback = block
+        @state = Types::ChannelStates::JOINING
+
+        @join_push.instance_variable_set(:@ref, @socket&.next_ref)
+        send_push(@join_push, register_pending: true)
+        self
+      end
+
+      # Tear down the subscription with a phx_leave push.
+      def unsubscribe
+        @state = Types::ChannelStates::LEAVING
+        ref = @socket&.next_ref
+        leave_push = Push.new(self, Types::ChannelEvents::LEAVE, {}, ref: ref)
+        send_push(leave_push, register_pending: false)
+        @state = Types::ChannelStates::CLOSED
+        self
+      end
+
+      # ----- Listener registration -----
+
+      # Register a postgres-changes listener. event may be "INSERT", "UPDATE",
+      # "DELETE", or "*" for all three. schema/table/filter narrow which rows
+      # fire the callback. Returns self so calls chain.
+      def on_postgres_changes(event, schema: nil, table: nil, filter: nil, &block)
+        unless %w[INSERT UPDATE DELETE *].include?(event)
+          raise ArgumentError, "postgres_changes event must be INSERT/UPDATE/DELETE/*"
+        end
+
+        @postgres_changes_callbacks << {
+          event: event, schema: schema, table: table, filter: filter, callback: block
+        }
+        self
+      end
+
+      def on_broadcast(event, &block)
+        @broadcast_callbacks << { event: event, callback: block }
+        self
+      end
+
+      def on_system(&block)
+        @system_callbacks << block
+        self
+      end
+
+      def on_close(&block)
+        @close_callbacks << block
+        self
+      end
+
+      def on_error(&block)
+        @error_callbacks << block
+        self
+      end
+
+      # ----- Outbound -----
+
+      # Send a custom broadcast message. The server will forward it to other
+      # subscribers of the same topic.
+      def send_broadcast(event, payload = {})
+        push = Push.new(self,
+                        Types::ChannelEvents::BROADCAST,
+                        { "type" => "broadcast", "event" => event, "payload" => payload })
+        send_push(push, register_pending: false)
+        self
+      end
+
+      # Track the local user in the channel's presence state.
+      def track(payload)
+        push = Push.new(self,
+                        Types::ChannelEvents::PRESENCE,
+                        { "type" => "presence", "event" => "track", "payload" => payload })
+        send_push(push, register_pending: false)
+        self
+      end
+
+      def untrack
+        push = Push.new(self,
+                        Types::ChannelEvents::PRESENCE,
+                        { "type" => "presence", "event" => "untrack" })
+        send_push(push, register_pending: false)
+        self
+      end
+
+      # ----- Inbound dispatch (called by Client) -----
+
+      # Route a parsed Message to the appropriate listeners. Returns true if the
+      # message belonged to this channel, false otherwise (so the Client knows
+      # whether to drop it).
+      def dispatch(message)
+        return false unless message.topic == @topic
+
+        case message.event
+        when Types::ChannelEvents::REPLY
+          dispatch_reply(message)
+        when Types::ChannelEvents::POSTGRES_CHANGES
+          dispatch_postgres_changes(message)
+        when Types::ChannelEvents::BROADCAST
+          dispatch_broadcast(message)
+        when Types::ChannelEvents::PRESENCE_STATE
+          @presence.sync_state(message.payload)
+        when Types::ChannelEvents::PRESENCE_DIFF
+          @presence.sync_diff(message.payload)
+        when Types::ChannelEvents::SYSTEM
+          @system_callbacks.each { |cb| cb.call(message.payload) }
+        when Types::ChannelEvents::CLOSE
+          @state = Types::ChannelStates::CLOSED
+          @close_callbacks.each { |cb| cb.call(message.payload) }
+        when Types::ChannelEvents::ERROR
+          @state = Types::ChannelStates::ERRORED
+          @error_callbacks.each { |cb| cb.call(message.payload) }
+        end
+
+        true
+      end
+
+      private
+
+      def default_params
+        {
+          "config" => {
+            "broadcast" => { "ack" => false, "self" => false },
+            "presence"  => { "key" => "", "enabled" => false },
+            "private"   => false
+          }
+        }
+      end
+
+      def send_push(push, register_pending:)
+        message = Message.new(
+          event:    push.event,
+          topic:    @topic,
+          payload:  push.payload,
+          ref:      push.ref,
+          join_ref: @join_push.ref
+        )
+
+        if can_send?
+          @pending_pushes[push.ref] = push if register_pending && push.ref
+          @socket&.push(message)
+        else
+          @push_buffer << [push, register_pending]
+        end
+      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)
+      end
+
+      def dispatch_reply(message)
+        ref = message.ref
+        push = @pending_pushes.delete(ref)
+        return unless push
+
+        push.resolve(
+          status:  message.payload["status"],
+          payload: message.payload["response"] || message.payload
+        )
+      end
+
+      def dispatch_postgres_changes(message)
+        # Payload shape: { "data" => { "type" => "INSERT", "schema" => "public", "table" => "users", ... }, "ids" => [...] }
+        data = message.payload["data"] || {}
+        change_type = data["type"]
+        schema      = data["schema"]
+        table       = data["table"]
+
+        @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)
+        end
+      end
+
+      def dispatch_broadcast(message)
+        event = message.payload["event"]
+        @broadcast_callbacks.each do |binding|
+          binding[:callback].call(message.payload) if binding[:event] == event
+        end
+      end
+
+      def on_join_ok
+        @state = Types::ChannelStates::JOINED
+        flush_push_buffer
+        @subscribe_callback&.call(Types::SubscribeStates::SUBSCRIBED, nil)
+      end
+
+      def on_join_error(payload)
+        @state = Types::ChannelStates::ERRORED
+        @subscribe_callback&.call(Types::SubscribeStates::CHANNEL_ERROR, payload)
+      end
+
+      def on_join_timeout
+        @state = Types::ChannelStates::ERRORED
+        @subscribe_callback&.call(Types::SubscribeStates::TIMED_OUT, nil)
+      end
+
+      def flush_push_buffer
+        buffered = @push_buffer
+        @push_buffer = []
+        buffered.each { |push, register_pending| send_push(push, register_pending: register_pending) }
+      end
+    end
+  end
+end

data/lib/supabase/realtime/client.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+require_relative "channel"
+require_relative "message"
+require_relative "types"
+require_relative "version"
+
+module Supabase
+  module Realtime
+    # Top-level Realtime client. Owns one {Socket}, multiplexes Channels onto it,
+    # 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}.
+    #
+    #   socket   = Supabase::Realtime::TestSocket.new
+    #   client   = Supabase::Realtime::Client.new(
+    #     url: "wss://project.supabase.co/realtime/v1",
+    #     params: { apikey: key },
+    #     socket: socket
+    #   )
+    #   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
+
+      # @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 timeout [Numeric] default per-push timeout (seconds)
+      def initialize(url:, params: {}, socket: nil, timeout: Types::DEFAULT_TIMEOUT_SECONDS)
+        @url     = normalize_url(url, params)
+        @params  = params
+        @access_token = params[:access_token] || params["access_token"]
+        @channels = {}
+        @socket   = socket
+        @timeout  = timeout
+        @ref      = 0
+
+        attach_socket if @socket
+      end
+
+      # Plug in a transport after construction (e.g. a websocket-client-simple wrapper).
+      def use_socket(socket)
+        @socket = socket
+        attach_socket
+        self
+      end
+
+      def connect
+        raise Errors::RealtimeError, "no socket attached — call #use_socket(socket) first" unless @socket
+
+        @socket.connect
+        self
+      end
+
+      def disconnect
+        @socket&.close
+        @channels.each_value { |ch| ch.instance_variable_set(:@state, Types::ChannelStates::CLOSED) }
+        self
+      end
+
+      def connected?
+        @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.
+      def channel(topic, params: nil)
+        @channels[topic] ||= Channel.new(topic, params: params, socket: self)
+      end
+
+      def get_channels
+        @channels.values
+      end
+
+      def remove_channel(channel)
+        channel.unsubscribe
+        @channels.delete(channel.topic)
+      end
+
+      def remove_all_channels
+        @channels.values.each { |ch| ch.unsubscribe }
+        @channels.clear
+      end
+
+      # Update the access token, send it to every joined channel so RLS reflects
+      # the new auth context, and remember it for future joins.
+      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
+          ))
+        end
+      end
+
+      # Manually emit a heartbeat. Real adapters typically wire this onto a timer.
+      def send_heartbeat
+        return unless connected?
+
+        @socket.send(JSON.generate(
+          "event"    => Types::ChannelEvents::HEARTBEAT,
+          "topic"    => Types::PHOENIX_TOPIC,
+          "payload"  => {},
+          "ref"      => next_ref,
+          "join_ref" => nil
+        ))
+      end
+
+      # Used by Channel — increments a shared counter so refs are unique per socket.
+      def next_ref
+        @ref += 1
+        @ref.to_s
+      end
+
+      # Used by Channel#send_push.
+      def push(message)
+        return unless @socket
+
+        @socket.send(JSON.generate(
+          "event"    => message.event,
+          "topic"    => message.topic,
+          "payload"  => message.payload,
+          "ref"      => message.ref,
+          "join_ref" => message.join_ref
+        ))
+      end
+
+      private
+
+      def attach_socket
+        @socket.on_message do |raw|
+          handle_inbound(raw)
+        end
+      end
+
+      def handle_inbound(raw)
+        message = Message.parse(raw)
+        return if message.topic.nil?
+
+        @channels.each_value do |channel|
+          channel.dispatch(message) if channel.topic == message.topic
+        end
+      end
+
+      def normalize_url(url, params)
+        normalized = url.to_s.dup
+        normalized.sub!(%r{\Ahttp://},  "ws://")
+        normalized.sub!(%r{\Ahttps://}, "wss://")
+        normalized = "#{normalized}/websocket" unless normalized.end_with?("/websocket")
+
+        query = { "vsn" => Types::VSN }.merge(params.transform_keys(&:to_s)) if params && !params.empty?
+        query ||= { "vsn" => Types::VSN }
+
+        separator = normalized.include?("?") ? "&" : "?"
+        "#{normalized}#{separator}#{URI.encode_www_form(query)}"
+      end
+    end
+  end
+end

data/lib/supabase/realtime/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    module Errors
+      class RealtimeError < StandardError; end
+
+      # Raised when subscribe() is called more than once on the same Channel
+      # 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
+    end
+  end
+end