omnyserver_node library

Classes

Alert: A rule currently breached by a node.
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).
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.
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.
CapabilityScanner: Runs a set of CapabilityDetectors concurrently and assembles the detected NodeCapabilities.
ChallengeMinter: Mints the single-use nonces the Hub challenges peers with.
Clock: Time source used throughout OmnyServer so tests can fix now.
CommandDetector: Detects a capability by running a probe command (typically tool --version) and, if it exits successfully, extracting a version string.
CommandExecutor: Runs external commands on behalf of formulas.
CommandFormula: A reusable base for formulas whose actions are platform-specific shell commands (the common case for installing/managing software).
CommandRequest: Hub → node: run a shell command.
CommandResult: Node → Hub: the result of a CommandRequest.
CommandStep: A platform command template: the executable and args to run for an action on a given OS family.
ConsoleNodeLogger: Bridges the node runtime's structured omnyhub.Logger to a plain line sink (the CLI's stdout), so what the Hub tells a node actually reaches the operator.
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.
CredentialProvider: Produces the Credential a connecting agent/client presents in answer to a Hub-issued auth challenge.
CudaDetector: Detects an NVIDIA CUDA GPU via nvidia-smi.
CurrentState: The observed configuration of a node: what it currently advertises.
DartFormula: The built-in Dart formula: installs and verifies the Dart SDK.
DefaultStateReconciler: The default capability-aware StateReconciler.
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.
DockerFormula: The built-in Docker formula: installs and manages the Docker engine.
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.
EventBus: A publish/subscribe bus for OmnyEvents.
ExecResult: The result of running an external command.
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).
FormulaRegistry: A catalogue of Formulas available on a node, keyed by formula id.
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.
Grant: A credential the Hub has issued: who it is for, what it may do, and the fingerprint of the token that proves it.
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.
IdGenerator: Generates opaque, unique identifiers (session ids, audit ids, request ids).
Json: Manual JSON read helpers shared by control-message and entity decoders.
LogBatch: Node → Hub: a batch of log lines, pushed one-way.
LogLine: One line a node reported, stamped with when the Hub received it.
LogShipper: Batches a node's log lines and ships them to the Hub.
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.
MemoryInfo: Memory utilisation snapshot for a node (bytes).
MetalDetector: Detects Apple Metal GPU support. Metal is available on every modern macOS host, so presence is inferred from the platform.
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.
MonitorParsers: Pure parsers for the textual output of the system probes the monitors run.
NodeAgent: The Node agent runtime: connects to the Hub over WSS, authenticates, registers, maintains a heartbeat with live status, executes Hub-dispatched operations, and reconnects automatically when the connection drops.
NodeAgentConfig: Configuration for a NodeAgent.
NodeCapabilities: The set of capabilities a node advertises, keyed by capability name.
NodeConnected: A node connected and authenticated to the Hub.
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.
NodeFormulaService: Executes formula and preset operations on a node, against a FormulaRegistry. Supplies the formulaHandler / presetHandler an agent plugs into its config.
NodeId: Stable identity of a node, used by the Hub and clients to address it (instead of a host:port). Equality is by value.
NodeRepository: Persists the Hub's view of registered nodes.
NodeServiceHandler: Answers Hub ServiceControl requests on the node by driving a ServiceController (systemd / launchd / Windows Service Manager).
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.
OmnyUid: A globally-unique, content-derived identity for a node or hub.
OpenClDetector: Detects OpenCL support via clinfo (best effort).
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.
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).
ProcessCommandExecutor: The default CommandExecutor, backed by Process.run.
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.
PublicKeyCredentialProvider: A CredentialProvider that signs the challenge with an Ed25519 key pair.
Reconciliation: The plan produced by reconciling a desired state against the current state: the ordered steps that still need to run to converge.
ReconnectPolicy: An exponential-backoff policy for reconnection attempts.
Rollbackable: Optional mixin for formulas that can roll back a failed action.
ServiceControl: Hub → node: control an OS service.
ServiceController: Wraps dart_service_manager to install and manage OmnyServer's own Hub and Node agent as native OS services (systemd / launchd / Windows Service Manager), exposing the lifecycle in OmnyServer's domain terms.
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.
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).
SystemMonitor: Assembles a live NodeStatus for the host by probing the OS for CPU, memory, storage, OS facts and top processes.
TokenCredentialProvider: A CredentialProvider that presents a static bearer token.
UidComputer: Computes deterministic OmnyUids from identity material.
UpdateService: Handles node update requests dispatched by the Hub (NodeControl with action update). Supports three update targets:
UuidGenerator: The default IdGenerator, backed by random (v4) UUIDs.
ValidationResult: The result of validating a formula's managed software.

Enums

AgentState: The connection lifecycle state of a NodeAgent.
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.
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.

Constants

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.
runNodeHandshake(HandshakeConnection connection, {required Future<Credential> credentials(Uint8List challenge), required String agentVersion, Duration timeout = const Duration(seconds: 10)}) → Future<void>: Runs the node side of OmnyServer's in-band authentication exchange — the counterpart of the Hub's NodeConnectionAuthenticator.
runProbe(String executable, List<String> args, {Duration timeout = const Duration(seconds: 5)}) → Future<ProcessResult?>: Runs a capability-probe command with a hard timeout, returning its result or null if it could not run or did not finish in time.

Typedefs

CapabilityProvider = Future<NodeCapabilities> Function(): Provides the node's currently-detected capabilities.
FormulaHandler = Future<FormulaResult> Function(FormulaRun request): Handles a Hub formula-run request on the node.
NodeControlHandler = Future<(bool, String)> Function(NodeControl request): Handles a Hub node-control request (restart/shutdown/update) on the node. Returns (success, message).
PresetHandler = Future<PresetApplyResult> Function(PresetApply request): Handles a Hub preset-apply request on the node.
ServiceHandler = Future<ServiceControlResult> Function(ServiceControl request): Handles a Hub service-control request on the node.
StatusProvider = Future<NodeStatus> Function(): Provides the node's current live status snapshot (CPU/mem/storage/…).

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
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_node library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyserver package

omnyserver_node library