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).

BloomFilter

Bloom filter for probabilistic row-level tracking. False positives cause one unnecessary re-execution (caught by result hash comparison). False negatives never happen.

Change

A database change event.

Delta

Delta format for subscription updates.

QueryGroup

A query group is the primary unit of execution. Multiple subscribers watching the same query+args+auth_scope share a single group. 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 and rows 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.

SubscriptionInfo

Information about a server-side subscription (kept for backward compat).

SubscriptionState

Subscription state from the client’s perspective.

Enums

ChangeOperation

Change operation type.

SessionStatus

Session status.

TrackingMode

Tracking mode for read sets.