chore: debug-realtime tooling for SSE pipeline diagnostics (#20)

* chore(debug): add /debug-realtime page + bare SSE endpoint

Tijdelijke debug-tooling voor M8-acceptance op Vercel preview.

- app/api/debug/realtime-stream/route.ts — geen auth, geen filtering;
  dropt elke pg_notify-event op scrum4me_changes rauw door als SSE
- app/debug-realtime/page.tsx — open zonder login op de root, toont
  binnenkomende events in een simpele <table>

Doel: isoleren of de SSE + Postgres LISTEN-pipe op Vercel überhaupt
events laat zien, los van iron-session, productfilter of solo-store.
Als ook deze niets binnen krijgt: probleem zit in pg connection of
Vercel function lifecycle. Als deze wel events toont: probleem zit
hoger in de stack (filter, store, hook).

VERWIJDEREN voordat de PR uit draft gaat.

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

* chore(debug): extend /debug-realtime with stats, emit-button and filters

Bouwt de basale luister-tabel uit met diagnostische tooling om de
SSE+LISTEN-pipe stress-vrij te kunnen valideren.

Toegevoegd:
- POST /api/debug/emit-test-notify — vuurt een handmatige pg_notify
  op scrum4me_changes met een synthetic payload (debug:true) zonder
  een echte DB-UPDATE te doen. Isoleert de SSE-route van Prisma/triggers.
- DebugRealtimeClient: stats-grid (status, reconnects, total events,
  since last event met >30s rood-warning, largest gap, first-event-
  time), emit-button, reset-stats, filters op type en entity
  (incl. "debug only").
- Type/entity kolom in de tabel met kleuring per type.

Geen impact op productie- of solo-flow. Tijdelijke testtooling;
verwijderen wanneer we deze pagina niet meer nodig hebben.

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

* chore(debug): add Layer 2 — mini Zustand-store + dispatch toggles

Test of SSE-event → store → render-pipeline werkt buiten de Solo
Paneel context. Mirrort het patroon van solo-store maar minimaal.

- debug-store.ts: kleine Zustand-store met tasks + applyEvent +
  applyCount/skipCount-tellers
- store-panel.tsx: rendert store-state in een tabel met statuskleuring
- client.tsx: drie layer-toggles (dispatch / flushSync / startView-
  Transition) + lift dispatch in onmessage. Zo kunnen we elke
  combinatie isoleren

Bevestigd: alle drie de toggles werken op het bare /debug-realtime
endpoint. Volgende laag is Server Action revalidation.

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-04-29 20:35:40 +02:00 committed by GitHub
parent 868a53c2ed
commit c6fdd45d98
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 868 additions and 0 deletions

View file

@ -0,0 +1,490 @@
'use client'
import { useEffect, useMemo, useRef, useState } from 'react'
import { flushSync } from 'react-dom'
import { useDebugStore, type DebugRealtimeEvent } from './debug-store'
import { StorePanel } from './store-panel'
type RowType = 'ready' | 'message' | 'error' | 'open' | 'close'
interface Row {
receivedAt: number
type: RowType
raw: string
parsed?: Record<string, unknown>
}
interface Stats {
reconnects: number
totalEvents: number
firstEventAt: number | null
lastEventAt: number | null
largestGapMs: number
emitInFlight: boolean
lastEmitResult: string | null
}
const MAX_ROWS = 500
const HEARTBEAT_WARN_MS = 30_000
export function DebugRealtimeClient() {
const [rows, setRows] = useState<Row[]>([])
const [status, setStatus] = useState<'connecting' | 'open' | 'closed' | 'error'>('connecting')
const [stats, setStats] = useState<Stats>({
reconnects: 0,
totalEvents: 0,
firstEventAt: null,
lastEventAt: null,
largestGapMs: 0,
emitInFlight: false,
lastEmitResult: null,
})
const [filterType, setFilterType] = useState<'all' | RowType>('all')
const [filterEntity, setFilterEntity] = useState<'all' | 'task' | 'story' | 'debug'>('all')
const [tickNow, setTickNow] = useState(() => Date.now())
// Layer-toggles — elke combinatie isoleert een potentiële bron van bugs.
// - dispatchToStore: voert applyEvent uit op een mini Zustand-store
// - useFlushSync: forceert React om synchroon te renderen tijdens dispatch
// - useViewTransition: wrap dispatch in document.startViewTransition
const [dispatchToStore, setDispatchToStore] = useState(true)
const [useFlushSync, setUseFlushSync] = useState(false)
const [useViewTransition, setUseViewTransition] = useState(false)
const dispatchToStoreRef = useRef(dispatchToStore)
const useFlushSyncRef = useRef(useFlushSync)
const useViewTransitionRef = useRef(useViewTransition)
useEffect(() => { dispatchToStoreRef.current = dispatchToStore }, [dispatchToStore])
useEffect(() => { useFlushSyncRef.current = useFlushSync }, [useFlushSync])
useEffect(() => { useViewTransitionRef.current = useViewTransition }, [useViewTransition])
const sourceRef = useRef<EventSource | null>(null)
const lastEventTimeRef = useRef<number | null>(null)
// Tick every second om "since last event"-counter levend te houden
useEffect(() => {
const t = setInterval(() => setTickNow(Date.now()), 1000)
return () => clearInterval(t)
}, [])
useEffect(() => {
const append = (row: Row) => {
setRows((prev) => [row, ...prev].slice(0, MAX_ROWS))
lastEventTimeRef.current = row.receivedAt
setStats((s) => {
const prevLast = s.lastEventAt
const gap = prevLast ? row.receivedAt - prevLast : 0
return {
...s,
totalEvents: s.totalEvents + 1,
firstEventAt: s.firstEventAt ?? row.receivedAt,
lastEventAt: row.receivedAt,
largestGapMs: Math.max(s.largestGapMs, gap),
}
})
}
const open = () => {
const source = new EventSource('/api/debug/realtime-stream')
sourceRef.current = source
append({ receivedAt: Date.now(), type: 'open', raw: '(EventSource opening)' })
setStats((s) => ({ ...s, reconnects: s.reconnects + 1 }))
setStatus('connecting')
source.addEventListener('ready', (e) => {
setStatus('open')
const data = (e as MessageEvent).data ?? ''
const parsed = safeParse(data)
append({ receivedAt: Date.now(), type: 'ready', raw: data, parsed })
})
source.addEventListener('error', (e) => {
setStatus('error')
const data = (e as MessageEvent).data ?? '(no data)'
append({ receivedAt: Date.now(), type: 'error', raw: data })
})
source.onmessage = (e) => {
const parsed = safeParse(e.data ?? '')
append({ receivedAt: Date.now(), type: 'message', raw: e.data ?? '', parsed })
// Dispatch naar de mini Zustand-store, optioneel met flushSync
// en/of startViewTransition om de echte solo-flow te mimeken.
if (dispatchToStoreRef.current && parsed) {
const dispatch = () =>
useDebugStore.getState().applyEvent(parsed as DebugRealtimeEvent)
const wrapWithFlush = useFlushSyncRef.current
? () => flushSync(dispatch)
: dispatch
if (
useViewTransitionRef.current &&
typeof document !== 'undefined' &&
typeof (document as Document & { startViewTransition?: unknown })
.startViewTransition === 'function'
) {
;(
document as Document & {
startViewTransition: (cb: () => void) => unknown
}
).startViewTransition(wrapWithFlush)
} else {
wrapWithFlush()
}
}
}
source.onerror = () => {
setStatus('error')
append({ receivedAt: Date.now(), type: 'close', raw: '(EventSource error/close)' })
}
}
open()
return () => {
sourceRef.current?.close()
sourceRef.current = null
}
}, [])
async function emitTestEvent() {
setStats((s) => ({ ...s, emitInFlight: true, lastEmitResult: null }))
try {
const res = await fetch('/api/debug/emit-test-notify', { method: 'POST' })
const json = (await res.json()) as { ok?: boolean; error?: string }
setStats((s) => ({
...s,
emitInFlight: false,
lastEmitResult: json.ok ? 'sent ✓' : `failed: ${json.error ?? 'unknown'}`,
}))
} catch (err) {
setStats((s) => ({
...s,
emitInFlight: false,
lastEmitResult: `failed: ${err instanceof Error ? err.message : String(err)}`,
}))
}
}
function reset() {
setRows([])
setStats({
reconnects: 0,
totalEvents: 0,
firstEventAt: null,
lastEventAt: null,
largestGapMs: 0,
emitInFlight: false,
lastEmitResult: null,
})
lastEventTimeRef.current = null
}
const filteredRows = useMemo(() => {
return rows.filter((row) => {
if (filterType !== 'all' && row.type !== filterType) return false
if (filterEntity !== 'all') {
const entity = (row.parsed?.entity as string | undefined) ?? null
if (filterEntity === 'debug') {
if (!row.parsed?.debug) return false
} else {
if (entity !== filterEntity) return false
}
}
return true
})
}, [rows, filterType, filterEntity])
const sinceLastEvent = lastEventTimeRef.current
? tickNow - lastEventTimeRef.current
: null
return (
<div style={{ marginTop: 16 }}>
<ControlBar
status={status}
stats={stats}
sinceLastEvent={sinceLastEvent}
filterType={filterType}
setFilterType={setFilterType}
filterEntity={filterEntity}
setFilterEntity={setFilterEntity}
onEmit={emitTestEvent}
onReset={reset}
/>
<LayerToggles
dispatchToStore={dispatchToStore}
setDispatchToStore={setDispatchToStore}
useFlushSync={useFlushSync}
setUseFlushSync={setUseFlushSync}
useViewTransition={useViewTransition}
setUseViewTransition={setUseViewTransition}
/>
{dispatchToStore && <StorePanel />}
<table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 12, marginTop: 12 }}>
<thead>
<tr style={{ background: '#f0f0f0', textAlign: 'left' }}>
<th style={{ padding: 6, border: '1px solid #ddd', width: 220 }}>received_at</th>
<th style={{ padding: 6, border: '1px solid #ddd', width: 100 }}>type</th>
<th style={{ padding: 6, border: '1px solid #ddd', width: 140 }}>entity / op</th>
<th style={{ padding: 6, border: '1px solid #ddd' }}>payload</th>
</tr>
</thead>
<tbody>
{filteredRows.length === 0 ? (
<tr>
<td colSpan={4} style={{ padding: 12, textAlign: 'center', color: '#888' }}>
Wachten op events trigger een mutatie via UI / script of klik &quot;emit test event&quot;.
</td>
</tr>
) : (
filteredRows.map((row, idx) => (
<tr
key={`${row.receivedAt}-${idx}`}
style={{ background: row.type === 'message' ? 'transparent' : '#fafafa' }}
>
<td style={{ padding: 6, border: '1px solid #ddd', whiteSpace: 'nowrap' }}>
{new Date(row.receivedAt).toISOString()}
</td>
<td style={{ padding: 6, border: '1px solid #ddd', color: typeColor(row.type) }}>
{row.type}
</td>
<td style={{ padding: 6, border: '1px solid #ddd', whiteSpace: 'nowrap' }}>
{row.parsed?.entity ? (
<>
{row.parsed.entity as string}
{row.parsed.op ? ` / ${row.parsed.op as string}` : ''}
{row.parsed.debug ? ' [debug]' : ''}
</>
) : (
'—'
)}
</td>
<td style={{ padding: 6, border: '1px solid #ddd', wordBreak: 'break-all' }}>
<code>{row.raw}</code>
</td>
</tr>
))
)}
</tbody>
</table>
</div>
)
}
function ControlBar({
status,
stats,
sinceLastEvent,
filterType,
setFilterType,
filterEntity,
setFilterEntity,
onEmit,
onReset,
}: {
status: 'connecting' | 'open' | 'closed' | 'error'
stats: Stats
sinceLastEvent: number | null
filterType: 'all' | RowType
setFilterType: (t: 'all' | RowType) => void
filterEntity: 'all' | 'task' | 'story' | 'debug'
setFilterEntity: (e: 'all' | 'task' | 'story' | 'debug') => void
onEmit: () => void
onReset: () => void
}) {
const heartbeatStale = sinceLastEvent !== null && sinceLastEvent > HEARTBEAT_WARN_MS
return (
<div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
<div
style={{
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))',
gap: 8,
padding: 12,
background: '#f7f7f7',
border: '1px solid #ddd',
borderRadius: 4,
}}
>
<Stat label="status" value={status} color={statusColor(status)} />
<Stat label="reconnects" value={String(stats.reconnects)} />
<Stat label="total events" value={String(stats.totalEvents)} />
<Stat
label="since last event"
value={sinceLastEvent === null ? '—' : `${(sinceLastEvent / 1000).toFixed(1)}s`}
color={heartbeatStale ? 'red' : undefined}
/>
<Stat
label="largest gap"
value={
stats.largestGapMs > 0
? `${(stats.largestGapMs / 1000).toFixed(1)}s`
: '—'
}
/>
<Stat
label="first event"
value={stats.firstEventAt ? new Date(stats.firstEventAt).toLocaleTimeString() : '—'}
/>
</div>
<div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>
<button
onClick={onEmit}
disabled={stats.emitInFlight}
style={{
padding: '6px 12px',
background: '#0a0',
color: 'white',
border: 'none',
borderRadius: 4,
cursor: stats.emitInFlight ? 'wait' : 'pointer',
opacity: stats.emitInFlight ? 0.6 : 1,
}}
>
{stats.emitInFlight ? 'sending…' : 'emit test event'}
</button>
{stats.lastEmitResult && (
<span style={{ fontSize: 12, color: '#666' }}>{stats.lastEmitResult}</span>
)}
<button
onClick={onReset}
style={{
padding: '6px 12px',
background: '#eee',
border: '1px solid #ccc',
borderRadius: 4,
cursor: 'pointer',
}}
>
reset stats
</button>
<span style={{ marginLeft: 12, fontSize: 12, color: '#666' }}>filter:</span>
<select
value={filterType}
onChange={(e) => setFilterType(e.target.value as 'all' | RowType)}
style={{ fontSize: 12, padding: 4 }}
>
<option value="all">all types</option>
<option value="ready">ready</option>
<option value="message">message</option>
<option value="error">error</option>
<option value="open">open</option>
<option value="close">close</option>
</select>
<select
value={filterEntity}
onChange={(e) => setFilterEntity(e.target.value as 'all' | 'task' | 'story' | 'debug')}
style={{ fontSize: 12, padding: 4 }}
>
<option value="all">all entities</option>
<option value="task">task</option>
<option value="story">story</option>
<option value="debug">debug only</option>
</select>
</div>
</div>
)
}
function LayerToggles({
dispatchToStore,
setDispatchToStore,
useFlushSync,
setUseFlushSync,
useViewTransition,
setUseViewTransition,
}: {
dispatchToStore: boolean
setDispatchToStore: (v: boolean) => void
useFlushSync: boolean
setUseFlushSync: (v: boolean) => void
useViewTransition: boolean
setUseViewTransition: (v: boolean) => void
}) {
return (
<div
style={{
marginTop: 12,
padding: 8,
background: '#fff8e1',
border: '1px solid #ffe0a0',
borderRadius: 4,
fontSize: 12,
}}
>
<strong style={{ marginRight: 12 }}>Layers:</strong>
<label style={{ marginRight: 16 }}>
<input
type="checkbox"
checked={dispatchToStore}
onChange={(e) => setDispatchToStore(e.target.checked)}
/>{' '}
dispatch naar mini-store
</label>
<label style={{ marginRight: 16 }}>
<input
type="checkbox"
checked={useFlushSync}
onChange={(e) => setUseFlushSync(e.target.checked)}
disabled={!dispatchToStore}
/>{' '}
wrap in flushSync
</label>
<label>
<input
type="checkbox"
checked={useViewTransition}
onChange={(e) => setUseViewTransition(e.target.checked)}
disabled={!dispatchToStore}
/>{' '}
wrap in startViewTransition
</label>
</div>
)
}
function Stat({ label, value, color }: { label: string; value: string; color?: string }) {
return (
<div style={{ display: 'flex', flexDirection: 'column' }}>
<span style={{ fontSize: 11, color: '#888', textTransform: 'uppercase' }}>{label}</span>
<span style={{ fontSize: 14, fontWeight: 'bold', color: color ?? 'inherit' }}>{value}</span>
</div>
)
}
function statusColor(status: 'connecting' | 'open' | 'closed' | 'error') {
switch (status) {
case 'open':
return 'green'
case 'error':
return 'red'
case 'closed':
return 'gray'
default:
return 'orange'
}
}
function typeColor(type: RowType) {
switch (type) {
case 'message':
return '#0070cc'
case 'ready':
return 'green'
case 'error':
return 'red'
case 'open':
return '#888'
case 'close':
return '#888'
}
}
function safeParse(raw: string): Record<string, unknown> | undefined {
try {
return JSON.parse(raw) as Record<string, unknown>
} catch {
return undefined
}
}

View file

@ -0,0 +1,71 @@
// Mini Zustand-store voor de debug-pagina. Mirrort het patroon van
// stores/solo-store.ts maar dan minimaal: alleen tasks-record + applyEvent.
// Doel: testen of de SSE-event → store → component-render keten werkt
// zonder de complexiteit van de echte Solo Paneel.
import { create } from 'zustand'
export interface DebugTask {
id: string
status: string
title: string
story_id: string
updated_at: string
}
export interface DebugRealtimeEvent {
op: 'I' | 'U' | 'D'
entity: 'task' | 'story'
id: string
story_id?: string
task_status?: string
task_title?: string
debug?: boolean
emitted_at?: string
[key: string]: unknown
}
interface DebugStore {
tasks: Record<string, DebugTask>
applyCount: number
skipCount: number
applyEvent: (event: DebugRealtimeEvent) => void
reset: () => void
}
export const useDebugStore = create<DebugStore>((set, get) => ({
tasks: {},
applyCount: 0,
skipCount: 0,
applyEvent: (event) => {
if (event.entity !== 'task') {
set((s) => ({ skipCount: s.skipCount + 1 }))
return
}
if (event.op === 'D') {
set((s) => {
const next = { ...s.tasks }
delete next[event.id]
return { tasks: next, applyCount: s.applyCount + 1 }
})
return
}
// INSERT/UPDATE — schrijf altijd, ongeacht of de task al bestond
set((s) => ({
tasks: {
...s.tasks,
[event.id]: {
id: event.id,
status: event.task_status ?? get().tasks[event.id]?.status ?? '?',
title: event.task_title ?? get().tasks[event.id]?.title ?? '(no title)',
story_id: event.story_id ?? get().tasks[event.id]?.story_id ?? '?',
updated_at: new Date().toISOString(),
},
},
applyCount: s.applyCount + 1,
}))
},
reset: () => set({ tasks: {}, applyCount: 0, skipCount: 0 }),
}))

View file

@ -0,0 +1,23 @@
// TIJDELIJKE debug-pagina voor M8-acceptance.
// Geen auth, geen styling — toont alle inkomende pg_notify-events op
// `scrum4me_changes` in een tabel zodat we kunnen zien of de SSE + LISTEN-
// pipe überhaupt events doorstroomt op Vercel.
//
// VERWIJDEREN VOOR M8 OUT-OF-DRAFT.
import { DebugRealtimeClient } from './client'
export const dynamic = 'force-dynamic'
export default function DebugRealtimePage() {
return (
<div style={{ fontFamily: 'monospace', padding: 16 }}>
<h1 style={{ fontSize: 18, fontWeight: 'bold' }}>Realtime debug scrum4me_changes</h1>
<p style={{ fontSize: 13, color: '#666' }}>
Live SSE-stream rechtstreeks van Postgres LISTEN op channel{' '}
<code>scrum4me_changes</code>. Geen auth, geen filtering. Verwijderen na M8 acceptance.
</p>
<DebugRealtimeClient />
</div>
)
}

View file

@ -0,0 +1,111 @@
'use client'
import { useDebugStore } from './debug-store'
export function StorePanel() {
const tasks = useDebugStore((s) => s.tasks)
const applyCount = useDebugStore((s) => s.applyCount)
const skipCount = useDebugStore((s) => s.skipCount)
const reset = useDebugStore((s) => s.reset)
const taskList = Object.values(tasks)
return (
<div style={{ marginTop: 16 }}>
<div
style={{
display: 'flex',
alignItems: 'center',
gap: 12,
padding: 8,
background: '#eef',
border: '1px solid #cce',
borderRadius: 4,
fontSize: 12,
}}
>
<strong>Store layer:</strong>
<span>
applyCount: <code>{applyCount}</code>
</span>
<span>
skipCount: <code>{skipCount}</code>
</span>
<span>
taskCount: <code>{taskList.length}</code>
</span>
<button
onClick={reset}
style={{
marginLeft: 'auto',
padding: '4px 10px',
background: '#eee',
border: '1px solid #ccc',
borderRadius: 4,
fontSize: 12,
cursor: 'pointer',
}}
>
reset store
</button>
</div>
<table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 12, marginTop: 8 }}>
<thead>
<tr style={{ background: '#f0f0f0', textAlign: 'left' }}>
<th style={{ padding: 6, border: '1px solid #ddd', width: 220 }}>id</th>
<th style={{ padding: 6, border: '1px solid #ddd', width: 100 }}>status</th>
<th style={{ padding: 6, border: '1px solid #ddd' }}>title</th>
<th style={{ padding: 6, border: '1px solid #ddd', width: 220 }}>updated_at (lokaal)</th>
</tr>
</thead>
<tbody>
{taskList.length === 0 ? (
<tr>
<td colSpan={4} style={{ padding: 8, textAlign: 'center', color: '#888' }}>
Store is leeg. Trigger een event en kijk of de tabel hier vult.
</td>
</tr>
) : (
taskList.map((t) => (
<tr key={t.id}>
<td style={{ padding: 6, border: '1px solid #ddd' }}>
<code>{t.id}</code>
</td>
<td
style={{
padding: 6,
border: '1px solid #ddd',
fontWeight: 'bold',
color: statusColor(t.status),
}}
>
{t.status}
</td>
<td style={{ padding: 6, border: '1px solid #ddd' }}>{t.title}</td>
<td style={{ padding: 6, border: '1px solid #ddd', whiteSpace: 'nowrap' }}>
{t.updated_at}
</td>
</tr>
))
)}
</tbody>
</table>
</div>
)
}
function statusColor(status: string) {
switch (status) {
case 'TO_DO':
return '#888'
case 'IN_PROGRESS':
return '#0070cc'
case 'REVIEW':
return '#cc7a00'
case 'DONE':
return 'green'
default:
return 'inherit'
}
}