98 lines
5.0 KiB
Markdown
98 lines
5.0 KiB
Markdown
# Synced attention: clearing on one device clears everywhere
|
|
|
|
Operator request: "when I clear notifications, it should clear in all places,
|
|
not only on the web and then I have to clear again on mobile."
|
|
|
|
## What is shared
|
|
|
|
- **Needs-you dismissals.** Dismiss and Clear all in the Needs-you sheet. Each
|
|
entry's identity is `{runId}:{Decision|Failed}` (`attentionKey`).
|
|
- **Chat New badges.** Opening a chat, and content arriving in the chat this
|
|
device has open, records a per-session `chat_seen` watermark in epoch ms.
|
|
|
|
ntfy notifications already shown on a phone cannot be retracted (see
|
|
`docs/ntfy.md`, "Clearing notifications across devices").
|
|
|
|
## Protocol (server, `internal/protocol/attention_acks.go`)
|
|
|
|
| Direction | Envelope |
|
|
| --- | --- |
|
|
| read | `{"type":"attention_acks"}` → `{"type":"attention_acks","attention_acks":{"dismissed":[…],"chat_seen":{…}}}` (the whole set) |
|
|
| add | `{"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}}` → same reply (the whole set) |
|
|
| push | `{"type":"attention_acks_changed","attention_acks":{…}}`: only what changed, sent to every *other* connection |
|
|
|
|
The set only grows: dismissals are added and watermarks only advance. That makes
|
|
merging a union/max that is safe to apply in any order or twice. Invalid
|
|
identities, invalid session ids, non-positive times, empty acks and acks with
|
|
more than 500 items are refused with `error`, and nothing is written. Dismissals
|
|
of unknown runs and watermarks for sessions that are not operator sessions are
|
|
skipped silently. A stored watermark is
|
|
`max(old, client value, operator_sessions.last_used_at)`.
|
|
|
|
Storage: two additive SQLite tables, `attention_dismissals(key, run_id,
|
|
dismissed_at)` and `chat_seen_watermarks(session_id, seen_at, acked_at)`,
|
|
created in `Store.Open`. Each ack prunes rows for deleted runs and sessions, and
|
|
rows older than 30 days (`AttentionAckRetention`).
|
|
|
|
**Clear all** sends the identities the sheet showed (its snapshot), not a
|
|
"cleared up to time T" marker. A time marker would hide a run created before T
|
|
that starts waiting on a person after T. The snapshot keeps the existing
|
|
"entries that arrive later stay" rule, and the request is bounded to 500
|
|
identities per batch.
|
|
|
|
## App
|
|
|
|
- `features/attention/domain/attention_acks.dart`: the value type (merge,
|
|
`without`, encode/decode, bounded batches).
|
|
- `features/attention/runtime/attention_ack_sync.dart` (`AttentionAckSync`): one
|
|
per app/gateway, bound with `bindAttentionAckSync`. It applies local
|
|
acknowledgements immediately and queues them persistently
|
|
(`attention_ack_queue.dart`, SharedPreferences, server-scoped). On every
|
|
connected transition it flushes the queue and reads the set. It also applies
|
|
pushed deltas. It sends through the socket's send-only path, so the
|
|
connect-time read never queues ahead of the first screen's request. A
|
|
refusal drops the batch. An older server that answers `pong` keeps the queue
|
|
and turns syncing off until the next connection, so the local state still
|
|
applies.
|
|
- `AttentionController(sync:)`: Dismiss and Clear all also acknowledge. Shared
|
|
identities are unioned into the local set and cached in the existing local
|
|
store, which acts as the offline copy.
|
|
- `ChatSessionsController`: looks up the bound sync. Opening a chat stores and
|
|
acknowledges `max(row updated_at, now)`. A shared watermark newer than this
|
|
device's own clears the badge and raises the local watermark, so the same
|
|
acknowledgement cannot later clear newer content. Content arriving in the open
|
|
chat is acknowledged after 1.5 s of quiet.
|
|
- `PipelinesApp` creates and binds the sync, loads the queue, and calls
|
|
`connected()` on each connection epoch.
|
|
|
|
The Needs-you sheet layout was not touched.
|
|
|
|
## Known limits
|
|
|
|
- The chat watermark compares a device clock with server times, so large clock
|
|
skew can mis-order a badge.
|
|
- An acknowledgement queued offline for a long time can clear a badge for
|
|
content that arrived between the offline open and the reconnect.
|
|
- Local dismissals made before this change are not uploaded. Only new
|
|
dismissals are shared.
|
|
|
|
## Tests
|
|
|
|
- Go: `internal/pipeline/attention_acks_test.go` (persist/reopen, advance-only,
|
|
unknown skipped, registry lift, prune deleted/expired, malformed refused),
|
|
`internal/server/attention_acks_test.go` (two websocket clients: push to the
|
|
other, no push for malformed/no-op acks), and
|
|
`internal/protocol/attention_acks_test.go`.
|
|
- Flutter: `test/features/attention/runtime/attention_ack_sync_test.dart` (two
|
|
devices: dismiss, Clear all, late connect, offline queue, restart, refusal,
|
|
legacy server, send-only path) and
|
|
`test/features/chat/ui/sessions/chat_seen_sync_test.dart` (open clears
|
|
everywhere, an earlier ack never clears later content, open-chat content, and
|
|
offline open synced on reconnect).
|
|
|
|
## Deployment
|
|
|
|
The server needs a rebuild and restart to serve the new requests; the tables are
|
|
created on open. The rebuilt web app and APK also need publishing. Until the
|
|
server is upgraded, the app keeps working with its local state and its queue.
|