GizStack
View .mdOpen in ChatGPTOpen in Claude

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.

gizlang
import * as Relay from "gizmodel/relay";

Types

Notice

gizlang
type Notice = { topic: string; key: string; gone: bool; }

A change to the row key of topic: written, or gone.

  • topic: string
  • key: string
  • gone: bool

Delta

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

  • changes
  • snapshot

Relay

gizlang
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

gizlang
function relay(store: Database, keep: i64): Relay throws SqlError

The feed of store, keeping the last keep changes (its table is created when missing).

Effects: fail, read, write, console, io, alloc.

Methods

Relay.position

gizlang
function Relay.position(self: Relay): string throws SqlError

The current position, for the first render of a topic.

Effects: fail, read, write, console, io, alloc.

Relay.transaction

gizlang
function Relay.transaction<F>(self: Relay, work: F): Rows throws SqlError

Runs work (as Database.transaction does) and, once it committed, wakes this process's subscribers. Work writes its rows and publishes each change.

Relay.publish

gizlang
function Relay.publish(self: Relay, tx: Database, change: Notice): bool throws SqlError

Inside 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

gizlang
function Relay.changed(self: Relay, change: Notice, write: (tx: Database) => void throws SqlError): void throws SqlError

Runs write and publishes change in one Relay.transaction; a write that throws publishes nothing.

Effects: fail, read, write, console, io, alloc.

Relay.notify

gizlang
function Relay.notify(self: Relay, change: Notice): Rows throws SqlError

Publishes change alone, in a Relay.transaction of its own.

Effects: fail, read, write, console, io, alloc.

Relay.ingest

gizlang
function Relay.ingest(self: Relay, source: string, position: i64, changes: Vec<Notice>): bool throws SqlError

Publish 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

gizlang
function Relay.since(self: Relay, topic: string, position: string, waitMs: i64, related: Vec<string> = []): Delta throws SqlError

The changes to topic after position, waiting up to waitMs for one.

Effects: fail, read, write, console, io, alloc.

Delta.position

gizlang
function Delta.position(self: Delta): string

The position a delta brings its subscriber to.