Module realtime 

Real-time subscription system.

Forge provides automatic real-time updates via PostgreSQL LISTEN/NOTIFY. When tables change, affected subscriptions are invalidated and re-executed.

Architecture

Client                Gateway                  PostgreSQL
  │                      │                         │
  │─── Subscribe ───────>│                         │
  │                      │── Execute query ───────>│
  │<── Initial data ─────│<── Results ────────────│
  │                      │                         │
  │                      │<── NOTIFY on change ───│
  │                      │── Re-execute query ───>│
  │<── Delta update ─────│<── New results ────────│

Key Types

• ReadSet - Tables a subscription depends on
• QueryGroup - Coalesced subscriptions sharing query+args+auth_scope
• Subscriber - Lightweight subscriber within a query group
• Delta - Change payload sent to clients

Structs

AuthScope

Authentication scope for query group identity. Two subscriptions with the same query+args but different auth scopes must be in different groups (different users see different data). Includes a hash of the sorted roles so users with different role sets don’t share a group.

Change

A database change event.

Delta

Delta format for subscription updates.

QueryGroup

Coalesces subscriptions sharing the same query+args+auth_scope. On invalidation the query executes once per group, not per subscriber.

QueryGroupId

Compact identifier for query groups. u32 for cache-friendly storage.

ReadSet

Read set tracking tables read during query execution.

SessionId

Unique session identifier.

SessionInfo

Information about a WebSocket session.

Subscriber

Lightweight subscriber within a query group. ~48 bytes.

SubscriberId

Compact identifier for subscribers within a slab.

SubscriptionId

Unique subscription identifier.

SubscriptionKey

Opaque dedup key for subscriptions sharing the same query+args+auth_scope.

SubscriptionState

Subscription state from the client’s perspective.

Enums

ChangeOperation

Change operation type.

SessionStatus

Session status.

TrackingMode

Tracking mode for read sets.