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 stateis its command line.
import * as State from "gizlang/state";Types
Entry
type Entry = { key: bytes; value: bytes; revision: i64; }A key, its value and the revision of the commit that wrote it.
key:bytesvalue:bytesrevision:i64
Write
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:bytesvalue:_gizlang_sdk_core.Option<bytes>expect:i64
Change
type Change = { revision: i64; key: bytes; value: Option<bytes>; }A key that a commit of REVISION wrote (VALUE) or deleted (none).
revision:i64key:bytesvalue:_gizlang_sdk_core.Option<bytes>
Changed
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:boolchanges:Vec<gizlang_state.Change>revision:i64
KvError
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.
conflictinvalidio
Medium
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
type Mark = { revision: i64; key: bytes; gone: bool; }A key a commit of REVISION wrote, or deleted (GONE).
revision:i64key:bytesgone:bool
Recent
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
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
type Checked = { text: string; error: string; }A value's stored form (TEXT), or the reason it is refused (ERROR, with TEXT empty).
text:stringerror:string
Item
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:stringtext:stringrevision:i64
Edit
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:stringop:stringvalue:gizlang_json.Jsonexpect:i64
StateError
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:stringpath:stringmessage:string
Changes
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:boolitems:Vec<gizlang_state.Item>revision:i64
State
type State = { medium: Medium; schemas: Vec<Schema>; }The store: its medium and the schemas of its paths.
medium:gizlang_state.Mediumschemas:Vec<gizlang_state.Schema>
Peer
type Peer = PeerCredentialsWho asks, as the kernel saw the connection (no uid: -1).
Admit
type Admit = (peer: Peer, method: string, path: string) => boolWhether 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
type Client = { lines: Lines; next: i64; }A connection to a store that serve answers.
lines:gizlang_state.Linesnext:i64
TomlFile
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.Dirname:stringvalues:_gizlang_sdk_collections.SortedMap<bytes, gizlang_state.Kept>revision:i64durable:i64recent:gizlang_state.Recent
Kept
type Kept = { value: bytes; revision: i64; }A value of a TOML file and the revision that wrote it.
value:bytesrevision:i64
Functions
recentAt
function recentAt(revision: i64): RecentNothing kept yet, at REVISION: a reader from before it reads its prefix whole.
resetOf
function resetOf(entries: Vec<Entry>, durable: i64): ChangedEvery current entry of a prefix, ENTRIES, as the changes up to DURABLE of a reader behind the kept ones (reset).
Effects: fail, alloc.
changedOf
function changedOf(since: Vec<Mark>, now: Vec<Option<Entry>>, durable: i64): ChangedThe 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
function schema<T>(pattern: string, rule: (value: T) => string): SchemaValues 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
function partial<T>(pattern: string, base: T, rule: (value: T) => string): SchemaValues 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
function layerOf(stored: Json, given: Json): JsonThe 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
function untyped(pattern: string): SchemaValues at paths matching PATTERN may be any JSON.
Effects: fail, alloc.
open
function open(medium: Medium, schemas: Vec<Schema>): StateThe store MEDIUM keeps, for paths SCHEMAS describe (the first match applies).
everyone
function everyone(peer: Peer, method: string, path: string): boolAn Admit that lets everyone do everything: for a socket whose file mode already limits who connects.
serve
function serve(state: State, listener: Listener, stop: Task.Cell<i64>, admit: Admit): void throws StateErrorServes 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
function connect(socket: string): Client throws StateErrorA connection to the store at SOCKET.
Effects: fail, read, io, alloc.
tomlFile
function tomlFile(dir: Dir, name: string): Medium throws StateErrorThe store in file NAME of DIR, read back when it is there.
Effects: fail, read, write, io, alloc.
Methods
Recent.keep
function Recent.keep(self: mut Recent, mark: Mark): voidKeeps MARK; past RECENT the oldest commits go, whole, to half of it.
Effects: fail, alloc.
Recent.holds
function Recent.holds(self: Recent, key: bytes, now: i64, expect: i64): boolWhether 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
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
function Item.value(self: Item): JsonThe item's value.
Effects: fail, alloc.
State.revision
function State.revision(self: State): i64The current revision: the last durable commit.
Effects: fail, read, write, console, io, alloc.
State.get
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
function State.read<T>(self: mut State, path: string): Option<T> throws StateErrorThe value at PATH as T, or none. A partial value (partial) reads as T only where it has every field.
State.list
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
function State.apply(self: mut State, edits: Vec<Edit>): i64 throws StateErrorChecks EDITS and runs them as the next commit, in memory; durable after flush. Its revision.
Effects: fail, read, write, console, io, alloc.
State.flush
function State.flush(self: mut State): void throws StateErrorMakes every applied commit durable.
Effects: fail, read, write, console, io, alloc.
State.commit
function State.commit(self: mut State, edits: Vec<Edit>): i64 throws StateErrorapply, then flush: the commit is durable when it answers.
Effects: fail, read, write, console, io, alloc.
State.write
function State.write<T>(self: mut State, path: string, value: T): i64 throws StateErrorPuts VALUE at PATH: a commit of one edit.
State.changes
function State.changes(self: mut State, prefix: string, after: i64): ChangesThe durable changes after revision AFTER under PREFIX; a deleted path's value is null.
Effects: fail, read, write, console, io, alloc.
State.dispose
function State.dispose(self: mut State): void throws StateErrorFlushes and closes the store.
Effects: fail, read, write, console, io, alloc.
Client.call
function Client.call(self: mut Client, method: string, params: Json): Json throws StateErrorThe result of METHOD with PARAMS, or its error.
Effects: fail, io, alloc.
Client.receive
function Client.receive(self: mut Client): Json throws StateErrorThe next message the store sends: an answer, or a watch's notice.
Effects: fail, io, alloc.
Client.dispose
function Client.dispose(self: Client): voidCloses the connection.
Effects: fail, io, alloc.
TomlFile.get
function TomlFile.get(self: mut TomlFile, key: bytes): Option<Entry>The entry at KEY, or none.
Effects: fail.
TomlFile.range
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
function TomlFile.apply(self: mut TomlFile, writes: Vec<Write>): i64 throws KvErrorApplies WRITES at once, after their conditions hold; the new revision. A condition that fails throws a conflict.
Effects: fail, alloc.
TomlFile.flush
function TomlFile.flush(self: mut TomlFile): void throws KvErrorWrites the file when it has changes it has not written (a temporary file, a sync, a rename).
Effects: fail, read, io, alloc.
TomlFile.changes
function TomlFile.changes(self: mut TomlFile, prefix: bytes, after: i64): ChangedThe changes under PREFIX after the revision AFTER, or a reset when they are no longer kept.
Effects: fail, read, write, console, io, alloc.