fix(api-websockets): deliver server->client pushes on SQL deployments (recency filter)

[adrians5j]

Summary

On SQL-backed (self-hosted / server flavour) deployments, SendToIdentity silently matched zero connections, so server→client WebSocket pushes never arrived — even though the connection was registered under the correct identity. Symptom: file-manager AI image enrichment completes and updates the file, but no "Image enriched" notification appears in Admin.

Root cause

ListConnectionsUseCase filters out stale connections with a lexicographic string comparison:

const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString();
connections = connections.filter(c => c.connectedOn >= threeHoursAgo);

connectedOn is declared string and is written as a UTC ISO string, but it is stored in a SQL datetime column. On read, the injected knex/driver hands it back in a shape that does not compare against an ISO string. On the reporter's SQLite setup it came back as a Date object (coerces to "Wed Aug 04 2026 …", which sorts below "2026-…"); other drivers/configs return a T/Z-less "2026-08-04 17:02:06" (space 0x20 sorts before T 0x54). Either way every live connection reads as older than the cutoff and is dropped → SendToIdentity sends to nobody, throws nothing, task still reports success.

Fix in this PR (unblocks the symptom)

Compare by parsed UTC epoch instead of raw string, handling both Date and string forms (normalizing the space form back to UTC — safe, since the stored wall-clock is UTC). Extracted into connectedOnToEpoch / isRecentConnection helpers + a named window constant.

⚠️ This is a localized patch — two deeper issues remain (please read)

This PR fixes the one call site so pushes work again, but it papers over the actual root cause. Two follow-ups worth doing properly:

A. connectedOn type contract is violated (blast radius beyond this filter)

connectedOn is typed string everywhere (ConnectionRegistry abstractions, ConnectionRow), but at runtime it's whatever the injected knex returns for a datetime column (a Date on the reporter's setup). The SQL adapter's toData() passes the raw driver value straight through, so the lie propagates to every consumer — notably WebsocketsGraphQLFactory exposes connectedOn: DateTime! in the Admin GraphQL, where a Date vs an ISO string can serialize inconsistently.

• Proper fix: normalize connectedOn/lastSeen to canonical ISO once, at the SQL boundary (in WebsocketsConnectionRegistry.toData() in @webiny/api-websockets-sql). Then the string type is honest, GraphQL is consistent, and the recency comparison could even go back to a plain string compare. The framework receives an injected knex it doesn't control, so normalizing at this boundary is the correct layer.

B. Recency filter keys off the wrong field (engine-independent correctness bug)

ListConnectionsUseCase judges "recent" by connectedOn (first-connect time), but listStale (in the SQL registry) correctly judges staleness by lastSeen (the heartbeat timestamp). So an Admin session open > 3 hours — alive and actively heartbeating, lastSeen fresh — has an old connectedOn and gets filtered out, silently losing all pushes. The heartbeat/lastSeen machinery exists precisely for liveness; the send path ignores it.

• Proper fix: filter on lastSeen (fall back to connectedOn when never heard from). Independent of the date-format issue above.

Recommended end state

Do A (boundary normalization in toData()) + B (filter on lastSeen), then the epoch helper in this PR can be simplified or removed. Happy to redo the PR that way if preferred over the current patch.

Not a WS-wiring regression

The recent 6.5.0 merges did not revert any WebSocket source — the wiring (register → sql registry → SendToIdentity → transport → admin handler) is intact. This is a latent bug in a new code path. On AWS/DynamoDB it never bites: ddb stores connectedOn as a plain string attribute that round-trips as ISO, so the original string compare is valid there.

Verification

Reproduced end-to-end on a self-hosted SQL project: upload image → AI enrichment task → SendToIdentity now matches the live connections → "Image enriched" notification renders in Admin. Traced with temporary logging that showed the sql registry returning matched=N while SendToIdentity saw matchedConnections=0, isolating the drop to this recency filter.

🤖 Generated with Claude Code