@supabase/realtime-js 2.108.2-beta.0 → 2.108.2-beta.5

package/migrations/httpsend-server-version.md

@@ -0,0 +1,88 @@
+# `httpSend()` server version requirement
+
+**Since:** v2.107.0
+**Applies to:** anyone calling `RealtimeChannel.httpSend()` (or `RealtimeChannel.broadcast()` configured to use HTTP)
+
+`httpSend()` sends broadcast events through a per-event REST endpoint:
+
+```
+POST /api/broadcast/:topic/events/:event
+```
+
+This endpoint was added in **Realtime server v2.97.0** ([supabase/realtime#1864](https://github.com/supabase/realtime/pull/1864)). It also enables binary broadcast payloads (`application/octet-stream`), which the older batch endpoint does not support.
+
+## What changed
+
+- `httpSend()` calls the new per-event endpoint and expects HTTP `202`.
+- On `404`, the client now rejects with a message that names the requirement and the escape hatches (see below) instead of returning the generic `Not Found` text from the server.
+- The original `RealtimeChannel.send()` (and its REST fallback) still target the older `POST /api/broadcast` batch endpoint and are unaffected.
+
+## Who is affected
+
+You are affected if **all** of the following are true:
+
+1. You upgraded `@supabase/realtime-js` (or `@supabase/supabase-js`) to **v2.107.0 or later**, **and**
+2. You call `httpSend()` (or `broadcast()` with `type: 'broadcast'` routed through HTTP), **and**
+3. Your Realtime server is **older than v2.97.0**.
+
+If you only use the WebSocket `send()` API, or your Realtime server is already on v2.97.0+, nothing changes for you.
+
+## How to verify the server version
+
+The Realtime server does not currently emit a version header, so the easiest checks are:
+
+- **Hosted Supabase:** version is rolled forward continuously and is on v2.97.0+.
+- **Local development with the Supabase CLI:** recent CLI versions bundle Realtime v2.97.0+. Update the CLI to the latest stable.
+- **Self-hosted:** check the `image:` tag of the Realtime container in your `docker-compose.yml`.
+
+## What to do
+
+### If you are on a recent Supabase CLI
+
+You should already be on a compatible Realtime version. If you still see the 404 error, update the CLI:
+
+```bash
+# macOS / Homebrew
+brew upgrade supabase/tap/supabase
+
+# npm
+npm install -g supabase
+
+# scoop / etc — see https://supabase.com/docs/guides/local-development
+```
+
+Then restart the local Supabase stack.
+
+### If you need to pin a specific Realtime version locally
+
+The CLI honors a per-project pin file. Create the file with the desired image tag:
+
+```bash
+mkdir -p supabase/.temp
+echo "v2.97.3" > supabase/.temp/realtime-version
+supabase stop && supabase start
+```
+
+(This is the same mechanism the `@supabase/supabase-js` test harness uses internally.)
+
+### If you self-host
+
+Bump the Realtime image in your deployment to `v2.97.3` or newer:
+
+```yaml
+services:
+  realtime:
+    image: supabase/realtime:v2.97.3
+```
+
+### If you cannot update the server right now
+
+Downgrade `@supabase/realtime-js` (and `@supabase/supabase-js`) back to **v2.106.x**, which only uses the older `POST /api/broadcast` batch endpoint:
+
+```bash
+npm install @supabase/supabase-js@2.106.2
+```
+
+## Why the message is more specific now
+
+Prior to this release, a 404 from the new endpoint surfaced as a plain `Not Found` error, which was hard to act on. The client now rejects with a message that points at this migration file and the escape hatches above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/realtime-js",
-  "version": "2.108.2-beta.0",
+  "version": "2.108.2-beta.5",
   "description": "Listen to realtime updates to your PostgreSQL database",
   "keywords": [
     "realtime",

package/src/RealtimeChannel.ts

@@ -179,6 +179,9 @@ export default class RealtimeChannel {
   broadcastEndpointURL: string
   private: boolean
   presence: RealtimePresence
+  private _postgresChangesSystemReady = false
+  private _subscribeCallback: ((status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void) | null =
+    null
   /** @internal */
   channelAdapter: ChannelAdapter
 
@@ -253,8 +256,22 @@ export default class RealtimeChannel {
 
     this.channelAdapter = new ChannelAdapter(this.socket.socketAdapter, topic, this.params)
     this.presence = new RealtimePresence(this)
+    this.channelAdapter.on(REALTIME_LISTEN_TYPES.SYSTEM, (payload: unknown) => {
+      if (
+        payload &&
+        typeof payload === 'object' &&
+        'extension' in payload &&
+        payload.extension === REALTIME_LISTEN_TYPES.POSTGRES_CHANGES &&
+        'status' in payload &&
+        payload.status === 'ok'
+      ) {
+        this._postgresChangesSystemReady = true
+        this._emitSubscribed()
+      }
+    })
 
     this._onClose(() => {
+      this._resetSubscribeState()
       this.socket._remove(this)
     })
 
@@ -277,6 +294,10 @@ export default class RealtimeChannel {
    * Log the full `err` so its `cause`, `name`, and any structured fields aren't hidden
    * behind `err.message`.
    *
+   * For channels that only bind `postgres_changes` callbacks, `SUBSCRIBED` is emitted after the
+   * server confirms the Postgres changefeed is ready. Channels with `broadcast` or `presence`
+   * callbacks keep the existing `SUBSCRIBED` timing.
+   *
    * @category Realtime
    *
    * @example Handling errors
@@ -297,6 +318,7 @@ export default class RealtimeChannel {
       this.socket.connect()
     }
     if (this.channelAdapter.isClosed()) {
+      this._resetSubscribeState()
       const {
         config: { broadcast, presence, private: isPrivate },
       } = this.params
@@ -344,11 +366,13 @@ export default class RealtimeChannel {
           this._updatePostgresBindings(postgres_changes, callback)
         })
         .receive('error', (error: { [key: string]: any }) => {
+          this._resetSubscribeState()
           this.state = CHANNEL_STATES.errored
           const message = Object.values(error).join(', ') || 'error'
           callback?.(REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR, new Error(message, { cause: error }))
         })
         .receive('timeout', () => {
+          this._resetSubscribeState()
           callback?.(REALTIME_SUBSCRIBE_STATES.TIMED_OUT)
         })
     }
@@ -396,7 +420,7 @@ export default class RealtimeChannel {
     this.bindings.postgres_changes = newPostgresBindings
 
     if (this.state != CHANNEL_STATES.errored && callback) {
-      callback(REALTIME_SUBSCRIBE_STATES.SUBSCRIBED)
+      this._onSubscribeOk(callback)
     }
   }
 
@@ -803,6 +827,16 @@ export default class RealtimeChannel {
       return { success: true }
     }
 
+    if (response.status === 404) {
+      return Promise.reject(
+        new Error(
+          'httpSend() requires Realtime server v2.97.0 or newer; the endpoint returned 404. ' +
+            'Update your Supabase CLI to a recent version, or upgrade the Realtime server in your self-hosted setup. ' +
+            'See https://github.com/supabase/supabase-js/blob/master/packages/core/realtime-js/migrations/httpsend-server-version.md'
+        )
+      )
+    }
+
     let errorMessage = response.statusText
     try {
       const errorBody = await response.json()
@@ -1121,6 +1155,39 @@ export default class RealtimeChannel {
     return normalizedServer === normalizedClient
   }
 
+  private _onSubscribeOk(callback: (status: REALTIME_SUBSCRIBE_STATES, err?: Error) => void) {
+    if (!this._shouldWaitForPostgresChangesSystem()) {
+      callback(REALTIME_SUBSCRIBE_STATES.SUBSCRIBED)
+      return
+    }
+
+    this._subscribeCallback = callback
+    this._emitSubscribed()
+  }
+
+  private _emitSubscribed() {
+    if (!this._subscribeCallback || !this._postgresChangesSystemReady) {
+      return
+    }
+
+    const callback = this._subscribeCallback
+    this._subscribeCallback = null
+    callback(REALTIME_SUBSCRIBE_STATES.SUBSCRIBED)
+  }
+
+  private _resetSubscribeState() {
+    this._postgresChangesSystemReady = false
+    this._subscribeCallback = null
+  }
+
+  private _shouldWaitForPostgresChangesSystem() {
+    return (
+      (this.bindings.postgres_changes?.length ?? 0) > 0 &&
+      (this.bindings.broadcast?.length ?? 0) === 0 &&
+      (this.bindings.presence?.length ?? 0) === 0
+    )
+  }
+
   /** @internal */
   private _getPayloadRecords(payload: any) {
     const records = {

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.108.2-beta.0'
+export const version = '2.108.2-beta.5'