Expand description
Semiont’s Rust SDK: a client of a knowledge base (client), with a
namespace per flow of the protocol (namespaces), over any transport.
Under it: the protocol’s types, channels, error codes and timing, as
protocol/specs/ states them; the transport contract and the bus client over it; a
client’s own bus; the shapes a namespace’s methods return (running,
cached), the cache its queries answer from and what refreshes it
(cache, refresh), where a client keeps what must outlive it
(storage), and the stream’s place kept with the caches (resume); the flows held as state a consumer reads and watches
(state); a session with a knowledge base and the registry of the ones
an application has signed in to (session); the sign-ins semiont login
keeps, as a storage (sign_in_store); the media types a knowledge base
admits (media_types); the readers of a resource’s description, and of
its bytes as text (resources); the knowledge bases a launcher
manages (discovery); when a failure is worth another attempt; whether a
job is one a claim takes (job_filter); a worker’s side of the job queue:
its claims, the jobs it holds and whether a failed one is retried
(claims); the readers of an annotation, and the builders of the ones a
worker commits (annotations);
how a knowledge base names its principals and the realm’s roles; and the
bus log. It does no HTTP and links no telemetry:
semiont-http-transport carries it over a gateway.
Modules§
- annotations
- Reading an annotation, and building one.
- bus
- A client of a knowledge base’s bus, over any
Transport: emit, observe, and request. - bus_log
SEMIONT_BUS_LOG: with any non-empty value, one line per frame a process sends or receives, and per read or upload of content, grep-able alike across processes:[bus <op>] <channel> scope=<resource> cid=<first 8> trace=<first 8> <payload>, withscope=,cid=andtrace=each written where there is one. On stderr, so the log lines on stdout stay one format.- cache
- A read-through cache: what a client’s live queries answer from (protocol/contract/CACHE-SEMANTICS.md, B1–B20).
- cached
- A live query: one of a client’s reads that answers from its cache
(
crate::cache) and stays true as the knowledge base changes. - channels
- The bus’s channels as a client meets them, generated from the registry (protocol/specs/src/bus/registry.json).
- claims
- A worker’s side of the job queue:
job.claim. - client
- A client of one knowledge base: its eleven namespaces over a transport, the bytes that never ride the bus, and the gateway’s own answers.
- discovery
- The knowledge bases a launcher manages, as the launcher publishes them (protocol/specs/src/discovery): what the document says, read whole or not at all, and what changed since it was last read.
- errors
- What a client reports when something fails, under the codes every SDK shares (protocol/specs/src/errors/codes.json, generated here): a transport’s failure, which is a server’s refusal or a request the gateway never answered; a bus request’s, which is the peer’s own failure or a fact only this side knows; a followed job’s, which failed for good or went silent; and the three together, as a caller meets them. Beside them, what makes a session unusable, what keeps a person from being signed in, and why no annotation is built of a span.
- event_
bus - A client’s own bus: frames published and observed inside one process. A
client constructs one and hands it to its transport (
bridge_into), which publishes into it every frame it delivers; what the client’s own parts say to each other goes through it too. - identity
- How a knowledge base is named, and the principals who act in it.
- job_
filter - Whether a job matches a filter.
- media_
types - The media types a knowledge base admits and what the system can do with each, as protocol/specs/src/media-types/registry.json states them, and the rules read from that table, which protocol/specs/src/media-types/cases.json holds in every SDK: the format a clone takes, the name content is stored under, and where a type’s text comes from, with whether that text has places on a page and whether it is derived.
- namespaces
- The namespaces of a client (
crate::client::SemiontClient), one per flow of the protocol and three beside them:frame,browse,mark,bind,gather,match_,yield_andbeckon; andjob,authandsystem. - refresh
- What refreshes a client’s cache, generated from
protocol/specs/src/client/refresh.json, the table every SDK applies: a row per
trigger, saying which live queries it asks again for (
refetches), which it writes with the value the event carries (writes), and which it ends, their entity being gone (removes); and where in the event its resource, its annotation and the value it carries are (names,carries). A client applies it to the queries of itsbrowse,gatherandmatch_namespaces, and states for itself only which namespace answers each query. - resources
- Reading a resource: what its description states, and its bytes as text.
- resume
- A stream’s place in each scope, kept so the next client for the same knowledge base resumes from it: what that client kept of a scope is then brought up to date by the events recorded since, replayed.
- retry
- Retrying: which failures are worth another attempt, and how long to keep trying.
- roles
- What the realm stamps on an account’s token: its roles, in the flat
rolesclaim, and its kind. The same strings the launcher writes into the realm;npm run lint:service-roleholds every site to one value. - running
- A long-running operation: what it reports as it goes, then its final value.
- session
- A client’s sessions with knowledge bases.
- sign_
in_ store - The sign-ins
semiont loginkeeps (protocol/specs/src/sign-in-store), as aSessionStorage: one sign-in serves the launcher’s verbs and an application built on this SDK. - state
- A client’s state units: its long-running flows, held as state a consumer reads and watches. None presumes a screen: a terminal, a daemon and an agent watching what a person does read them alike.
- state_
unit - A state unit: a piece of a client’s state with a reactive surface and one
structural commitment,
dispose. - storage
- Where a client keeps what must outlive it: a string under a key. The seam an environment fills in (a file, a platform’s store), so nothing above it knows where it runs.
- timing
- The timing a client keeps: its deadlines, its retry budgets and the cadence of its stream, generated from protocol/specs/src/client/timing.json, so one client waits as long, and tries as often, as another. A transport takes overrides of the ones a test must not wait out.
- transport
- The transport contract (protocol/contract/TRANSPORT-CONTRACT.md): what a client needs of whatever carries the bus, the bytes and the gateway’s own answers. Three traits, each usable as a trait object, so a client holds them without naming what carries them:
- types
- The protocol’s types, generated from the spec when this crate is built (build.rs): every schema of the job protocol’s channels, the reads a job’s admission makes, and the bodies of the bus transport, with every schema they reach. What a schema states that a type cannot — a pattern, a length, a bound — the receiving side’s validators hold.
Functions§
- fault_
said - What every SDK says of the first fault
bodyhas as the component schemaTis generated from, as it refuses it: “it has no `member`”, “its `member` is malformed”, or “it is malformed”;Nonewhen it has none.