supabase-rb 3.1.1 → 3.2.0

data/lib/supabase/functions/README.md

@@ -1,8 +1,8 @@
 # `supabase-functions`
 
 Ruby client for [Supabase Edge Functions](https://supabase.com/docs/guides/functions).
-Per-call control over body, headers, HTTP method, region routing, and
-response parsing. Mirrors the public surface of
+Per-call control over body, headers, region routing, and response parsing.
+Mirrors the public surface of
 [`supabase_functions`](https://github.com/supabase/supabase-py/tree/main/src/functions)
 in Python.
 
@@ -27,27 +27,36 @@ functions = Supabase::Functions::Client.new(
 )
 
 # Simple invoke (POST + JSON body)
-response = functions.invoke("hello", body: { name: "Ada" })
-response.data    # => parsed JSON or raw bytes
-response.status
-response.headers
+raw = functions.invoke("hello", body: { name: "Ada" })
+# => the raw response body as a String (default). Parsing is opt-in:
+
+data = functions.invoke("hello", body: { name: "Ada" }, response_type: :json)
+# => parsed JSON (Hash / Array / scalar). Same shape as supabase-py.
+
+# For the legacy wrapper carrying status + headers, pass
+# `return_response: true` — note: that path is deprecated.
 ```
 
-### Custom method / headers / query / region
+### Custom headers / region
 
 ```ruby
 functions.invoke(
   "ingest",
-  method:  "PUT",
   headers: { "X-Trace-Id" => "abc" },
-  query:   { tenant: "x" },
   region:  Supabase::Functions::Types::FunctionRegion::US_EAST_1,
   body:    payload_hash
 )
 ```
 
-`response.data` is auto-parsed when the response `Content-Type` is JSON,
-otherwise the raw body. Force parsing with `response_type: :json`.
+`#invoke` is always a POST — there is no `method:` kwarg. There is no
+`query:` kwarg either (the only query-string consumer is region routing,
+which is wired up internally). Both kwargs existed historically to mirror
+the supabase-js surface and were dropped in US-030 for parity with
+supabase-py.
+
+The return value is the raw response body unless you opt in with
+`response_type: :json` — Content-Type is intentionally ignored (parity with
+supabase-py, deliberately different from supabase-js).
 
 ### Errors
 
@@ -66,6 +75,84 @@ async = Supabase::Functions::Async::Client.new(
 )
 
 Async do
-  response = async.invoke("hello", body: { name: "Ada" })
+  data = async.invoke("hello", body: { name: "Ada" })
+end
+```
+
+## Differences from supabase-py
+
+### `timeout:`, `verify:`, `proxy:` are active constructor parameters
+
+In `supabase-py` these three kwargs on `SyncFunctionsClient.__init__` are
+**deprecated**: passing any of them emits a `DeprecationWarning` and the
+guidance is to configure the underlying `httpx.Client` instead
+(see `functions_client.py`).
+
+In `supabase-rb` they are **active and have well-defined effects** on the
+default Faraday session:
+
+| Kwarg     | Type            | Default | Effect                                                                    |
+|-----------|-----------------|---------|---------------------------------------------------------------------------|
+| `timeout` | `Numeric, nil`  | `60`    | Sets both `Faraday::Connection#options.timeout` and `.open_timeout` (sec).|
+| `verify`  | `Boolean`       | `true`  | Becomes `ssl: { verify: ... }` on the Faraday connection (TLS cert check).|
+| `proxy`   | `String, nil`   | `nil`   | Passed through as Faraday's `proxy:` option.                              |
+
+```ruby
+functions = Supabase::Functions::Client.new(
+  base_url: "https://project.supabase.co/functions/v1",
+  headers:  { "Authorization" => "Bearer #{key}" },
+  timeout:  30,
+  verify:   true,
+  proxy:    "http://corporate-proxy.local:3128"
+)
+```
+
+If you pass your own `http_client:` (a pre-built `Faraday::Connection`),
+`timeout`/`verify`/`proxy` are ignored — your Faraday is used as-is.
+
+### Retry — opt-in via Faraday middleware
+
+Neither `supabase-py` nor `supabase-rb` retries Edge Function calls
+automatically. In Ruby, the idiomatic way to add retries is to inject a
+Faraday connection with the [`faraday-retry`][faraday-retry] middleware:
+
+```ruby
+require "faraday"
+require "faraday/retry"
+require "supabase/functions"
+
+http = Faraday.new(url: "https://project.supabase.co/functions/v1") do |f|
+  f.request :retry,
+            max:            2,
+            interval:       0.5,
+            backoff_factor: 2,
+            retry_statuses: [429, 500, 502, 503, 504],
+            # `invoke` always POSTs, so opt POST into the retried set.
+            methods:        %i[get head options put delete post],
+            # Defaults cover Faraday::TimeoutError + Errno::ETIMEDOUT +
+            # Faraday::RetriableResponse — listing them explicitly keeps the
+            # set intact when we also want ConnectionFailed.
+            exceptions:     [Faraday::ConnectionFailed, Faraday::TimeoutError,
+                             Errno::ETIMEDOUT, Faraday::RetriableResponse]
+  f.options.timeout      = 60
+  f.options.open_timeout = 60
+  f.adapter Faraday.default_adapter
 end
+
+functions = Supabase::Functions::Client.new(
+  base_url:    "https://project.supabase.co/functions/v1",
+  headers:     { "Authorization" => "Bearer #{key}" },
+  http_client: http
+)
 ```
+
+`faraday-retry` is not a runtime dependency of `supabase-rb`; add
+`gem "faraday-retry"` to your `Gemfile` if you want this pattern.
+
+Be mindful that `invoke` is always a POST — by default `faraday-retry`
+only retries idempotent methods (`%i[delete get head options put]`), so
+you must opt POST in via `methods:` above if you want POST retries.
+Functions whose side effects are not idempotent should leave POST out
+of `methods:` to avoid double-execution.
+
+[faraday-retry]: https://github.com/lostisland/faraday-retry

data/lib/supabase/functions/client.rb

@@ -17,13 +17,19 @@ module Supabase
     #     headers:  { "Authorization" => "Bearer #{key}" }
     #   )
     #
-    #   response = functions.invoke("hello-world", body: { name: "Ada" })
-    #   response.data    # => parsed JSON or raw bytes
-    #   response.status  # => 200
-    #   response.headers # => { "content-type" => "application/json", ... }
+    #   raw = functions.invoke("hello-world", body: { name: "Ada" })
+    #   # => Ruby returns String; encoding depends on response_type
+    #   #    (:text → UTF-8, :binary → ASCII-8BIT, :json → parsed object).
+    #   data = functions.invoke("hello-world", body: { name: "Ada" }, response_type: :json)
+    #   # => parsed JSON Hash / Array / scalar.
+    #
+    # JSON parsing is opt-in via `response_type: :json` — Content-Type is not
+    # consulted (deliberately different from supabase-js).
+    #
+    # For the legacy `Types::Response` wrapper (data + status + headers), pass
+    # `return_response: true` — note that `Types::Response` is deprecated and
+    # will be removed in a future release.
     class Client
-      VALID_METHODS = %w[GET OPTIONS HEAD POST PUT PATCH DELETE].freeze
-
       attr_reader :base_url, :headers
 
       # @param base_url [String] full URL to the Edge Functions endpoint
@@ -54,24 +60,38 @@ module Supabase
 
       # Invoke an Edge Function by name.
       #
+      # Always POSTs. The `method:` and `query:` kwargs were dropped in US-030
+      # — they had no analogue in supabase-py and only existed to mirror the
+      # supabase-js surface (see Open Question §9.4). Region routing still
+      # appends `forceFunctionRegion` to the URL via the region branch below.
+      #
       # @param function_name [String]
       # @param body [Hash, String, nil] JSON-encoded if Hash, sent as-is if String
       # @param headers [Hash] per-invocation headers (merged over the client defaults)
-      # @param method [String, Symbol] HTTP method, defaults to "POST"
       # @param region [String, nil] one of {Types::FunctionRegion}::ALL
-      # @param response_type [Symbol, String] :json to parse JSON, anything else returns raw bytes
-      # @param query [Hash, nil] extra query-string params
-      # @return [Types::Response]
-      def invoke(function_name, body: nil, headers: {}, method: "POST", region: nil, response_type: :text, query: nil)
+      # @param response_type [Symbol, String] controls how the response body
+      #   is returned. Ruby always returns a `String` (unlike supabase-py, which
+      #   returns `bytes` for binary). Supported values:
+      #     * `:json`   — parse the body as JSON; returns Hash / Array / scalar.
+      #     * `:text`   — return a `String` with `Encoding::UTF_8` (default).
+      #     * `:binary` — return a `String` with `Encoding::BINARY`
+      #       (`ASCII-8BIT`), byte-for-byte equal to the HTTP response body.
+      #   Parsing/encoding is opt-in by the caller, never inferred from the
+      #   response Content-Type.
+      # @param return_response [Boolean] when true, return the deprecated
+      #   {Types::Response} wrapper (data + status + headers) instead of the
+      #   bare parsed body. Default `false` (US-026). The wrapper is scheduled
+      #   for removal — prefer reading the data directly.
+      # @return [Object, Types::Response] parsed body (Hash / String / Array /
+      #   nil) by default; the deprecated `Types::Response` struct when
+      #   `return_response: true` is passed.
+      def invoke(function_name, body: nil, headers: {}, region: nil, response_type: :text,
+                 return_response: false)
         validate_function_name!(function_name)
-
-        http_method = method.to_s.upcase
-        unless VALID_METHODS.include?(http_method)
-          raise ArgumentError, "method must be one of #{VALID_METHODS.join(', ')}"
-        end
+        validate_region!(region)
 
         merged_headers = @headers.merge(headers)
-        merged_query   = (query || {}).transform_keys(&:to_s)
+        merged_query   = {}
 
         if region && region != Types::FunctionRegion::ANY
           merged_headers["x-region"] = region
@@ -93,7 +113,7 @@ module Supabase
           end
 
         response = @session.run_request(
-          http_method.downcase.to_sym,
+          :post,
           "#{@base_url}/#{function_name}",
           encoded_body,
           merged_headers
@@ -101,14 +121,13 @@ module Supabase
           req.params.update(merged_query) unless merged_query.empty?
         end
 
-        raise_for_relay!(response)
         raise_for_status!(response)
+        raise_for_relay!(response)
+
+        data = parse_body(response, response_type)
+        return data unless return_response
 
-        Types::Response.new(
-          data:    parse_body(response, response_type),
-          status:  response.status,
-          headers: response.headers
-        )
+        Types::Response.new(data: data, status: response.status, headers: response.headers)
       end
 
       private
@@ -134,6 +153,20 @@ module Supabase
         raise ArgumentError, "function_name must be a non-empty String"
       end
 
+      # Reject regions that aren't in {Types::FunctionRegion::ALL}. Nil is fine
+      # (means "let the server pick"); FunctionRegion::ANY is explicitly allowed
+      # — the AC's `|| region == FunctionRegion::ANY` clause is redundant with
+      # the `ALL` check (ANY is already in ALL) but kept here in spirit so
+      # callers passing the sentinel string `"any"` also pass.
+      def validate_region!(region)
+        return if region.nil?
+        return if Types::FunctionRegion::ALL.include?(region)
+
+        raise ArgumentError,
+              "region must be one of Supabase::Functions::Types::FunctionRegion::ALL " \
+              "(got #{region.inspect})"
+      end
+
       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.
@@ -153,14 +186,22 @@ module Supabase
       end
 
       def parse_body(response, response_type)
-        return response.body if response.body.nil? || response.body.empty?
-
-        if response_type.to_s == "json"
-          parse_json_safe(response.body) || response.body
+        body = response.body
+        return body if body.nil?
+
+        case response_type.to_s
+        when "json"
+          return body if body.empty?
+
+          parse_json_safe(body) || 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
+          # the encoding so callers get a stable, lossless String.
+          body.dup.force_encoding(Encoding::BINARY)
         else
-          # Auto-detect JSON: if the server says application/json, parse it.
-          content_type = response.headers["content-type"] || response.headers["Content-Type"] || ""
-          content_type.include?("application/json") ? (parse_json_safe(response.body) || response.body) : response.body
+          # :text (default) — return a UTF-8 String.
+          body.dup.force_encoding(Encoding::UTF_8)
         end
       end
 

data/lib/supabase/functions/types.rb

@@ -3,9 +3,30 @@
 module Supabase
   module Functions
     module Types
-      # Returned by Client#invoke. `data` is parsed JSON when response_type: :json
-      # (or auto-detected from a JSON Content-Type), otherwise the raw response body.
-      Response = Struct.new(:data, :status, :headers, keyword_init: true)
+      # @deprecated US-026: `Client#invoke` now returns parsed body directly.
+      #   Pass `return_response: true` to {Supabase::Functions::Client#invoke}
+      #   to keep building this wrapper temporarily — both paths emit a
+      #   one-time deprecation warning. Slated for removal in a future
+      #   release. Read `data` directly from `invoke`'s return value instead.
+      class Response < Struct.new(:data, :status, :headers, keyword_init: true)
+        DEPRECATION_MESSAGE =
+          "[DEPRECATION] Supabase::Functions::Types::Response is deprecated " \
+          "(US-026): Supabase::Functions::Client#invoke now returns the parsed " \
+          "body directly. Pass `return_response: true` only as a temporary " \
+          "compatibility shim — this struct will be removed in a future release."
+
+        class << self
+          attr_accessor :_deprecation_warned
+        end
+
+        def self.new(*args, **kwargs)
+          unless _deprecation_warned
+            Kernel.warn(DEPRECATION_MESSAGE)
+            self._deprecation_warned = true
+          end
+          super
+        end
+      end
 
       # Supabase Edge Function regions. Use FunctionRegion::US_EAST_1 etc., or pass
       # the bare string ("us-east-1") to Client#invoke — both are accepted.

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

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

data/lib/supabase/postgrest/client.rb

@@ -12,6 +12,10 @@ module Supabase
       "Content-Type" => "application/json"
     }.freeze
 
+    # Per-request HTTP timeout (seconds) applied when callers don't supply
+    # one. Mirrors supabase-py's `DEFAULT_POSTGREST_CLIENT_TIMEOUT = 120`.
+    DEFAULT_POSTGREST_TIMEOUT = 120
+
     # Sync PostgREST client. Constructed once per project; reused across requests.
     #
     # ```ruby
@@ -42,7 +46,7 @@ module Supabase
         @http_client = http_client
         @verify = verify
         @proxy = proxy
-        @timeout = timeout
+        @timeout = timeout.nil? ? DEFAULT_POSTGREST_TIMEOUT : timeout
       end
 
       # Set the Authorization header to either Bearer (token) or Basic
@@ -132,8 +136,9 @@ module Supabase
                    "POST"
                  end
 
-        headers = @headers.dup
+        headers = {}
         headers["Prefer"] = "count=#{count}" if count
+        headers.merge!(@headers)
 
         if %w[HEAD GET].include?(method)
           query = stringify_keys(params)
@@ -167,6 +172,8 @@ module Supabase
 
       def build_session
         Faraday.new(url: @base_url, ssl: { verify: @verify }, proxy: @proxy) do |f|
+          f.request :url_encoded
+          f.options.params_encoder = Faraday::FlatParamsEncoder
           if @timeout
             f.options.timeout = @timeout
             f.options.open_timeout = @timeout

data/lib/supabase/postgrest/errors.rb

@@ -7,18 +7,30 @@ module Supabase
       # Mirrors supabase-py's APIError — exposes :message, :code, :hint, :details
       # plus the raw error hash via {#raw}.
       class APIError < StandardError
-        attr_reader :raw, :message, :code, :hint, :details
+        attr_reader :raw, :code, :hint, :details
 
         # @param error [Hash] parsed JSON body from a PostgREST error response
         def initialize(error = {})
-          @raw = error || {}
-          @message = @raw["message"] || @raw[:message]
-          @code = @raw["code"] || @raw[:code]
-          @hint = @raw["hint"] || @raw[:hint]
-          @details = @raw["details"] || @raw[:details]
+          if error.is_a?(Hash)
+            @raw = error
+            @message = @raw["message"] || @raw[:message]
+            @code = @raw["code"] || @raw[:code]
+            @hint = @raw["hint"] || @raw[:hint]
+            @details = @raw["details"] || @raw[:details]
+          elsif error.nil?
+            @raw = {}
+          else
+            @raw = error
+            @message = "PostgREST returned non-hash error: #{error.inspect}"
+          end
           super(to_s)
         end
 
+        # Override StandardError#message so the field-level value is non-nil.
+        def message
+          @message.to_s
+        end
+
         def to_s
           parts = []
           parts << "Error #{@code}:" if @code

data/lib/supabase/postgrest/request_builder.rb

@@ -338,18 +338,12 @@ module Supabase
 
       private
 
-      # PostgREST allows the same query key to appear multiple times (e.g. multiple
-      # `order=` or repeated filter columns). Ruby Hash collapses by key, so we
-      # store repeats as Arrays — Faraday emits them as multiple query params.
       def add_param(params, key, value)
-        existing = params[key]
-        params[key] = if existing.is_a?(Array)
-                        existing + [value]
-                      elsif existing
-                        [existing, value]
-                      else
-                        value
-                      end
+        if params.key?(key)
+          params[key] = Array(params[key]) << value
+        else
+          params[key] = value
+        end
         params
       end
     end

data/lib/supabase/realtime/README.md

@@ -31,6 +31,13 @@ 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.
 
+The same caveat applies to the channel rejoin timer: after a join error or
+timeout, the channel schedules a retry via `Supabase::Realtime::Timer`, which
+runs the rejoin on a background thread once the backoff delay elapses.
+Anything the rejoin path mutates (state shared with listener callbacks, the
+underlying `Socket`, etc.) must tolerate being touched from an arbitrary
+thread — consistent with the existing listener-thread model.
+
 ## Usage
 
 ```ruby
@@ -64,6 +71,110 @@ channel.presence.on_join  { |key, presence| ... }
 channel.presence.on_leave { |key, presence| ... }
 ```
 
+## Модель конкурентности
+
+Все пользовательские колбэки realtime исполняются на **read-треде websocket-
+гема** — том же, который читает фреймы из сокета. Транспорт по умолчанию
+(`Sockets::WebsocketClientSimple`) построен на
+[`websocket-client-simple`](https://github.com/shokai/websocket-client-simple),
+который спавнит этот тред сам в `connect`-блоке. Если вы инжектите свой
+адаптер (`include Supabase::Realtime::Socket`), правила те же — `Client`
+дёргает `message_callbacks` синхронно из `fire_message`, поэтому колбэк
+исполняется на том же треде, который вы пришлёте.
+
+**Где какие колбэки исполняются:**
+
+| Колбэк                                                                            | Тред                                                                       |
+|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------|
+| `channel.on_broadcast`, `on_postgres_changes`, `on_system`, `on_close`, `on_error`| read-тред транспорта                                                       |
+| `presence.on_sync`, `on_join`, `on_leave`                                         | read-тред транспорта (но фанятся ПОСЛЕ освобождения внутреннего mutex'а)   |
+| Блок `channel.subscribe { \|status, err\| ... }`                                  | read-тред транспорта                                                       |
+| `push.receive(:ok / :error) { ... }`                                              | read-тред (если ответ пришёл) ИЛИ push-timeout-тред (если сработал watchdog) |
+| `client.on_reconnect_failed { \|err\| ... }`                                      | reconnect-тред (см. секцию ниже)                                           |
+
+**Что от вас требуется внутри колбэка:**
+
+1. **Не блокировать.** Любая длительная операция в колбэке (синхронный HTTP,
+   тяжёлый БД-запрос, `sleep`, `Mutex#synchronize` на чужом локе) задерживает
+   обработку следующих фреймов на том же сокете. Если задержка превысит
+   `heartbeat_interval` — heartbeat не отправится, сервер дропнет соединение,
+   и стартует фоновый реконнект. Правильный паттерн — внутри колбэка только
+   декодинг payload + пушок в очередь / Sidekiq / собственный пул тредов;
+   тяжёлая работа — снаружи.
+
+2. **Тред-безопасность общего состояния.** Колбэк работает на read-треде, а
+   ваш основной код (Rails-контроллер, Sidekiq-воркер, ActiveRecord-
+   соединение) — на других. Любое разделяемое состояние, к которому вы
+   обращаетесь и из колбэка, и снаружи, должно быть защищено вами — мьютексом,
+   `Concurrent::Map`, атомиком, очередью с потокобезопасной семантикой и т.п.
+   Внутреннее состояние гема уже синхронизировано: `presence.state` возвращает
+   shallow-копию снимка (US-007), `Push` разруливает гонку «timeout vs reply»
+   под собственным мьютексом, `Channel#join_state` обновляется только из read-
+   треда. Всё, что лежит ВНЕ гема, — на пользователе.
+
+3. **Исключения уже изолированы.** `raise StandardError` из любого
+   пользовательского колбэка ловится `CallbackSafety` (US-002), логируется в
+   `Realtime::Client.new(logger:)` (или `$stderr` через `Kernel#warn`, если
+   логгер не задан) и **не убивает read-тред** — соседние колбэки и
+   следующие фреймы продолжают работать. Это страховка, а не штатный канал
+   ошибок: пользовательский код всё равно должен ловить свои ошибки явно,
+   иначе лог быстро превратится в шум.
+
+**Отличие от `supabase-py`.** Python-клиент построен на `asyncio`: read-loop
+там — это `await`-цикл внутри одной корутины, и колбэки (`async def`)
+дёргаются `await callback(payload)` в том же event-loop'е. Конкуренции по
+shared state нет в принципе (asyncio однопоточен), но блокирующий колбэк
+блокирует весь loop, а не «один тред из пула». В rb read-loop — это
+настоящий `Thread`, поэтому правила противоположные: блокировка локальна
+(страдает только один сокет), но shared state требует реальной
+синхронизации.
+
+## Realtime reconnect: отличие от supabase-py
+
+`Realtime::Client` отличается от `supabase-py` (`realtime/_async/client.py:141-193`)
+тем, как сообщает о реконнекте — это намеренное отклонение, продиктованное
+разницей моделей конкурентности (треды vs `asyncio`):
+
+- **Реконнект всегда фоновый.** Когда сервер закрывает сокет, rb запускает
+  отдельный тред с экспоненциальным бэкоффом (`initial_backoff` ×
+  `2^(n-1)`, капается на 60 с) и пытается переподключиться до `max_retries`
+  раз. В py та же логика «живёт» внутри корутины `connect()` — она
+  возвращает управление либо когда сокет встал, либо когда был исчерпан
+  бюджет ретраев (через `raise`).
+- **Окончательная неудача доходит через колбэк, а не исключение.** После
+  исчерпания `max_retries` rb вызывает каждый зарегистрированный колбэк
+  `on_reconnect_failed { |last_error| ... }` ровно один раз, с последним
+  пойманным исключением транспорта. Колбэки оборачиваются `CallbackSafety`
+  — раис в одном пользовательском блоке не блокирует остальные:
+
+  ```ruby
+  client.on_reconnect_failed do |err|
+    logger.error("realtime down for good: #{err.class}: #{err.message}")
+    notify_oncall!
+  end
+  ```
+
+  Если `disconnect` был вызван явно — колбэк не дёргается (это была
+  намеренная остановка, не сбой).
+- **Явный `connect` к недоступному серверу не «успешен молча».** Первичный
+  `client.connect` ходит на транспорт синхронно: если `Socket#connect`
+  бросает (типично `Errno::ECONNREFUSED` / `SocketError` от
+  `websocket-client-simple`), это исключение пробрасывается из
+  `Client#connect` сразу, без внутреннего ретрая. Поведение совпадает с
+  py: `await connect()` тоже бросает на постоянной ошибке. Бэкграунд-цикл
+  и `on_reconnect_failed` относятся ИСКЛЮЧИТЕЛЬНО к ситуации
+  «соединение установилось и потом упало», а не «никогда не поднималось
+  первый раз».
+
+Сводка контракта:
+
+| Сценарий                                  | Поведение                            |
+|-------------------------------------------|--------------------------------------|
+| Первичный `connect`, сервер недоступен    | `raise` (как в py)                   |
+| Установленный сокет, сервер дропнул       | бэкграунд-реконнект до `max_retries` |
+| Все `max_retries` исчерпаны               | `on_reconnect_failed.(last_error)`   |
+| Явный `disconnect` во время бэкоффа       | колбэк НЕ вызывается                 |
+
 ## Testing
 
 For unit testing, use `Supabase::Realtime::TestSocket` — an in-memory Socket

data/lib/supabase/realtime/callback_safety.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Supabase
+  module Realtime
+    # Helper for invoking user-supplied callbacks (channel/presence/push hooks)
+    # from the read-thread without letting a bad block tear down dispatch.
+    #
+    # supabase-py uses Python's exception-on-task semantics where one task's
+    # exception doesn't kill the listener (`realtime/_async/client.py:113-117`
+    # catches at the validation step; user-callback exceptions surface through
+    # `asyncio` task results). The rb port runs callbacks on the websocket-gem
+    # read-thread synchronously, so an unguarded exception kills the loop and
+    # silently stops delivery to *every* channel on the client. This helper
+    # rescues `StandardError`, logs a `warn` with the event name and the
+    # exception class/message, and lets the read-thread continue.
+    #
+    # @see US-002 acceptance criteria — "колбэк, бросающий исключение, не мешает
+    #   доставке следующего сообщения" / "исключение в колбэке одного канала не
+    #   мешает доставке сообщений в соседний".
+    module CallbackSafety
+      module_function
+
+      # Invoke `block` and swallow any `StandardError`, logging it via `logger`
+      # at `warn` level. When `logger` is nil or doesn't respond to `warn`,
+      # falls back to `Kernel#warn` ($stderr) so an unconfigured client still
+      # leaves a trace instead of failing silently.
+      def safe(logger, event_name)
+        yield
+      rescue StandardError => e
+        msg = "[Supabase::Realtime] callback for '#{event_name}' raised " \
+              "#{e.class}: #{e.message}"
+        if logger.respond_to?(:warn)
+          logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+        nil
+      end
+    end
+  end
+end