Skip to main content

Crate semiont

Crate semiont 

Source
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>, with scope=, cid= and trace= 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_ and beckon; and job, auth and system.
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 its browse, gather and match_ 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 roles claim, and its kind. The same strings the launcher writes into the realm; npm run lint:service-role holds 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 login keeps (protocol/specs/src/sign-in-store), as a SessionStorage: 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 body has as the component schema T is generated from, as it refuses it: “it has no `member`”, “its `member` is malformed”, or “it is malformed”; None when it has none.