From bbeb79017b78979c813747f63ca4960b7fd2337c Mon Sep 17 00:00:00 2001 From: Pedro Rodrigues Date: Wed, 28 Jan 2026 12:21:24 +0000 Subject: [PATCH] PR feedback --- skills/supabase/AGENTS.md | 3 +- .../references/realtime/broadcast-basics.md | 6 +- .../references/realtime/broadcast-database.md | 1 - .../references/realtime/patterns-cleanup.md | 2 - .../references/realtime/patterns-debugging.md | 78 +++++++++++++++++++ .../references/realtime/patterns-errors.md | 27 ++++--- .../references/realtime/setup-auth.md | 1 - 7 files changed, 94 insertions(+), 24 deletions(-) create mode 100644 skills/supabase/references/realtime/patterns-debugging.md diff --git a/skills/supabase/AGENTS.md b/skills/supabase/AGENTS.md index 9211248..b2f11a2 100644 --- a/skills/supabase/AGENTS.md +++ b/skills/supabase/AGENTS.md @@ -75,6 +75,7 @@ Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md **Implementation Patterns** (`patterns-`): - `references/realtime/patterns-cleanup.md` +- `references/realtime/patterns-debugging.md` - `references/realtime/patterns-errors.md` **Postgres Changes** (`postgres-`): @@ -89,4 +90,4 @@ Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md --- -*26 reference files across 11 categories* \ No newline at end of file +*27 reference files across 11 categories* \ No newline at end of file diff --git a/skills/supabase/references/realtime/broadcast-basics.md b/skills/supabase/references/realtime/broadcast-basics.md index c57d6ad..6fbd6c1 100644 --- a/skills/supabase/references/realtime/broadcast-basics.md +++ b/skills/supabase/references/realtime/broadcast-basics.md @@ -45,11 +45,7 @@ channel.send({ **Before subscribing or one-off (HTTP):** ```javascript -const { error } = await channel.send({ - type: 'broadcast', - event: 'message_created', - payload: { text: 'Hello!' }, -}) +await channel.httpSend('message_created', { text: 'Hello!' }) ``` ## Receive Own Messages diff --git a/skills/supabase/references/realtime/broadcast-database.md b/skills/supabase/references/realtime/broadcast-database.md index 2fc82b4..3d4c57d 100644 --- a/skills/supabase/references/realtime/broadcast-database.md +++ b/skills/supabase/references/realtime/broadcast-database.md @@ -41,7 +41,6 @@ create trigger messages_broadcast_trigger **Client subscription:** ```javascript -await supabase.realtime.setAuth() const channel = supabase .channel('room:123', { config: { private: true } }) .on('broadcast', { event: 'INSERT' }, (payload) => console.log('Insert:', payload)) diff --git a/skills/supabase/references/realtime/patterns-cleanup.md b/skills/supabase/references/realtime/patterns-cleanup.md index 3a1152a..664cd48 100644 --- a/skills/supabase/references/realtime/patterns-cleanup.md +++ b/skills/supabase/references/realtime/patterns-cleanup.md @@ -38,8 +38,6 @@ function ChatRoom({ roomId }) { }) channelRef.current = channel - supabase.realtime.setAuth() - channel .on('broadcast', { event: 'message_created' }, handleMessage) .subscribe() diff --git a/skills/supabase/references/realtime/patterns-debugging.md b/skills/supabase/references/realtime/patterns-debugging.md new file mode 100644 index 0000000..3763ed1 --- /dev/null +++ b/skills/supabase/references/realtime/patterns-debugging.md @@ -0,0 +1,78 @@ +--- +title: Debug Realtime Connections +impact: MEDIUM +impactDescription: Enables visibility into connection and message flow issues +tags: realtime, debugging, logging, troubleshooting +--- + +## Debug Realtime Connections + +Use logging to diagnose connection issues, message flow, and performance problems. + +## Client-Side Logging + +**Incorrect:** + +```javascript +// No logging - no visibility into issues +const supabase = createClient(url, key) +``` + +**Correct:** + +Enable client-side logging with a custom logger function: + +```javascript +const supabase = createClient(url, key, { + realtime: { + logger: (kind, msg, data) => { + console.log(`[${kind}] ${msg}`, data) + }, + }, +}) +``` + +Log message types: +- `push` - Messages sent to server +- `receive` - Messages received from server +- `transport` - Connection events (connect, disconnect, heartbeat) +- `error` - Error events +- `worker` - Web Worker events + +## Server-Side Log Level + +Configure Realtime server log verbosity via client params: + +```javascript +const supabase = createClient(url, key, { + realtime: { + params: { + log_level: 'info', // 'debug' | 'info' | 'warn' | 'error' + }, + }, +}) +``` + +This affects the verbosity of logs from the Realtime server, not client-side logs. + +## Filtering Logs for Debugging + +Filter logs to focus on specific events: + +```javascript +const supabase = createClient(url, key, { + realtime: { + logger: (kind, msg, data) => { + // Only log push/receive for subscription debugging + if (kind === 'push' || kind === 'receive') { + console.log(`[${kind}] ${msg}`, data) + } + }, + }, +}) +``` + +## Related + +- [patterns-errors.md](patterns-errors.md) +- [Docs](https://supabase.com/docs/guides/troubleshooting/realtime-debugging-with-logger) diff --git a/skills/supabase/references/realtime/patterns-errors.md b/skills/supabase/references/realtime/patterns-errors.md index 0db55ad..ba599fb 100644 --- a/skills/supabase/references/realtime/patterns-errors.md +++ b/skills/supabase/references/realtime/patterns-errors.md @@ -52,28 +52,32 @@ channel.subscribe((status, err) => { ## Automatic Reconnection -Supabase handles reconnection with exponential backoff. Configure timing: +Supabase handles reconnection automatically with exponential backoff. No manual re-subscribe is needed. + +## Client-Side Logging + +Enable client-side logging to debug connection issues: ```javascript const supabase = createClient(url, key, { realtime: { - params: { - log_level: 'info', // 'debug' | 'info' | 'warn' | 'error' + logger: (kind, msg, data) => { + console.log(`[${kind}] ${msg}`, data) }, }, }) ``` +Log message types include `push`, `receive`, `transport`, `error`, and `worker`. + ## Silent Disconnections in Background -WebSocket connections can disconnect when apps are backgrounded (mobile, inactive tabs). - -**Solution:** Monitor connection state and re-subscribe when needed: +WebSocket connections can disconnect when apps are backgrounded (mobile, inactive tabs). Supabase reconnects automatically. Re-track presence after reconnection if needed: ```javascript channel.subscribe((status) => { if (status === 'SUBSCRIBED') { - // Re-track presence if needed + // Re-track presence after reconnection channel.track({ user_id: userId, online_at: new Date().toISOString() }) } }) @@ -82,14 +86,9 @@ channel.subscribe((status) => { ## Authorization Errors Private channel authorization fails when: -- User not authenticated (`setAuth()` not called) +- User not authenticated - Missing RLS policies on `realtime.messages` -- Token expired (refresh before expiry) - -```javascript -// Refresh auth before token expires -await supabase.realtime.setAuth('fresh-jwt-token') -``` +- Token expired ## Related diff --git a/skills/supabase/references/realtime/setup-auth.md b/skills/supabase/references/realtime/setup-auth.md index c98d652..7412514 100644 --- a/skills/supabase/references/realtime/setup-auth.md +++ b/skills/supabase/references/realtime/setup-auth.md @@ -22,7 +22,6 @@ const channel = supabase.channel('room:123:messages') ```javascript // Private channel requires authentication -await supabase.realtime.setAuth() // Must call before subscribing const channel = supabase.channel('room:123:messages', { config: { private: true }, })