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.
Blueprint: What a server should be.
BlueprintApplied: A blueprint was applied to a node.
BlueprintApplyRequest: Hub → node: make it so.
BlueprintApplyResult: Node → Hub: what the apply did.
BlueprintId: Identity of a blueprint (the declaration of what a server should be).
BlueprintPlanRequest: Hub → node: work out what applying this blueprint would change.
BlueprintPlanResult: Node → Hub: what the node would have to change, or did.
BlueprintRepository: Persists Blueprints.
BlueprintSource: The bytes a human actually wrote.
BroadcastEventBus: The default in-process EventBus, backed by a broadcast stream.
BuildToolsFormula: gcc and make — a node that can compile something.
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: What the Hub wants a node to be.
DesiredStateRepository: Persists the state each node is supposed to be in.
DnsUtilsFormula: nslookup — asking a node what it thinks a name resolves to.
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.
FileLedgerStore: Keeps a node's ledger on disk, one file per blueprint, under <data-dir>/blueprints/<id>.json.
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).
FormulaProvider: Serves formula:<id> resources out of the node's existing FormulaRegistry.
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.
FormulaStatusReport: One formula's answer about itself, on one node.
FormulaStatusRequest: Hub → node: report the state of the formulas this node carries.
FormulaStatusResult: Node → Hub: what each formula found when it looked at itself.
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.
Ledger: What this system put on this machine.
LedgerEntry: One resource the node has been told to manage, and how it came to be there.
LedgerStore: Where a node keeps what it has applied.
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).
MemoryLedgerStore: A LedgerStore that lives only as long as the process.
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.
NetToolsFormula: netstat and route — what is listening, and where traffic goes.
NmapFormula: nmap — what a node can see of the network around it.
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.
NodeBlueprintService: Plans and applies blueprints on a node.
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.
PackageFormula: A formula whose whole job is "make these commands exist".
PackageNames: The package that carries a formula's commands, named per package manager.
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.
ProcpsFormula: Installs the process tools — ps and top — on a node.
ProtocolErrorMessage: Either side: a protocol-level error raised during the handshake.
ProtocolVersion: The wire protocol version negotiated in the Hello handshake.
ProviderRegistry: The catalogue of resource types this node can actually handle.
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.
ResolvedBlueprint: A blueprint with its includes flattened, variables substituted and resources ordered — everything a node needs, and nothing it has to work out.
ResolvedResource: A resource after resolution, and where it came from.
Resource: One declared thing a blueprint wants on a node.
ResourceChange: One resource's line in a plan, and afterwards its line in a report.
ResourceId: What a resource is called: its type, and its name within that type.
ResourceProvider: Knows how to read and write one kind of resource on a node.
ResourceState: What a provider found when it looked at one resource on a node.
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 the node-control requests the Hub dispatches (NodeControl).
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.
BlueprintFormat: The format a blueprint was written in.
CapabilityKind: The well-known kinds of capability a node can advertise.
ChangeKind: What a plan proposes to do about one resource, or what an apply did.
Ensure: What a resource should be, as opposed to what should be done to it.
FormulaAction: The operational steps a Formula supports.
FormulaStatus: What a formula found when it looked at the thing it manages.
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

agentRestartExitCode → const int: The exit code an agent leaves with when the Hub asked it to restart.
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.
packageSpec({required String id, required String name, required String description}) → FormulaSpec: The specs of package-backed formulas share a shape: the commands they provide, and no service to start or stop.
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

BlueprintApplyHandler = Future<BlueprintApplyResult> Function(BlueprintApplyRequest request): Applies a blueprint on the node.
BlueprintPlanHandler = Future<BlueprintPlanResult> Function(BlueprintPlanRequest request): Works out what applying a blueprint would change on the node.
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.
FormulaStatusHandler = Future<FormulaStatusResult> Function(FormulaStatusRequest request): Handles a Hub formula-status 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