fix(realtime): force-destroy pg socket on cleanup timeout (SSE leak) (#44)

Three SSE-routes (solo, backlog, notifications) each create a long-
running pg.Client that LISTENs on scrum4me_changes. On abrupt close
(Fast Refresh, browser refresh, Vercel function recycle) the
pgClient.end()-await sometimes hangs silently, leaving the underlying
socket connected to Postgres. The connection stays in 'idle' on Neon's
side and after ~10-20 reconnects the connection-pool fills up — new
SSE connects fail with ERR_INCOMPLETE_CHUNKED_ENCODING in the browser.

Fix: shared `closePgClientSafely` helper that races client.end()
against a 2 s timeout; on timeout it force-destroys the underlying
socket so the OS releases the FD and Postgres notices the disconnect.

Validated by direct DB inspection: 18 stale 'idle LISTEN'-connections
were piled up before the fix; after manual pg_terminate_backend cleanup
the SSE-stream stabilised. This change makes the pile-up impossible
going forward.

- new lib/realtime/pg-client-cleanup.ts
- 3 routes use the helper instead of bare `await pgClient.end()`
- 3 unit tests for the helper (timely-end, hang-falls-back-to-destroy,
  end-rejection-is-swallowed)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/api/realtime/backlog/route.ts

@@ -6,6 +6,7 @@ import { NextRequest } from 'next/server'
 import { Client } from 'pg'
 import { getSession } from '@/lib/auth'
 import { getAccessibleProduct } from '@/lib/product-access'
+import { closePgClientSafely } from '@/lib/realtime/pg-client-cleanup'
 
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
@@ -68,7 +69,7 @@ export async function GET(request: NextRequest) {
         closed = true
         if (heartbeatTimer) clearInterval(heartbeatTimer)
         if (hardCloseTimer) clearTimeout(hardCloseTimer)
-        try { await pgClient.end() } catch { /* ignore */ }
+        await closePgClientSafely(pgClient, 'realtime/backlog')
         try { controller.close() } catch { /* already closed */ }
         if (process.env.NODE_ENV !== 'production') {
           console.log(`[realtime/backlog] closed: ${reason}`)

app/api/realtime/notifications/route.ts

@@ -16,6 +16,7 @@ import { Client } from 'pg'
 import { getSession } from '@/lib/auth'
 import { prisma } from '@/lib/prisma'
 import { productAccessFilter } from '@/lib/product-access'
+import { closePgClientSafely } from '@/lib/realtime/pg-client-cleanup'
 
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
@@ -83,11 +84,7 @@ export async function GET(request: NextRequest) {
         closed = true
         if (heartbeatTimer) clearInterval(heartbeatTimer)
         if (hardCloseTimer) clearTimeout(hardCloseTimer)
-        try {
-          await pgClient.end()
-        } catch {
-          // ignore
-        }
+        await closePgClientSafely(pgClient, 'realtime/notifications')
         try {
           controller.close()
         } catch {

app/api/realtime/solo/route.ts

@@ -14,6 +14,7 @@ import { NextRequest } from 'next/server'
 import { Client } from 'pg'
 import { getSession } from '@/lib/auth'
 import { getAccessibleProduct } from '@/lib/product-access'
+import { closePgClientSafely } from '@/lib/realtime/pg-client-cleanup'
 
 export const runtime = 'nodejs'
 export const dynamic = 'force-dynamic'
@@ -145,11 +146,7 @@ export async function GET(request: NextRequest) {
         closed = true
         if (heartbeatTimer) clearInterval(heartbeatTimer)
         if (hardCloseTimer) clearTimeout(hardCloseTimer)
-        try {
-          await pgClient.end()
-        } catch {
-          // ignore
-        }
+        await closePgClientSafely(pgClient, 'realtime/solo')
         try {
           controller.close()
         } catch {