gizmodel/relay
realtime as a position in a log the database keeps. Every committed change appends its topic and key (not its value: the store is the state, so a subscriber reads the rows a change names); a subscriber asks for a topic's changes after the position it holds and waits (a long poll) until there are some or its wait ends. Positions belong to the database, not to a process, so every worker process of the application (GIZLANG_WORKERS) and every later run answers the same position the same way. A position older than what the log keeps, or from another database, gets a snapshot answer: the caller renders the topic again. So a reconnect, a missed message, a restart and a request served by another worker are one path.
import * as Relay from "gizmodel/relay";Types
Notice
type Notice = { topic: string; key: string; gone: bool; }A change to the row key of topic: written, or gone.
topic:stringkey:stringgone:bool
Delta
type Delta = | { kind: "changes"; changes: Vec<Notice>; position: string; } | { kind: "snapshot"; position: string; }What a subscriber gets: the topic's changes and the position after them, or a snapshot to render at that position.
changessnapshot
Relay
type Relay_store is held by reference: a feed travels in an app context (a record of fixed size).
Opaque: create and use it through this module's functions.
Functions
relay
function relay(store: Database, keep: i64): Relay throws SqlErrorThe feed of store, keeping the last keep changes (its table is created
when missing).
Effects: fail, read, write, console, io, alloc.
Methods
Relay.position
function Relay.position(self: Relay): string throws SqlErrorThe current position, for the first render of a topic.
Effects: fail, read, write, console, io, alloc.
Relay.transaction
function Relay.transaction<F>(self: Relay, work: F): Rows throws SqlErrorRuns work (as Database.transaction does) and, once it committed, wakes this
process's subscribers. Work writes its rows and publishes each change.
Relay.publish
function Relay.publish(self: Relay, tx: Database, change: Notice): bool throws SqlErrorInside Relay.transaction: append a change. Publishers take the feed's lock until they commit, so positions commit in order and a subscriber that read up to one never later finds an earlier one appear (PostgreSQL hands out identities to transactions that may commit in another order).
Effects: fail, read, write, console, io, alloc.
Relay.changed
function Relay.changed(self: Relay, change: Notice, write: (tx: Database) => void throws SqlError): void throws SqlErrorRuns write and publishes change in one Relay.transaction; a write that throws publishes nothing.
Effects: fail, read, write, console, io, alloc.
Relay.notify
function Relay.notify(self: Relay, change: Notice): Rows throws SqlErrorPublishes change alone, in a Relay.transaction of its own.
Effects: fail, read, write, console, io, alloc.
Relay.ingest
function Relay.ingest(self: Relay, source: string, position: i64, changes: Vec<Notice>): bool throws SqlErrorPublish an externally committed CDC batch and its durable per-stream offset. A commit may change many rows with the same source position: publish them together. Sources deliver increasing positive positions per partition; replayed or older batches are ignored. This store commits the offset and notices atomically. An empty batch advances the durable source checkpoint without a view invalidation.
Effects: fail, read, write, console, io, alloc.
Relay.since
function Relay.since(self: Relay, topic: string, position: string, waitMs: i64, related: Vec<string> = []): Delta throws SqlErrorThe changes to topic after position, waiting up to waitMs for one.
Effects: fail, read, write, console, io, alloc.
Delta.position
function Delta.position(self: Delta): stringThe position a delta brings its subscriber to.