supabase-rb 3.2.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6f3e676fb9f80387385b5339aff40fcdc8b584b9c8e66f92072f2ac9d7ba356
-  data.tar.gz: f9972703bfd0828183e1a600c5cad893c4102c728b913384919b41da9e4deb06
+  metadata.gz: '0168cd0cbeebbe6a2e1132d54ba1592b6a1f1f43d0c3f7d9374b52d16394f0a0'
+  data.tar.gz: 92b7a6b274189d5036f4975a7b1866510b6b09b6be0ea1d0360dd45d156d913b
 SHA512:
-  metadata.gz: 39871694f25f18c296f358f6f85325f18f31a1752e2bb79dc96c6ce0551f5d0c10a72c5994a5302761e6e4df170eadae058dc69fa04dac5764db2568198d1b1a
-  data.tar.gz: aa76e506b180682651570e8b8a3c1a091901655a5d95ac5d642b962dc33dfd09f2c77d131117eb70c42a1163c63cd341d8941d1db3064ce7504943e75e771f35
+  metadata.gz: b426ffddbbc4c9f86ee32453a4b58d478c7fc7643b418205662901cb759f7603161cb8e96f536aa947214a5dbb8e83408f164dd3add2354bdf204e68b2aae46d
+  data.tar.gz: 533f4f7a15bc5a1571f7554d3e7e54737f7aee788c07a6d81cad08f6ab2d4e39f7a6404fe2657cae679977ed9136d189a260b6936e893b564f55d808d5d03991

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Supabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/supabase/auth/api.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/follow_redirects"
 require "json"
 
 module Supabase
@@ -59,6 +60,15 @@ module Supabase
         result = no_resolve_json ? response : parse_response(response)
 
         xform ? xform.call(result) : result
+      rescue Errors::AuthError
+        # A domain error raised inside the request — typically by an `xform`
+        # (e.g. JWKS parsing raising AuthInvalidJwtError) or response parsing —
+        # is already the correct exception. Re-raise it unchanged. Without this
+        # clause the blanket `rescue StandardError` below funnels it through
+        # handle_exception, which masks every non-Faraday error as
+        # AuthRetryableError(status: 0) — so callers of get_claims would see a
+        # spurious "retryable" error instead of the real AuthInvalidJwtError.
+        raise
       rescue Faraday::Error => e
         raise Helpers.handle_exception(e)
       rescue StandardError => e
@@ -99,6 +109,10 @@ module Supabase
 
       def build_connection
         Faraday.new(url: @url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          # Follow 3xx (httpx `follow_redirects=True` in supabase-py) before
+          # raise_error inspects the status, so a redirect isn't turned into an
+          # error.
+          f.response :follow_redirects
           f.response :raise_error
           if @timeout
             f.options.timeout = @timeout

data/lib/supabase/auth/async/admin_api.rb

@@ -25,6 +25,7 @@ module Supabase
 
         def build_connection
           Faraday.new(url: @url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            f.response :follow_redirects
             f.response :raise_error
             if @timeout
               f.options.timeout = @timeout

data/lib/supabase/auth/async/api.rb

@@ -18,6 +18,7 @@ module Supabase
 
         def build_connection
           Faraday.new(url: @url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            f.response :follow_redirects
             f.response :raise_error
             if @timeout
               f.options.timeout = @timeout

data/lib/supabase/auth/client.rb

@@ -13,6 +13,7 @@ module Supabase
       STORAGE_KEY = "supabase.auth.token"
       EXPIRY_MARGIN = 10
       JWKS_TTL = 600 # 10 minutes
+
       # Explicit asymmetric algorithm-to-digest mapping (reference table).
       ALG_TO_DIGEST = {
         "RS256" => "SHA256", "RS384" => "SHA384", "RS512" => "SHA512",
@@ -712,12 +713,23 @@ module Supabase
         # same message py would raise.
         raise Errors::AuthInvalidJwtError, "Algorithm not supported" unless SUPPORTED_ALGORITHMS.include?(header["alg"])
 
-        # Asymmetric JWT - verify via JWKS using the jwt gem's decode
+        # Asymmetric JWT — signature verification ONLY, matching py exactly:
+        # py calls algorithm.verify() (gotrue_client.py:1272-1282) after the
+        # manual validate_exp above, so no claim validation (exp/nbf) happens
+        # here — the jwt gem's defaults are explicitly switched off.
         jwk_data = _fetch_jwks(header["kid"], jwks || { "keys" => [] })
         jwk_set = JWT::JWK::Set.new({ "keys" => [jwk_data] })
 
         begin
-          JWT.decode(token, nil, true, { algorithms: [header["alg"]], jwks: jwk_set })
+          JWT.decode(
+            token, nil, true,
+            {
+              algorithms: [header["alg"]],
+              jwks: jwk_set,
+              verify_expiration: false,
+              verify_not_before: false
+            }
+          )
         rescue JWT::DecodeError => e
           raise Errors::AuthInvalidJwtError, "Invalid JWT signature: #{e.message}"
         end

data/lib/supabase/auth/helpers.rb

@@ -90,6 +90,8 @@ module Supabase
         /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.match?(value)
       end
 
+      # Mirrors py `validate_exp` (helpers.py:286-292): no clock-skew leeway —
+      # a token is rejected the moment `exp <= now`.
       def validate_exp(exp)
         raise Errors::AuthInvalidJwtError, "JWT has no expiration time" if exp.nil? || exp == 0
 

data/lib/supabase/client.rb

@@ -41,8 +41,9 @@ module Supabase
       if options.is_a?(Supabase::ClientOptions)
         configured_auth = options.headers["Authorization"] || options.headers[:Authorization]
       elsif options.is_a?(Hash)
-        global_headers = options[:global]&.dig(:headers) || options.dig("global", "headers") || {}
-        configured_auth = global_headers["Authorization"] || global_headers[:Authorization]
+        configured_headers = options[:global]&.dig(:headers) || options.dig("global", "headers") ||
+                             options[:headers] || options["headers"] || {}
+        configured_auth = configured_headers["Authorization"] || configured_headers[:Authorization]
       end
 
       client = new(supabase_url: supabase_url, supabase_key: supabase_key,
@@ -77,9 +78,8 @@ module Supabase
       # is kept as a raw Hash so existing callers don't break — anything
       # else is canonicalized into a ClientOptions struct so the per-sub-
       # client kwargs derivation has one code path.
-      legacy_hash_shape =
-        options.is_a?(Hash) &&
-          options.keys.any? { |k| %i[auth postgrest storage functions realtime global].include?(k.to_sym) }
+      legacy_hash_shape = options.is_a?(Hash) && legacy_options_hash?(options)
+      warn_stray_legacy_keys(options) if legacy_hash_shape
 
       @options =
         if options.is_a?(Hash) && !legacy_hash_shape
@@ -109,6 +109,14 @@ module Supabase
         "apikey"        => @supabase_key,
         "Authorization" => "Bearer #{@supabase_key}"
       }.merge(configured_headers || {})
+
+      # Current access token used to authorize the data-plane sub-clients
+      # (postgrest/storage/functions) and the realtime socket. Starts as the
+      # anon key and is rotated by #apply_auth on sign-in / token refresh. Held
+      # explicitly (rather than re-derived from @headers) so that a realtime
+      # client built LAZILY after a sign-in still picks up the session token
+      # instead of the anon key — see #realtime.
+      @access_token = @supabase_key
     end
 
     def async?
@@ -143,9 +151,13 @@ module Supabase
     end
 
     def realtime
+      # Use the current access token (@access_token), not the anon key: if the
+      # caller signed in before this lazy accessor first ran, apply_auth could
+      # not push the token to a not-yet-built realtime client, so we must seed
+      # the join auth from the rotated token here. apikey stays the anon key.
       @realtime ||= Realtime::Client.new(
         url:    realtime_url,
-        params: { "apikey" => @supabase_key, "access_token" => @supabase_key },
+        params: { "apikey" => @supabase_key, "access_token" => @access_token },
         **sub_options(:realtime)
       )
     end
@@ -226,6 +238,47 @@ module Supabase
 
     private
 
+    # Keys that only occur in the legacy nested options shape — none of them
+    # is a ClientOptions field, so their presence is an unambiguous marker.
+    # `:storage` and `:realtime` are deliberately NOT in this list: both are
+    # also ClientOptions fields and need value-based disambiguation below.
+    LEGACY_ONLY_OPTION_KEYS = %i[auth postgrest functions global].freeze
+    # Every key the legacy nested shape consumes; anything else passed
+    # alongside one of these is silently invisible to the sub-clients.
+    LEGACY_OPTION_KEYS = (LEGACY_ONLY_OPTION_KEYS + %i[storage realtime]).freeze
+    private_constant :LEGACY_ONLY_OPTION_KEYS, :LEGACY_OPTION_KEYS
+
+    def legacy_options_hash?(options)
+      return true if options.keys.any? { |k| LEGACY_ONLY_OPTION_KEYS.include?(k.to_sym) }
+
+      # `:storage` exists in both shapes. A Hash can only be the legacy
+      # per-sub-client kwargs — the ClientOptions field holds a session
+      # storage *object* (get_item/set_item duck type), never a Hash.
+      #
+      # `:realtime` is a kwargs Hash in both shapes and both code paths hand
+      # it to Realtime::Client unchanged, so on its own it is not a legacy
+      # marker — routing it through ClientOptions keeps sibling fields like
+      # `:schema` from being silently dropped.
+      option_value(options, :storage).is_a?(Hash)
+    end
+
+    def option_value(options, key)
+      options.key?(key) ? options[key] : options[key.to_s]
+    end
+
+    # The legacy shape only routes its known nested keys; flat ClientOptions
+    # fields mixed in (e.g. `{ schema: "x", auth: {...} }`) never reach any
+    # sub-client. Losing them silently was the original failure mode of the
+    # shape detector, so make the remaining ambiguous case loud.
+    def warn_stray_legacy_keys(options)
+      stray = options.keys.map(&:to_sym) - LEGACY_OPTION_KEYS
+      return if stray.empty?
+
+      warn "Supabase::Client: options #{stray.inspect} are ignored when combined with the " \
+           "legacy nested options shape (#{LEGACY_OPTION_KEYS.inspect} keys). Pass a flat " \
+           "ClientOptions-style hash or a Supabase::ClientOptions instance to use them."
+    end
+
     # Single internal path shared by the public `#set_auth` and the
     # `on_auth_state_change` listener installed on `#auth`. Refreshes the
     # Authorization header used by every non-auth sub-client and resets their
@@ -238,7 +291,8 @@ module Supabase
     # waiting for every joined channel's `Socket#send` to drain — see
     # spec/async/apply_auth_non_blocking_spec.rb (US-047 / US-048).
     def apply_auth(token)
-      @headers["Authorization"] = "Bearer #{token || @supabase_key}"
+      @access_token = token || @supabase_key
+      @headers["Authorization"] = "Bearer #{@access_token}"
       @storage = @functions = @postgrest = nil
       dispatch_realtime { @realtime&.set_auth(token) }
     end

data/lib/supabase/functions/async/client.rb

@@ -34,6 +34,7 @@ module Supabase
 
         def build_session
           Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+            f.response :follow_redirects
             f.options.timeout = @timeout
             f.options.open_timeout = @timeout
             f.adapter :async_http

data/lib/supabase/functions/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/follow_redirects"
 require "json"
 require "uri"
 
@@ -134,6 +135,7 @@ module Supabase
 
       def build_session
         Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          f.response :follow_redirects
           f.options.timeout = @timeout
           f.options.open_timeout = @timeout
           f.adapter Faraday.default_adapter
@@ -170,7 +172,13 @@ module Supabase
       def raise_for_relay!(response)
         # The relay layer signals its own errors via this response header (set to
         # "true"). The function itself doesn't set this — only the relay.
-        relay = response.headers["x-relay-header"] || response.headers["X-Relay-Header"]
+        #
+        # DIVERGES FROM PY (intentional): supabase-py reads `x-relay-header`,
+        # which is a long-standing bug — the actual relay error header is
+        # `x-relay-error` (see @supabase/functions-js: `headers.get('x-relay-error')`).
+        # We follow supabase-js (the canonical client) so relay errors are
+        # detected against a real Supabase deployment.
+        relay = response.headers["x-relay-error"] || response.headers["X-Relay-Error"]
         return unless relay == "true"
 
         parsed = parse_json_safe(response.body) || {}
@@ -193,7 +201,12 @@ module Supabase
         when "json"
           return body if body.empty?
 
-          parse_json_safe(body) || body
+          # The caller explicitly asked for JSON, so a body that doesn't parse
+          # is a contract violation and must surface — not be silently handed
+          # back as a raw String (which the old `parse_json_safe(body) || body`
+          # did, leaving callers to discover the wrong type at runtime). Mirrors
+          # supabase-py's `response.json()`, which raises on invalid JSON.
+          JSON.parse(body)
         when "binary"
           # Byte-for-byte copy with BINARY (ASCII-8BIT) encoding. Faraday may
           # hand us the body tagged as UTF-8 even when it's raw bytes; force

data/lib/supabase/postgrest/async/client.rb

@@ -39,6 +39,7 @@ module Supabase
           Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
             f.request :url_encoded
             f.options.params_encoder = Faraday::FlatParamsEncoder
+            f.response :follow_redirects
             if @timeout
               f.options.timeout = @timeout
               f.options.open_timeout = @timeout

data/lib/supabase/postgrest/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/follow_redirects"
 
 require_relative "request_builder"
 require_relative "version"
@@ -174,6 +175,9 @@ module Supabase
         Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
           f.request :url_encoded
           f.options.params_encoder = Faraday::FlatParamsEncoder
+          # Follow 3xx like supabase-py's httpx `follow_redirects=True`, so a
+          # PostgREST/proxy redirect doesn't surface as an APIError.
+          f.response :follow_redirects
           if @timeout
             f.options.timeout = @timeout
             f.options.open_timeout = @timeout

data/lib/supabase/realtime/README.md

@@ -159,21 +159,26 @@ shared state нет в принципе (asyncio однопоточен), но
 - **Явный `connect` к недоступному серверу не «успешен молча».** Первичный
   `client.connect` ходит на транспорт синхронно: если `Socket#connect`
   бросает (типично `Errno::ECONNREFUSED` / `SocketError` от
-  `websocket-client-simple`), это исключение пробрасывается из
-  `Client#connect` сразу, без внутреннего ретрая. Поведение совпадает с
-  py: `await connect()` тоже бросает на постоянной ошибке. Бэкграунд-цикл
-  и `on_reconnect_failed` относятся ИСКЛЮЧИТЕЛЬНО к ситуации
-  «соединение установилось и потом упало», а не «никогда не поднималось
-  первый раз».
+  `websocket-client-simple`), `Client#connect` ретраит с экспоненциальным
+  бэкоффом как в py (`initial_backoff * 2^(n-1)`, кап 60 с) до `max_retries`
+  попыток суммарно и затем пробрасывает последнюю ошибку. При
+  `auto_reconnect: false` первая же ошибка пробрасывается сразу — тоже
+  паритет с py. Бэкграунд-цикл и `on_reconnect_failed` относятся к
+  ситуациям «соединение установилось и потом упало» и «транспорт сообщил
+  об ошибке асинхронно» (некоторые адаптеры открывают сокет в фоне и не
+  бросают из `connect` синхронно — тогда первичный сбой тоже уходит в
+  бэкграунд-цикл).
 
 Сводка контракта:
 
-| Сценарий                                  | Поведение                            |
-|-------------------------------------------|--------------------------------------|
-| Первичный `connect`, сервер недоступен    | `raise` (как в py)                   |
-| Установленный сокет, сервер дропнул       | бэкграунд-реконнект до `max_retries` |
-| Все `max_retries` исчерпаны               | `on_reconnect_failed.(last_error)`   |
-| Явный `disconnect` во время бэкоффа       | колбэк НЕ вызывается                 |
+| Сценарий                                       | Поведение                                          |
+|------------------------------------------------|----------------------------------------------------|
+| Первичный `connect`, сервер недоступен (sync)  | ретраи с бэкоффом, затем `raise` (как в py)        |
+| То же при `auto_reconnect: false`              | `raise` сразу, без ретраев (как в py)              |
+| Транспорт сигналит сбой асинхронно             | бэкграунд-реконнект → `on_reconnect_failed`        |
+| Установленный сокет, сервер дропнул            | бэкграунд-реконнект до `max_retries`               |
+| Все `max_retries` исчерпаны (бэкграунд)        | `on_reconnect_failed.(last_error)`                 |
+| Явный `disconnect` во время бэкоффа            | ретраи прекращаются, колбэк НЕ вызывается          |
 
 ## Testing
 

data/lib/supabase/realtime/channel.rb

@@ -85,26 +85,31 @@ module Supabase
         @state = Types::ChannelStates::JOINING
 
         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)
+        # Make subscribe a one-call entry point. If the socket is already open,
+        # send the join now. If it isn't, just (idempotently) open it — the
+        # client's rejoin_channels fires on socket-open and (re)sends the join
+        # exactly once. The previous version sent/buffered the join here AND let
+        # rejoin_channels re-send it on open, so a subscribe-before-open issued
+        # a DUPLICATE join; the server phx_closed the extra one, which (with the
+        # registry-removal fix) tore the channel down and broke delivery. Caught
+        # by the live integration suite, not the mocked specs.
+        if @socket && !@socket.connected?
+          @socket.connect
+        else
+          send_join_push
+        end
         self
       end
 
       # Re-issue the join push without resetting @joined_once. Used by the
-      # client after a socket reconnect to restore channel subscriptions.
+      # client after a socket reconnect to restore channel subscriptions, and by
+      # the rejoin timer after a join error.
       def rejoin
         return unless @joined_once
 
         @state = Types::ChannelStates::JOINING
         inject_postgres_changes_bindings
-        @join_push.instance_variable_set(:@ref, @socket&.next_ref)
-        @join_push.instance_variable_set(:@received_status, nil)
-        send_push(@join_push, register_pending: true)
+        send_join_push
         self
       end
 
@@ -221,6 +226,26 @@ module Supabase
         self
       end
 
+      # Push the rotated access_token to the server for this channel. Called by
+      # {Client#set_auth} for every joined channel, mirroring supabase-py
+      # (client.py:335-337): `await channel.push(ChannelEvents.access_token,
+      # {"access_token": token})`. Routing through the normal push path means the
+      # frame is buffered (not dropped) when the socket is momentarily offline,
+      # matching py's `channel.push` buffering — the prior version only sent when
+      # `connected?` and silently lost the rotation otherwise.
+      def push_access_token(token)
+        return unless @joined_once
+
+        ref  = @socket&.next_ref
+        push = Push.new(self,
+                        Types::ChannelEvents::ACCESS_TOKEN,
+                        { "access_token" => token },
+                        ref: ref,
+                        timeout: Types::DEFAULT_TIMEOUT_SECONDS)
+        send_push(push, register_pending: true)
+        self
+      end
+
       # Public low-level push for arbitrary Phoenix events. Mirrors
       # `supabase-py`'s `channel.push(event, payload, timeout)`. Returns the
       # {Push} instance so callers can attach receive() handlers and observe the
@@ -257,19 +282,21 @@ module Supabase
         when Types::ChannelEvents::PRESENCE_DIFF
           @presence.sync_diff(message.payload)
         when Types::ChannelEvents::SYSTEM
-          @system_callbacks.each do |cb|
-            CallbackSafety.safe(logger, "system") { cb.call(message.payload) }
+          # supabase-py routes system frames by status (channel.py:520-525): a
+          # `status: "ok"` payload reaches the on_system callbacks; anything else
+          # (e.g. a postgres_changes subscription failure reported via `system`)
+          # is treated as a channel error → ERRORED + rejoin scheduled.
+          if message.payload.is_a?(Hash) && message.payload["status"] == "error"
+            trigger_channel_error(message.payload)
+          else
+            @system_callbacks.each do |cb|
+              CallbackSafety.safe(logger, "system") { cb.call(message.payload) }
+            end
           end
         when Types::ChannelEvents::CLOSE
-          @state = Types::ChannelStates::CLOSED
-          @close_callbacks.each do |cb|
-            CallbackSafety.safe(logger, "phx_close") { cb.call(message.payload) }
-          end
+          handle_channel_close(message.payload)
         when Types::ChannelEvents::ERROR
-          @state = Types::ChannelStates::ERRORED
-          @error_callbacks.each do |cb|
-            CallbackSafety.safe(logger, "phx_error") { cb.call(message.payload) }
-          end
+          trigger_channel_error(message.payload)
         end
 
         true
@@ -292,10 +319,23 @@ 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. 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).
+      # server starts emitting presence_state/diff frames.
+      #
+      # The access_token is placed at the ROOT of the join payload (a sibling of
+      # "config"), and only when a token is actually present — matching
+      # supabase-py's `channel.py` exactly:
+      #
+      #   config_payload = { "config": { ... } }
+      #   if self.socket.access_token:
+      #       config_payload["access_token"] = self.socket.access_token
+      #
+      # The server / Phoenix gateway reads `payload.access_token`, NOT
+      # `payload.config.access_token`. Nesting it under config (as a prior
+      # version of this port did) meant the caller's JWT never reached RLS and
+      # private channels authorized with the URL apikey only. The token source is
+      # the same field set_auth rotates (Client#access_token) — single source of
+      # truth. On rejoin the payload hash is reused, so an explicitly-cleared
+      # token must delete the stale key rather than leave it behind.
       def inject_postgres_changes_bindings
         config = (@join_push.payload["config"] ||= {})
         config["postgres_changes"] = @postgres_changes_callbacks.map do |binding|
@@ -309,7 +349,12 @@ module Supabase
         presence_cfg = (config["presence"] ||= {})
         presence_cfg["enabled"] = true if @presence.any_callbacks?
 
-        config["access_token"] = @socket&.access_token
+        token = @socket&.access_token
+        if token
+          @join_push.payload["access_token"] = token
+        else
+          @join_push.payload.delete("access_token")
+        end
       end
 
       # If a presence callback is added after the channel is already joined,
@@ -324,6 +369,20 @@ module Supabase
         subscribe(&@subscribe_callback)
       end
 
+      # Put the join push on the wire — but only when the socket is actually
+      # open. When it isn't, the join is intentionally NOT sent or buffered here:
+      # the client's rejoin_channels re-sends it the moment the socket opens, and
+      # sending/buffering it here too would duplicate the join (the server then
+      # phx_closes the extra one). Assigns a fresh ref and clears any prior reply
+      # status so a rejoin is matched to its own phx_reply.
+      def send_join_push
+        return unless @socket&.connected?
+
+        @join_push.instance_variable_set(:@ref, @socket.next_ref)
+        @join_push.instance_variable_set(:@received_status, nil)
+        send_push(@join_push, register_pending: true)
+      end
+
       def send_push(push, register_pending:)
         message = Message.new(
           event:    push.event,
@@ -333,14 +392,15 @@ module Supabase
           join_ref: @join_push.ref
         )
 
+        if register_pending && push.ref
+          @pending_pushes[push.ref] = push
+          # Arm the timeout when the push is queued, not when it hits the wire
+          # (py parity, channel.py:318-323): a push buffered on a channel that
+          # never reaches JOINED must resolve TIMEOUT, not hang forever.
+          push.start_timeout
+        end
+
         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
-            # gets buffered (channel not yet joined) we leave it untimed until
-            # the buffer is flushed.
-            push.start_timeout
-          end
           @socket&.push(message)
         else
           @push_buffer << [push, register_pending]
@@ -385,13 +445,18 @@ module Supabase
           next unless binding[:event] == change_type || binding[:event] == "*"
           next if binding[:schema] && binding[:schema] != schema
           next if binding[:table]  && binding[:table]  != table
-          # 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.
+          # DIVERGES FROM PY/JS (intentional — see docs/PARITY.md D7): supabase-py
+          # AND realtime-js demultiplex postgres_changes *solely* by the
+          # server-assigned binding id (`id && ids.include?(id)`), so a binding
+          # with no id fires for nothing. We instead filter client-side on
+          # event/schema/table (above) and use the server id only as an
+          # additional demux when present. This is more robust — events still
+          # route correctly even if the server omits ids — at the cost of one
+          # narrow edge case: two bindings on the SAME (schema, table, event)
+          # differing only by `:filter`, while neither has a server id yet, will
+          # both fire (we don't evaluate PostgREST `:filter` client-side). In the
+          # normal flow on_join_ok records the ids on the join-ack, after which
+          # this gate demuxes them correctly.
           next if binding[:id] && ids.is_a?(Array) && !ids.include?(binding[:id])
 
           CallbackSafety.safe(logger, "postgres_changes:#{binding[:event]}") do
@@ -480,13 +545,52 @@ module Supabase
       def flush_push_buffer
         buffered = @push_buffer
         @push_buffer = []
-        buffered.each { |push, register_pending| send_push(push, register_pending: register_pending) }
+        buffered.each do |push, register_pending|
+          # A push that resolved while buffered (timed out waiting for the join)
+          # must not go on the wire late — its caller already saw TIMEOUT.
+          next if push.received_status
+
+          send_push(push, register_pending: register_pending)
+        end
       end
 
       def on_leave_ack
+        handle_channel_close({})
+      end
+
+      # Channel teardown — mirrors supabase-py `channel.on_close`
+      # (channel.py:134-138): cancel any pending rejoin, mark CLOSED, fire the
+      # registered close listeners, and remove the channel from the owning
+      # client's registry so a CLOSED channel no longer receives dispatched
+      # frames and doesn't leak across a subscribe/unsubscribe churn cycle. The
+      # registry removal is the fix for the prior leak where unsubscribed
+      # channels stayed in `client.channels` forever and kept running
+      # presence/broadcast dispatch.
+      #
+      # (Named distinctly from the public {#on_close} listener registrar, which
+      # is an rb-only convenience with no py counterpart.)
+      def handle_channel_close(payload = {})
+        @rejoin_timer.reset
         @state = Types::ChannelStates::CLOSED
         @close_callbacks.each do |cb|
-          CallbackSafety.safe(logger, "phx_close") { cb.call({}) }
+          CallbackSafety.safe(logger, "phx_close") { cb.call(payload) }
+        end
+        @socket._remove_channel(self) if @socket.respond_to?(:_remove_channel)
+      end
+
+      # Mirrors supabase-py `channel.on_error` (channel.py:140-146): a phx_error
+      # frame, or a `system` frame with status "error", errors the channel and
+      # schedules a rejoin with exponential backoff so a transient server-side
+      # channel crash self-heals instead of staying dead until the whole socket
+      # drops. No-op while LEAVING/CLOSED so a phx_error racing an unsubscribe
+      # can't flip the channel back to ERRORED.
+      def trigger_channel_error(payload)
+        return if leaving? || closed?
+
+        @state = Types::ChannelStates::ERRORED
+        @rejoin_timer.schedule_timeout
+        @error_callbacks.each do |cb|
+          CallbackSafety.safe(logger, "phx_error") { cb.call(payload) }
         end
       end
     end

data/lib/supabase/realtime/client.rb

@@ -36,7 +36,9 @@ module Supabase
                   :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 params [Hash]   query-string params merged onto the URL (e.g. apikey).
+      #   `access_token` is accepted here but is NOT serialized into the URL —
+      #   it is carried in join payloads / access_token pushes instead.
       # @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.
@@ -75,6 +77,7 @@ module Supabase
         @logger             = logger
         @heartbeat_thread   = nil
         @reconnect_thread   = nil
+        @connecting         = false
         @intentionally_closed = false
         @send_buffer        = [] # frames queued while no socket / not connected
         @send_buffer_mutex  = Mutex.new
@@ -111,14 +114,49 @@ module Supabase
         self
       end
 
+      # Establish the WebSocket connection. Mirrors supabase-py's `connect()`
+      # (client.py:141-193): synchronous transport failures are retried with
+      # exponential backoff — `initial_backoff * 2^(n-1)` seconds, capped at
+      # 60s — for up to `max_retries` total attempts, then the last error is
+      # re-raised to the caller. With `auto_reconnect: false` the first
+      # failure raises immediately, as in py.
+      #
+      # Only failures that `Socket#connect` raises *synchronously* are retried
+      # here. Transports that report failure asynchronously (on_error/on_close
+      # after connect returns) are recovered by the background reconnect loop
+      # (schedule_reconnect → on_reconnect_failed) — same contract, different
+      # signal path. A concurrent `disconnect` aborts the retry loop quietly.
       def connect
         unless @socket
           @socket = build_default_transport
           attach_socket
         end
 
+        # Idempotent: if a connection is already open or in flight, don't kick
+        # off a second transport.connect. A duplicate connect can produce a
+        # second on_open, which would fire rejoin_channels twice and send a
+        # duplicate join per channel (the server then phx_closes the extra one).
+        # This matters because Channel#subscribe calls connect when the socket
+        # isn't open yet, and the caller may have already called connect.
+        return self if connected? || @connecting
+
         @intentionally_closed = false
-        @socket.connect
+        attempts = 0
+        begin
+          @connecting = true
+          @socket.connect
+        rescue StandardError
+          # Reset the in-flight flag so the retry (and any later connect call)
+          # isn't short-circuited by the idempotency guard above.
+          @connecting = false
+          attempts += 1
+          raise if !@auto_reconnect || attempts >= @max_retries
+
+          sleep [@initial_backoff * (2**(attempts - 1)), 60.0].min
+          return self if @intentionally_closed
+
+          retry
+        end
         self
       end
 
@@ -161,7 +199,24 @@ module Supabase
       def remove_channel(channel)
         channel.unsubscribe
         @channels.delete(channel)
-        @socket&.close if @channels.empty?
+        # Close the socket once the registry empties — mirrors supabase-py's
+        # `remove_channel` (which calls `self.close()` when `len(channels) == 0`).
+        # Use the intentional-close path (`disconnect`), not a bare
+        # `@socket.close`: the latter fires on_close → schedule_reconnect and the
+        # socket would immediately come back up.
+        disconnect if @channels.empty?
+      end
+
+      # Internal: drop a channel from the registry without unsubscribing it.
+      # Called by {Channel#on_close} when a channel reaches CLOSED on its own
+      # (leave-ack or a server phx_close), mirroring supabase-py's
+      # `socket._remove_channel` (client.py:294-295). Distinct from the public
+      # {#remove_channel}, which actively unsubscribes. Removes the specific
+      # channel object (topics can repeat in the flat registry). Does not close
+      # the socket — that auto-close only happens via the explicit
+      # remove_channel/remove_all_channels paths, matching py.
+      def _remove_channel(channel)
+        @channels.delete(channel)
       end
 
       # Unsubscribe every tracked channel and clear the registry. Iterates over a
@@ -172,6 +227,9 @@ module Supabase
       def remove_all_channels
         @channels.dup.each { |ch| ch.unsubscribe }
         @channels.clear
+        # supabase-py's remove_all_channels unsubscribes every channel and then
+        # `await self.close()`. Match that — intentional close, no reconnect.
+        disconnect
         self
       end
 
@@ -180,30 +238,19 @@ module Supabase
       #
       # 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.
+      # `Channel#inject_postgres_changes_bindings`.
+      #
+      # The fan-out mirrors supabase-py (client.py:333-337): for every joined
+      # channel, `channel.push(access_token, {access_token: token})`. Routing
+      # through the channel's push path (rather than sending a raw frame only
+      # when `connected?`) means a rotation issued while the socket is briefly
+      # offline is buffered and replayed on reconnect, not silently dropped.
       def set_auth(token)
         @access_token = token
         @params["access_token"] = token if @params.is_a?(Hash)
 
-        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
+        @channels.each do |channel|
+          channel.push_access_token(token) if channel.joined?
         end
       end
 
@@ -265,9 +312,25 @@ module Supabase
         @socket.on_message { |raw| handle_inbound(raw) }
         @socket.on_open    { handle_socket_open }
         @socket.on_close   { handle_socket_close }
+        @socket.on_error   { |err| handle_socket_error(err) }
+      end
+
+      # A transport-level error (failed write, protocol error) means the
+      # connection is effectively dead. supabase-py funnels both heartbeat-send
+      # failures and socket errors into `_on_connect_error` → `_reconnect`
+      # (client.py:212-221). Some transports surface an abrupt drop only as an
+      # error and never fire on_close, so wiring this here is what keeps a
+      # half-dead connection from silently never reconnecting. Honors the same
+      # intentional-close / auto_reconnect gating as handle_socket_close.
+      def handle_socket_error(_err = nil)
+        stop_heartbeat
+        return if @intentionally_closed || !@auto_reconnect
+
+        schedule_reconnect
       end
 
       def handle_socket_open
+        @connecting = false
         flush_send_buffer
         start_heartbeat
         rejoin_channels
@@ -291,6 +354,7 @@ module Supabase
       end
 
       def handle_socket_close
+        @connecting = false
         stop_heartbeat
         return if @intentionally_closed || !@auto_reconnect
 
@@ -313,7 +377,14 @@ module Supabase
             begin
               send_heartbeat
             rescue StandardError
-              # Swallow — a transient send error shouldn't kill the heartbeat loop.
+              # A heartbeat write failure means the connection is dead. Mirror
+              # supabase-py (client.py:270-271), which routes the failure into
+              # the reconnect sequence rather than swallowing it — otherwise a
+              # half-dead socket that errors on write but never fires on_close
+              # would never recover. Break the loop; handle_socket_error
+              # (re)starts heartbeat after a successful reconnect.
+              handle_socket_error
+              break
             end
           end
         end
@@ -404,8 +475,18 @@ module Supabase
         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 }
+        # The user JWT must never appear in the URL: supabase-py puts only
+        # `apikey` in the query string (client.py:78-79) and carries the access
+        # token in join payloads / access_token pushes. URLs are logged by
+        # proxies and servers, so serializing the token here would leak it.
+        # `access_token` stays available via @access_token for joins/set_auth.
+        query = { "vsn" => Types::VSN }
+        if params && !params.empty?
+          url_params = params.transform_keys(&:to_s)
+          url_params.delete("access_token")
+          url_params.compact!
+          query = query.merge(url_params)
+        end
 
         separator = normalized.include?("?") ? "&" : "?"
         "#{normalized}#{separator}#{URI.encode_www_form(query)}"

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "async"
+require "async/variable"
 require "async/http/endpoint"
 require "async/websocket/client"
 require "protocol/websocket/message"
@@ -72,7 +73,12 @@ module Supabase
           end
 
           endpoint = ::Async::HTTP::Endpoint.parse(@url)
-          ready    = ::Async::Promise.new
+          # Async::Variable, not Async::Promise: Promise only exists in newer
+          # async releases (Ruby >= 3.2 resolutions), while Variable is
+          # available across all async 2.x — and 3.1 resolves async 2.24.
+          # Variable has no #reject, so a connect error is resolved as a value
+          # and re-raised by the waiting side below.
+          ready = ::Async::Variable.new
 
           @session = parent.async do
             @connector.connect(endpoint, headers: header_pairs) do |connection|
@@ -84,15 +90,17 @@ module Supabase
             end
           rescue => err
             fire_error(err)
-            ready.reject(err) unless ready.resolved?
+            ready.resolve(err) unless ready.resolved?
           ensure
             fire_close
           end
 
-          # Cooperative wait — Promise buffers the resolution, so this returns
+          # Cooperative wait — Variable 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
+          outcome = ready.wait
+          raise outcome if outcome.is_a?(Exception)
+
           nil
         end
 

data/lib/supabase/storage/analytics.rb

@@ -49,7 +49,11 @@ module Supabase
       # a plain Hash that a downstream iceberg-ruby (when one exists) can consume.
       # Keeping the public method present mirrors the API surface.
       def catalog(catalog_name, access_key_id:, secret_access_key:)
-        service_key = @headers["apiKey"]
+        # py reads the header through case-insensitive `httpx.Headers`; the
+        # umbrella Supabase::Client sends "apikey" (lowercase), so match any
+        # casing (exact "apiKey" wins if both spellings are present).
+        service_key = @headers["apiKey"] ||
+                      @headers.find { |k, _| k.to_s.casecmp?("apikey") }&.last
         raise Errors::StorageApiError.new("apiKey must be passed in the headers.") if service_key.to_s.empty?
 
         s3_endpoint = @base_url.sub(%r{iceberg/?\z}, "s3")

data/lib/supabase/storage/file_api.rb

@@ -290,8 +290,14 @@ module Supabase
       def build_upload_io(file, filename, content_type)
         case file
         when String
-          # Treat as raw bytes/text, not a path — call sites that want path semantics
-          # pass a Pathname or open the File themselves (matches storage3's bytes/IO contract).
+          # DIVERGES FROM PY (intentional): supabase-py treats a `str` as a
+          # filesystem PATH and opens it; raw bytes must be passed as
+          # bytes/BufferedReader. We treat a String as raw bytes/text and a
+          # Pathname (or any IO) as the file source. Rationale: this matches
+          # supabase-js (which takes Blob/Buffer/File, never a path string) and
+          # avoids the silent footgun where `upload("a.png", "./a.png")` would
+          # upload the literal path string. Callers that want path semantics
+          # pass `Pathname("./a.png")` or an opened File.
           Faraday::Multipart::FilePart.new(StringIO.new(file), content_type, filename)
         when Pathname
           Faraday::Multipart::FilePart.new(file.to_s, content_type, filename)

data/lib/supabase/storage/vectors.rb

@@ -90,7 +90,12 @@ module Supabase
       end
 
       def list_indexes(next_token: nil, max_results: nil, prefix: nil)
-        json = with_metadata("next_token" => next_token, "max_results" => max_results, "prefix" => prefix)
+        # DIVERGES FROM PY (intentional): supabase-py sends snake_case body keys
+        # here (`next_token`/`max_results`) while every other vectors action —
+        # list_buckets, list — uses camelCase (`nextToken`/`maxResults`). That
+        # inconsistency is a py bug; we send camelCase to match the sibling
+        # actions and the rest of the storage/vector API.
+        json = with_metadata("nextToken" => next_token, "maxResults" => max_results, "prefix" => prefix)
         body = @client.send_action(path: "ListIndexes", json: json)
         Types::ListVectorIndexesResponse.from_hash(body)
       end

data/lib/supabase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Supabase
-  VERSION = "3.2.0"
+  VERSION = "3.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: supabase-rb
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.2.1
 platform: ruby
 authors:
 - Supabase
@@ -107,6 +107,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +191,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.30'
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
 description: 'Ruby client for Supabase: Auth, PostgREST, Storage, Edge Functions,
   and Realtime exposed through a single Supabase.create_client(supabase_url:, supabase_key:)
   factory, mirroring supabase-py''s create_client().'
@@ -186,6 +214,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - lib/supabase-auth.rb
 - lib/supabase.rb
 - lib/supabase/README.md
@@ -261,14 +290,15 @@ files:
 - lib/supabase/storage/vectors.rb
 - lib/supabase/storage/version.rb
 - lib/supabase/version.rb
-homepage: https://github.com/supabase-ruby/supabase-rb
+homepage: https://supabase-ruby.dev
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/supabase-ruby/supabase-rb
+  homepage_uri: https://supabase-ruby.dev
   source_code_uri: https://github.com/supabase-ruby/supabase-rb
-  documentation_uri: https://github.com/supabase-ruby/supabase-rb/blob/master/lib/supabase/README.md
+  documentation_uri: https://supabase-ruby.dev/reference
   changelog_uri: https://github.com/supabase-ruby/supabase-rb/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/supabase-ruby/supabase-rb/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -276,7 +306,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="