GizStack
View .mdOpen in ChatGPTOpen in Claude

gizlang/state

typed values at paths, for one program to own and others to read, change and watch: an operating system's settings, an app's preferences, a service's configuration.

  • A path is segments joined by "/" (display/monitor/del-a12f). A value is JSON. A schema ties a path pattern to a Gizlang type and a rule: every write is read as that type, checked by its constraint annotations (gizlang/constraints) and the rule, and stored as the type writes it (gizlang/json encode), so a value has one form and a typo in a field name is refused, not stored. - A commit is a list of edits (put, patch as RFC 7396 JSON Merge Patch, delete), each optionally on the condition of its path's revision. It is atomic and durable when it answers. - A watch is a prefix and a revision: each path changed after it, once, at its last change, then those of each new commit. A watcher too far behind gets the prefix's current values instead (reset). - A medium keeps the keys (Medium): the KV engine's log (gizdb/kv/local medium) or one TOML file (tomlFile). A program imports the one it keeps, so a small image links this module and gizlang/toml alone. - One process owns the store. serve answers JSON-RPC 2.0 lines on a unix-domain socket; one task runs every request in turn, so commits that arrive together share one sync. gizdb state is its command line.
gizlang
import * as State from "gizlang/state";

Types

Entry

gizlang
type Entry = { key: bytes; value: bytes; revision: i64; }

A key, its value and the revision of the commit that wrote it.

  • key: bytes
  • value: bytes
  • revision: i64

Write

gizlang
type Write = { key: bytes; value: Option<bytes>; expect: i64; }

One write of a commit: KEY gets VALUE, or goes when VALUE is none. EXPECT: the key has not changed after that revision (0: it is absent), so one revision a reader read at guards every key it read; -1 for no condition.

  • key: bytes
  • value: _gizlang_sdk_core.Option<bytes>
  • expect: i64

Change

gizlang
type Change = { revision: i64; key: bytes; value: Option<bytes>; }

A key that a commit of REVISION wrote (VALUE) or deleted (none).

  • revision: i64
  • key: bytes
  • value: _gizlang_sdk_core.Option<bytes>

Changed

gizlang
type Changed = { reset: bool; changes: Vec<Change>; revision: i64; }

The durable changes after a revision, up to REVISION. RESET: the changes were no longer kept, so CHANGES holds every current key of the prefix instead, and the reader replaces what it knew of the prefix.

  • reset: bool
  • changes: Vec<gizlang_state.Change>
  • revision: i64

KvError

gizlang
type KvError = | { kind: "conflict"; key: bytes; revision: i64 } | { kind: "invalid"; key: bytes; message: string } | { kind: "io"; message: string }

Why a commit failed: a condition did not hold (the key and its revision), a key the medium cannot keep, or the medium could not be written.

  • conflict
  • invalid
  • io

Medium

gizlang
type Medium = { get: (key: bytes) => Option<Entry>; range: (prefix: bytes) => Vec<Entry>; apply: (writes: Vec<Write>) => i64 throws KvError; flush: () => void throws KvError; changes: (prefix: bytes, after: i64) => Changed; committed: () => i64; dispose: () => void throws KvError; }

A medium of a store: what keeps its keys, as functions over the medium's own state (gizdb/kv/local medium, tomlFile). A program holds the one it opened; the store calls nothing else.

  • get: (key: bytes) => _gizlang_sdk_core.Option<gizlang_state.Entry> — The entry of KEY, or none.
  • range: (prefix: bytes) => Vec<gizlang_state.Entry> — The entries whose keys start with PREFIX, in byte order.
  • apply: (writes: Vec<gizlang_state.Write>) => i64 throws gizlang_state.KvError — Runs WRITES as the next commit, in memory: its revision.
  • flush: () => void throws gizlang_state.KvError — Makes every applied commit durable.
  • changes: (prefix: bytes, after: i64) => gizlang_state.Changed — The durable changes after revision AFTER of the keys that start with PREFIX.
  • committed: () => i64 — The last durable revision.
  • dispose: () => void throws gizlang_state.KvError — Flushes and closes the medium.

Mark

gizlang
type Mark = { revision: i64; key: bytes; gone: bool; }

A key a commit of REVISION wrote, or deleted (GONE).

  • revision: i64
  • key: bytes
  • gone: bool

Recent

gizlang
type Recent = { marks: Vec<Mark>; floor: i64; }

The changes kept for readers behind the newest revision, after floor, in order: about 80 bytes each. A reader at or after floor sees every change since; one before it does not, and neither does a condition.

  • marks: Vec<gizlang_state.Mark>
  • floor: i64

Schema

gizlang
type Schema = { pattern: Vec<string>; check: (value: Json) => Checked; }

A path pattern ("*" is one segment, a last "**" any number) and what its values must be: CHECK gives a value's stored form, or why it is refused.

  • pattern: Vec<string>
  • check: (value: gizlang_json.Json) => gizlang_state.Checked

Checked

gizlang
type Checked = { text: string; error: string; }

A value's stored form (TEXT), or the reason it is refused (ERROR, with TEXT empty).

  • text: string
  • error: string

Item

gizlang
type Item = { path: string; text: string; revision: i64; }

A path, its value as stored JSON text ("null" for a deleted path in changes), and the revision of the commit that wrote it. The text is parsed only when asked (Item.value): a list need not parse what it hands on.

  • path: string
  • text: string
  • revision: i64

Edit

gizlang
type Edit = { path: string; op: string; value: Json; expect: i64; }

One edit of a commit. OP is "put" (VALUE is the value), "patch" (VALUE is a merge patch of the current value, or of {} when there is none) or "delete". EXPECT: the path has not changed after that revision (0: it is absent), so the revision a reader read at guards all it read; -1 for none.

  • path: string
  • op: string
  • value: gizlang_json.Json
  • expect: i64

StateError

gizlang
type StateError = { kind: string; path: string; message: string; }

Why a request failed: "invalid" (a path or value its schema refuses), "conflict" (a path changed after its expected revision), "denied" (the service's admit refused it), "io" (the log could not be written: the store stops) or "closed" (no store answers).

  • kind: string
  • path: string
  • message: string

Changes

gizlang
type Changes = { reset: bool; items: Vec<Item>; revision: i64; }

The changes after a revision; RESET: the values of the whole prefix, which replace what the reader knew.

  • reset: bool
  • items: Vec<gizlang_state.Item>
  • revision: i64

State

gizlang
type State = { medium: Medium; schemas: Vec<Schema>; }

The store: its medium and the schemas of its paths.

  • medium: gizlang_state.Medium
  • schemas: Vec<gizlang_state.Schema>

Peer

gizlang
type Peer = PeerCredentials

Who asks, as the kernel saw the connection (no uid: -1).

Admit

gizlang
type Admit = (peer: Peer, method: string, path: string) => bool

Whether PEER may run METHOD (get, list, watch, commit) on PATH: a get's or commit edit's path, a list's or watch's prefix. The store's owner gives its policy; the service asks it for every path of every request.

Client

gizlang
type Client = { lines: Lines; next: i64; }

A connection to a store that serve answers.

  • lines: gizlang_state.Lines
  • next: i64

TomlFile

gizlang
type TomlFile = { dir: Dir; name: string; values: SortedMap<bytes, Kept>; revision: i64; durable: i64; recent: Recent; }

A store in one TOML file, for a machine too small for a log (tomlFile): revision = N, then each path's value, an object as the table ["path"] and any other value as the key "path" = value. A flush writes the whole file anew: a temporary file, its sync, a rename over the old one, the folder's sync (settings are a few KB). After a restart every path has the file's revision: a condition from before it conflicts, and a watcher from before it resets. TOML has no null: a null field is left out, and a value with a null in an array cannot be kept.

  • dir: gizlang_system.Dir
  • name: string
  • values: _gizlang_sdk_collections.SortedMap<bytes, gizlang_state.Kept>
  • revision: i64
  • durable: i64
  • recent: gizlang_state.Recent

Kept

gizlang
type Kept = { value: bytes; revision: i64; }

A value of a TOML file and the revision that wrote it.

  • value: bytes
  • revision: i64

Functions

recentAt

gizlang
function recentAt(revision: i64): Recent

Nothing kept yet, at REVISION: a reader from before it reads its prefix whole.

resetOf

gizlang
function resetOf(entries: Vec<Entry>, durable: i64): Changed

Every current entry of a prefix, ENTRIES, as the changes up to DURABLE of a reader behind the kept ones (reset).

Effects: fail, alloc.

changedOf

gizlang
function changedOf(since: Vec<Mark>, now: Vec<Option<Entry>>, durable: i64): Changed

The changes up to DURABLE of the marks SINCE gives (Recent.since), each with its key's entry NOW: the key once, at its last change, with its value now (none: deleted).

Effects: fail, alloc.

schema

gizlang
function schema<T>(pattern: string, rule: (value: T) => string): Schema

Values at paths matching PATTERN are read as T: each field must meet its constraint annotations (Min, Max, MaxLength, Pattern and Values of gizlang/constraints), and the whole must pass RULE, which gives "" or the reason (a check of several fields, or of another path's value). The value is stored as T writes it.

partial

gizlang
function partial<T>(pattern: string, base: T, rule: (value: T) => string): Schema

Values at paths matching PATTERN hold some fields of T, as a layer of settings does: each field given is checked as T's, BASE gives the others for the check and RULE sees the whole, and a field T lacks is refused. The value stores only the fields given, in T's order.

layerOf

gizlang
function layerOf(stored: Json, given: Json): Json

The fields of STORED that GIVEN has, in STORED's order, and so on inside: the stored form of a layer (partial) that gave the fields of GIVEN.

Effects: fail, alloc.

untyped

gizlang
function untyped(pattern: string): Schema

Values at paths matching PATTERN may be any JSON.

Effects: fail, alloc.

open

gizlang
function open(medium: Medium, schemas: Vec<Schema>): State

The store MEDIUM keeps, for paths SCHEMAS describe (the first match applies).

everyone

gizlang
function everyone(peer: Peer, method: string, path: string): bool

An Admit that lets everyone do everything: for a socket whose file mode already limits who connects.

serve

gizlang
function serve(state: State, listener: Listener, stop: Task.Cell<i64>, admit: Admit): void throws StateError

Serves STATE on LISTENER (a unix-domain socket the caller bound, and gave the mode its clients need) until STOP holds a value other than 0; serve closes LISTENER then. Each path of each request goes as ADMIT lets its peer. The methods:

  • get {path}: {path, value, revision} or null
  • list {prefix}: [{path, value, revision}]
  • commit {edits: [{path, op, value, expect}]}: {revision}
  • watch {prefix, after}: {revision}, then notices "changes" {reset, revision, items} with a deleted path's value null
  • revision {}: {revision} An error is code 1 invalid, 2 conflict, 3 io (the service stops after it) or 4 denied.

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

connect

gizlang
function connect(socket: string): Client throws StateError

A connection to the store at SOCKET.

Effects: fail, read, io, alloc.

tomlFile

gizlang
function tomlFile(dir: Dir, name: string): Medium throws StateError

The store in file NAME of DIR, read back when it is there.

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

Methods

Recent.keep

gizlang
function Recent.keep(self: mut Recent, mark: Mark): void

Keeps MARK; past RECENT the oldest commits go, whole, to half of it.

Effects: fail, alloc.

Recent.holds

gizlang
function Recent.holds(self: Recent, key: bytes, now: i64, expect: i64): bool

Whether KEY, whose last write is at revision NOW (0: it is absent), holds condition EXPECT: 0, the key is absent; N, its last write or delete is at or before N. A key absent now holds N only when no kept change of it is after N, and N is not before the kept ones.

Effects: fail.

Recent.since

gizlang
function Recent.since(self: Recent, prefix: bytes, after: i64, durable: i64): Option<Vec<Mark>>

The kept changes after AFTER up to DURABLE of the keys that start with PREFIX, or none when AFTER is before them (the reader resets).

Effects: fail, alloc.

Item.value

gizlang
function Item.value(self: Item): Json

The item's value.

Effects: fail, alloc.

State.revision

gizlang
function State.revision(self: State): i64

The current revision: the last durable commit.

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

State.get

gizlang
function State.get(self: mut State, path: string): Option<Item>

The item at PATH, or none.

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

State.read

gizlang
function State.read<T>(self: mut State, path: string): Option<T> throws StateError

The value at PATH as T, or none. A partial value (partial) reads as T only where it has every field.

State.list

gizlang
function State.list(self: mut State, prefix: string): Vec<Item>

The items whose paths start with PREFIX, in byte order of their paths.

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

State.apply

gizlang
function State.apply(self: mut State, edits: Vec<Edit>): i64 throws StateError

Checks EDITS and runs them as the next commit, in memory; durable after flush. Its revision.

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

State.flush

gizlang
function State.flush(self: mut State): void throws StateError

Makes every applied commit durable.

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

State.commit

gizlang
function State.commit(self: mut State, edits: Vec<Edit>): i64 throws StateError

apply, then flush: the commit is durable when it answers.

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

State.write

gizlang
function State.write<T>(self: mut State, path: string, value: T): i64 throws StateError

Puts VALUE at PATH: a commit of one edit.

State.changes

gizlang
function State.changes(self: mut State, prefix: string, after: i64): Changes

The durable changes after revision AFTER under PREFIX; a deleted path's value is null.

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

State.dispose

gizlang
function State.dispose(self: mut State): void throws StateError

Flushes and closes the store.

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

Client.call

gizlang
function Client.call(self: mut Client, method: string, params: Json): Json throws StateError

The result of METHOD with PARAMS, or its error.

Effects: fail, io, alloc.

Client.receive

gizlang
function Client.receive(self: mut Client): Json throws StateError

The next message the store sends: an answer, or a watch's notice.

Effects: fail, io, alloc.

Client.dispose

gizlang
function Client.dispose(self: Client): void

Closes the connection.

Effects: fail, io, alloc.

TomlFile.get

gizlang
function TomlFile.get(self: mut TomlFile, key: bytes): Option<Entry>

The entry at KEY, or none.

Effects: fail.

TomlFile.range

gizlang
function TomlFile.range(self: mut TomlFile, prefix: bytes): Vec<Entry>

The entries whose keys start with PREFIX, in key order.

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

TomlFile.apply

gizlang
function TomlFile.apply(self: mut TomlFile, writes: Vec<Write>): i64 throws KvError

Applies WRITES at once, after their conditions hold; the new revision. A condition that fails throws a conflict.

Effects: fail, alloc.

TomlFile.flush

gizlang
function TomlFile.flush(self: mut TomlFile): void throws KvError

Writes the file when it has changes it has not written (a temporary file, a sync, a rename).

Effects: fail, read, io, alloc.

TomlFile.changes

gizlang
function TomlFile.changes(self: mut TomlFile, prefix: bytes, after: i64): Changed

The changes under PREFIX after the revision AFTER, or a reset when they are no longer kept.

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