omnyserver_hub library

Classes

Alert: A rule currently breached by a node.
AlertMonitor: Watches the fleet against a set of AlertRules, and says so when one is breached — and, just as importantly, when it stops being.
AlertRaised: A rule became breached by a node.
AlertResolved: A rule stopped being breached.
AlertRule: A condition worth being told about.
AuditEntry: An immutable record of a security- or operationally-relevant action, for the audit trail (who did what, to which target, with what outcome).
AuditLog: Records security- and operationally-relevant actions to an AuditRepository, stamping each with a generated id and the current time.
AuditRepository: Persists the audit trail.
AuthChallenge: Hub → peer: a nonce the peer must sign (public-key auth) and echo.
Authenticator: Verifies a Credential and resolves the authenticated Principal.
AuthFail: Hub → peer: authentication failed.
AuthOk: Hub → peer: authentication succeeded.
AuthorizedKey: An authorized public key entry: which principal it grants and the roles.
AuthorizedKeysStore: An in-memory trust store of authorized public keys, keyed by (principal, key).
Authorizer: Decides whether an authenticated Principal may perform an action.
AuthSubmit: Peer → Hub: the credential answering an AuthChallenge.
BroadcastEventBus: The default in-process EventBus, backed by a broadcast stream.
Capability: A single detected capability of a node, optionally with a version and free-form details (e.g. the GPU model for cuda).
CapabilityDetector: Probes the host for a single capability, returning it if present.
CertGenerator: Generates the TLS certificate material an OmnyServer Hub needs to run.
ChallengeMinter: Mints the single-use nonces the Hub challenges peers with.
Clock: Time source used throughout OmnyServer so tests can fix now.
CommandRequest: Hub → node: run a shell command.
CommandResult: Node → Hub: the result of a CommandRequest.
CompositeAuthenticator: Tries several Authenticators in order, succeeding on the first that authenticates the credential.
ControlMessage: Base type for the JSON messages exchanged during the OmnyServer handshake — the challenge/response that runs on a freshly-opened control connection, before the omnyhub node protocol takes over.
ControlMessageCodec: Encodes handshake ControlMessages to and from the JSON envelope {"type": <type>, ...fields}, carried as WebSocket text frames.
CpuInfo: CPU utilisation snapshot for a node.
Credential: A credential presented by a connecting party (client or node) during the authentication handshake.
CurrentState: The observed configuration of a node: what it currently advertises.
DesiredState: The target configuration the Hub wants a node to reach: an ordered list of formula steps (typically expanded from one or more presets).
DesiredStateRepository: Persists the state each node is supposed to be in.
Drift: How far a node has drifted from what it was declared to be — the wire form of a Reconciliation.
Ed25519PublicKey: An Ed25519 public key, used to identify users and nodes in an authorized_keys-style trust store. Equality is by key bytes.
ErrorCodes: Stable, machine-readable error codes carried in error control messages and surfaced on OmnyServerExceptions.
EventAggregator: Subscribes to an EventBus and keeps a bounded, in-memory history of recent events plus per-type counts — the basis for the events API and dashboards.
EventBus: A publish/subscribe bus for OmnyEvents.
Formula: An operational procedure that manages a piece of software on a node (install / update / start / stop / restart / uninstall / verify).
FormulaContext: Ambient context handed to a Formula action: the host platform, an optional pinned target version, free-form parameters, a clock and a log sink for streaming progress.
FormulaFinished: A formula run finished on a node.
FormulaId: Identity of a formula (an operational procedure such as docker or dart).
FormulaRepository: Persists FormulaSpecs (formula catalogue).
FormulaResult: The structured outcome of running a single formula action.
FormulaRun: Hub → node: run a formula action.
FormulaRunResult: Node → Hub: the final result of a FormulaRun.
FormulaSpec: Declarative metadata describing a formula: its identity, the platforms it supports, the actions it implements and an optional target version.
FormulaStarted: A formula run started on a node.
GeneratedCertificates: The paths of the TLS files produced by CertGenerator.generate.
Grant: A credential the Hub has issued: who it is for, what it may do, and the fingerprint of the token that proves it.
GrantAuthenticator: Authenticates against the grants the Hub has issued, as opposed to the ones baked into its command line.
GrantRepository: Persists the credentials the Hub has issued.
HandshakeChannel: A ControlMessage-typed view over omnyhub's HandshakeConnection.
Heartbeat: A liveness signal a node sends to the Hub at a regular interval, optionally carrying a fresh NodeStatus snapshot.
HeartbeatReceived: A heartbeat was received from a node.
Hello: First message a peer sends after connecting: announces role and protocol.
HttpApiServer: A reusable, versioned REST API in front of an OmnyServerHub.
HubConfig: Configuration for an OmnyServerHub.
HubMetrics: Wires Hub lifecycle/operational events and live registry state into a MetricsRegistry, producing Prometheus-ready metrics:
IdGenerator: Generates opaque, unique identifiers (session ids, audit ids, request ids).
Json: Manual JSON read helpers shared by control-message and entity decoders.
JsonAuditRepository: JSON-lines AuditRepository (<root>/audit.jsonl, append-only).
JsonDesiredStateRepository: JSON-directory DesiredStateRepository (<root>/desired/<node>.json).
JsonFormulaRepository: JSON-directory FormulaRepository (<root>/formulas/<id>.json).
JsonGrantRepository: JSON-directory GrantRepository (<root>/grants/<id>.json).
JsonMetricRepository: JSON-lines MetricRepository (<root>/metrics/<nodeId>.jsonl).
JsonNodeRepository: JSON-directory NodeRepository (<root>/nodes/<id>.json).
JsonPresetRepository: JSON-directory PresetRepository (<root>/presets/<id>.json).
LogBatch: Node → Hub: a batch of log lines, pushed one-way.
LogBuffer: The Hub's log sink: a bounded, per-node tail of what nodes have reported, plus a live stream of it.
LogLine: One line a node reported, stamped with when the Hub received it.
MachineId: Resolves a stable, per-machine fingerprint used as an input to UidComputer. It is best-effort and never throws: on platforms where no stable id is available it falls back to the host name.
MemoryAuditRepository: In-memory AuditRepository keeping a bounded ring of recent entries.
MemoryDesiredStateRepository: In-memory DesiredStateRepository.
MemoryFormulaRepository: In-memory FormulaRepository.
MemoryGrantRepository: In-memory GrantRepository.
MemoryInfo: Memory utilisation snapshot for a node (bytes).
MemoryMetricRepository: In-memory MetricRepository keeping a bounded ring of samples per node.
MemoryNodeRepository: In-memory NodeRepository; data lives only for the process lifetime.
MemoryPresetRepository: In-memory PresetRepository.
MetricPoint: One node's resource usage at an instant — the chartable projection of a NodeStatus.
MetricRepository: Persists historical metric samples for nodes.
MetricSample: A persisted, timestamped metric sample for a node.
MetricsRegistry: A minimal metrics registry that renders Prometheus text exposition.
NodeCapabilities: The set of capabilities a node advertises, keyed by capability name.
NodeConnected: A node connected and authenticated to the Hub.
NodeConnectionAuthenticator: Authenticates a node's control connection with OmnyServer's in-band challenge/response, before omnyhub's node protocol takes over.
NodeControl: Hub → node: a node-level control request (restart / shutdown / update).
NodeDescriptor: The Hub's view of a registered node: its identity, platform, advertised capabilities, operator labels and live online flag.
NodeDisconnected: A node disconnected from the Hub.
NodeEvent: An observable change in the NodeRegistry.
NodeId: Stable identity of a node, used by the Hub and clients to address it (instead of a host:port). Equality is by value.
NodeRegistry: Tracks the nodes registered with the hub and answers discovery queries.
NodeRepository: Persists the Hub's view of registered nodes.
NodeStatus: A point-in-time live snapshot of a node's health and resource utilisation.
NodeUpdated: A node was updated (OS, package or agent).
OmnyEvent: Base type for every event emitted on the Hub's EventBus.
OmnyServerHome: Resolves the OmnyServer home directory (~/.omnyserver by default), where identity, credentials and local state live.
OmnyServerHub: The central orchestrator: accepts node connections over WSS, authenticates them, maintains a live registry, aggregates status and events, and dispatches operations (restart, formula, preset, …) to nodes, correlating their results.
OmnyUid: A globally-unique, content-derived identity for a node or hub.
Operation: Something the Hub is doing to a node, that takes long enough to be worth a name.
OperationAck: A generic acknowledgement for a request that has no richer result type.
OperationFinished: A long-running operation finished.
Operations: The operations the Hub invokes on a node, and the results it gets back.
OperationStarted: A long-running operation was dispatched to a node.
OperationStore: The operations the Hub is running, and the last few it ran.
PlatformInfo: Static facts about a node's host operating system and agent build, reported once at registration (and refreshed on reconnect).
Preset: A named desired-configuration bundle: an ordered list of formula steps that move a server toward a target state. Presets are designed to be idempotent.
PresetApplied: A preset was applied to a node.
PresetApply: Hub → node: apply a preset (a bundle of formula steps).
PresetApplyResult: Node → Hub: the result of applying a preset.
PresetId: Identity of a preset (a named desired-configuration bundle of formulas).
PresetRepository: Persists Presets.
PresetStep: A reference to a formula within a preset: which formula, which action to drive, and an optional pinned version.
Principal: An authenticated identity, with the roles it holds. Used by the Hub to make authorization decisions.
PrincipalId: Identity of an authenticated principal (a user account or a node account).
ProcessInfo: A running process snapshot and its resource consumption.
ProtocolErrorMessage: Either side: a protocol-level error raised during the handshake.
ProtocolVersion: The wire protocol version negotiated in the Hello handshake.
PublicKeyAuthenticator: Authenticates public-key Credentials against an AuthorizedKeysStore.
Reconciliation: The plan produced by reconciling a desired state against the current state: the ordered steps that still need to run to converge.
RegisteredNode: A node currently registered with the hub, with its live connection and liveness bookkeeping.
RoleBasedAuthorizer: A simple role-based Authorizer: a principal may perform an action if it holds one of the roles mapped to that action's required role set, or holds the wildcard adminRole.
Rollbackable: Optional mixin for formulas that can roll back a failed action.
ServiceControl: Hub → node: control an OS service.
ServiceControlResult: Node → Hub: the result of a ServiceControl.
ServiceDescriptor: Describes an OS-level service managed by OmnyServer (hub or agent), abstracting over systemd / launchd / Windows Service Manager.
ShellHub: Hosts an OmnyShell broker on the OmnyServer Hub's listener, so one Hub serves both fleets.
SqliteAuditRepository: SQLite-backed AuditRepository.
SqliteDesiredStateRepository: SQLite-backed DesiredStateRepository.
SqliteFormulaRepository: SQLite-backed FormulaRepository.
SqliteGrantRepository: SQLite-backed GrantRepository.
SqliteMetricRepository: SQLite-backed MetricRepository.
SqliteNodeRepository: SQLite-backed NodeRepository.
SqlitePresetRepository: SQLite-backed PresetRepository.
SqliteStore: Opens (or creates) a SQLite database and provides the repository implementations backed by it.
StateReconciler: Computes the Reconciliation needed to move a node from its current state toward a desired state.
StatusReport: Node → Hub: a live status snapshot, pushed one-way.
StorageDevice: A single storage device / mount point snapshot (bytes).
SystemClock: The default Clock, backed by the system wall clock (UTC).
TokenAuthenticator: Authenticates token Credentials against an in-memory token store.
TokenGrant: A token and the identity it grants.
UidComputer: Computes deterministic OmnyUids from identity material.
UuidGenerator: The default IdGenerator, backed by random (v4) UUIDs.
ValidationResult: The result of validating a formula's managed software.

Enums

AlertMetric: What an AlertRule watches.
AuditOutcome: The outcome of an audited operation.
CapabilityKind: The well-known kinds of capability a node can advertise.
FormulaAction: The operational steps a Formula supports.
NodeEventKind: The kind of a NodeEvent.
OperationStatus: Where an Operation has got to.
PeerRole: The role a connecting party announces in its Hello.
ServiceStatus: The lifecycle state of an OS-managed service.

Extensions

NodeDescriptorMapping on NodeDescriptor: Translates between OmnyServer's node descriptor and omnyhub's.

Constants

descriptorAttribute → const String: The key OmnyServer's full descriptor is advertised under, inside omnyhub's free-form omnyhub.NodeDescriptor.attributes.
omnyServerVersion → const String: The canonical OmnyServer package version (kept in sync with pubspec.yaml).

Functions

decodeChallenge(String nonce) → Uint8List: Decodes a wire nonce back to its raw bytes.
encodeChallenge(Uint8List challenge) → String: Encodes challenge for the wire.
hashToken(String token) → String: The SHA-256 of token, hex-encoded — what a Grant stores in place of it.
jsonOk(Object? body, {int status = 200}) → HubResponse: A successful JSON HubResponse.
newToken() → String: Mints a fresh bearer token: 32 bytes from the platform's secure random, base64url-encoded and unpadded.
nodeDescriptorFrom(NodeDescriptor descriptor) → NodeDescriptor: Recovers OmnyServer's descriptor from an omnyhub descriptor.
openApiDocument() → Map<String, dynamic>: Returns the static OpenAPI 3.0 document describing the v1 HTTP API.
toHubId(NodeId id) → NodeId: The omnyhub id for id.
toShellGrants(Map<String, TokenGrant> grants) → Map<String, TokenGrant>: Translates OmnyServer's token grants into OmnyShell's.

Typedefs

AuthAuditSink = Future<void> Function(String principal, String reason): Records a rejected authentication attempt.

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
CertGeneratorException: Thrown when certificate generation cannot complete.
NodeUnavailableException: The requested node is unknown or offline.
NotFoundException: A requested resource (formula, preset, node) was not found.
OmnyServerException: Base type for every expected, classified failure raised by OmnyServer.
OmnyServerTimeoutException: An operation exceeded its deadline.
OperationException: An operation (command, formula, preset) failed during execution.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
StorageException: A persistence backend failed to read or write.
TransportException: The underlying transport failed or closed unexpectedly.

omnyserver_hub library

Classes

Enums

Extensions

Constants

Functions

Typedefs

Exceptions / Errors

omnyserver package

omnyserver_hub library