Skip to main content
One idea at a time

A live connection carries notifications

Maya opens a project's tasks. Another member changes a task's status. Repeated polling could discover the change later. A persistent connection lets the server notify Maya while the page remains open.

WebSocket is a protocol for bidirectional messages over a connection. Socket.IO adds its own event protocol, connection management, and transport behavior. A Socket.IO client is not interchangeable with a plain WebSocket client.

Keep mutations on HTTP​

Taskboard updates a task through an authenticated HTTP request. The handler validates the body, checks workspace access, applies the database change, and records durable activity. A later notification tells connected clients that data changed.

Illustrative notification
{
  "kind": "realtime",
  "type": "task.updated",
  "workspaceId": "workspace-id",
  "projectId": "project-id",
  "eventId": "event-id",
  "taskId": "task-id",
  "version": 2
}

The event can tell the frontend to refetch the task or invalidate a query cache. Postgres remains the authoritative record. Keeping the mutation on HTTP also keeps one route for validation, CSRF protection, idempotency, and error responses.

The notification must follow commit. Emitting before commit can make Maya refetch data that does not yet exist, or announce a change that later rolls back. A durable event job allows a worker to deliver notifications after the transaction.

A connection is temporary state​

Browsers sleep, networks switch, and deploys close sockets. A connected indicator therefore means that the transport currently appears available, not that the client has received every historical update.

Socket.IO preserves message ordering on a connection but defaults to at-most-once delivery. Taskboard's durable notification attempts can still lead to missed or repeated client observations. The application needs its own recovery through HTTP. Socket.IO delivery guarantees.

The Socket.IO event name is task.changed; the payload's type identifies the domain change. The worker publishes through Postgres NOTIFY, and the API listens on the shared channel. Notifications can reach multiple listening API processes, but disconnected listeners miss them. Redis adapters, load-balancer routing, and multi-replica verification remain deployment extensions.

Read connection handling in Read api/src/realtime.ts and notification creation in Read api/src/tasks.ts.

Take away

Use live events to notify clients about committed state. Preserve an HTTP path to read and change authoritative data.

Does receiving an event prove that the client's entire task list is current?

No. The client may have missed another event or already have stale data. Refetching authoritative state is the recovery path.

Taskboard's reference browser client selects the WebSocket transport explicitly. Browser WebSocket handshakes include an Origin header that the server checks. A same-origin polling GET may omit that header, so this strict origin policy does not support that polling handshake.