Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
realtime.md · 4.4 KB · 101 lines

Realtime — The Change Log and Live Surfaces

Every generative surface — every list, table, board, detail page, comment thread, and attachment list — subscribes to the change log and re-renders when a record it can see changes, from any tab, user, or agent. This falls out of one small websocket contract with a deliberate rule: the wire carries a signal, never the record body.

sequenceDiagram
    participant Writer as any write (web/API/agent)
    participant Server
    participant Hub as realtime hub
    participant Client as a live surface

    Client->>Server: connect /ws (session), subscribe [collections]
    Server->>Server: may this subject READ each collection?
    Server-->>Client: {type: subscribed, collections}
    Writer->>Server: create/update/delete a record
    Server->>Hub: publish {collection, record_id, action}
    Hub->>Hub: per subscriber, re-run the READ decision
    Hub-->>Client: {type: record, collection, record_id, action}
    Client->>Server: refetch through the normal permission-enforced API
    Client->>Client: re-render

Transport

GET /ws (upgraded to a websocket). The connection is authenticated — a session cookie or bearer token — and anonymous connections are refused (1008). Realtime is behind a flag; when off, surfaces fall back to polling.

Client protocol

Messages are JSON. On accept, the server sends {"type": "welcome", "user": ...}. Then:

Client sendsServer replies
{"action": "subscribe", "collections": ["tasks", "notes"]}{"type": "subscribed", "collections": [...]} — only the collections the subject may read are kept
{"action": "unsubscribe", "collections": [...]}{"type": "subscribed", "collections": [...]}
{"action": "ping"}{"type": "pong"}

Subscriptions are capped per connection, and each collection name is validated.

In the browser this is wrapped as one helper, window.dbbasicSubscribe(collection, handler) (served by the nav object): it opens the socket once, subscribes on demand, reconnects with backoff, and runs a ~20-second poll as a fallback for missed events and multi-worker deployments. A page never talks to /ws directly — it calls dbbasicSubscribe and re-renders in the handler.

The event

A change pushes exactly:

{ "type": "record", "collection": "tasks", "record_id": "…", "action": "update" }

action is create / update / delete. No field values travel — only which record changed. The client reacts by refetching through the ordinary API, which re-applies the full permission policy and field redaction. So a live surface can never show a field the API wouldn't have served.

Permission filtering — twice

Realtime is inside the permission engine, not beside it:

  1. On subscribe — a subject may follow a collection only if it may READ

it (_ws_can_subscribe runs the same check a GET would).

  1. On publish — for each subscriber, the server re-runs the READ decision

against the changed record, so a row-filtered subscriber only hears about rows its filter would let it see. If the policy can't be loaded to filter safely, nothing is pushed.

Combined with the signal-only payload, this means the change log leaks neither the existence of records you can't see (filtered per-subscriber) nor their contents (never sent).

Why signal, not body

  • Security — the wire can't leak a field, because it carries none. All

reads go back through the one enforced path.

  • Simplicity — there is no second serialization/redaction path to keep in

sync with the API; the client just refetches.

  • Correctness under races — the refetch always returns the current row, so a

burst of edits collapses to one correct re-render rather than replaying stale bodies.

The durable, poll-based event log remains the fallback for missed pushes and for deployments with more than one worker process.

Related

uses plain ASGI and how websocket/SSE object events fit the direction.

subscribe and on every push.

behind the durable log.