omnyserver_client_web library
OmnyServer for the browser: the REST client and the domain model it decodes.
The browser-safe subset of the package. A web dashboard imports this,
never omnyserver.dart or omnyserver_hub.dart, which reach dart:io —
and that distinction is load-bearing rather than stylistic: dart2js emits
no output at all for an entrypoint whose graph touches an unsupported SDK
library, so a stray import is not a compile error but a silently empty build.
test/unit/web_barrel_dart_io_free_test.dart walks this barrel's import graph
and fails if anything creeps back in.
What you get:
- HubApiClient — the same client the CLI drives the Hub with, so the
dashboard exercises exactly the public API surface any other client does.
In a browser it sends with
fetch; inject an ApiTransport to drive it against a fake Hub in tests. - The entities the API returns — NodeDescriptor, NodeStatus (with
CpuInfo, MemoryInfo, StorageDevice, ProcessInfo), PlatformInfo,
NodeCapabilities, Preset, FormulaResult, OmnyEvent, AuditEntry —
decoded with the very
fromJsonthe Hub encodes with, so there is no second, drifting copy of the wire format in the web app.
Two things the browser does not get, and cannot:
- TLS options. The browser owns its TLS stack: a self-signed Hub certificate has to be trusted at the OS or browser level, and there is no in-page bypass to offer.
PlatformInfo.local(). A node runs on a machine; a page is a client of one. It throws.
The Hub must allow the app's origin (hub start --cors-origin …) or the
browser blocks every response before this code sees it.
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.
- ApiResponse
- A raw HTTP response: the status and the undecoded body.
- ApiTransport
-
One HTTP round-trip, abstracted away from
dart:io. - AuditEntry
- An immutable record of a security- or operationally-relevant action, for the audit trail (who did what, to which target, with what outcome).
- Capability
-
A single detected capability of a node, optionally with a version and
free-form details (e.g. the GPU model for
cuda). - 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.
- CpuInfo
- CPU utilisation snapshot for a node.
- 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).
- Drift
- How far a node has drifted from what it was declared to be — the wire form of a Reconciliation.
- ErrorCodes
-
Stable, machine-readable error codes carried in
errorcontrol messages and surfaced on OmnyServerExceptions. - FormulaFinished
- A formula run finished on a node.
- FormulaId
-
Identity of a formula (an operational procedure such as
dockerordart). - 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.
- 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.
- HubApiClient
- A thin REST client for the Hub HTTP API, used by the CLI's operational commands — and by the web dashboard — so both exercise exactly the same public API surface as any other client.
- 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.
- MemoryInfo
- Memory utilisation snapshot for a node (bytes).
- MetricPoint
- One node's resource usage at an instant — the chartable projection of a NodeStatus.
- 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.
- NodeId
-
Stable identity of a node, used by the Hub and clients to address it
(instead of a
host:port). Equality is by value. - 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.
- 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.
- 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).
- 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.
- 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.
- 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).
- 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.
- OperationStatus
- Where an Operation has got to.
- ServiceStatus
- The lifecycle state of an OS-managed service.
Constants
- omnyServerVersion → const String
-
The canonical OmnyServer package version (kept in sync with
pubspec.yaml).
Exceptions / Errors
- AuthException
- Authentication failed: credentials missing, malformed or rejected.
- AuthorizationException
- The authenticated principal is not permitted to perform the action.
- HubApiException
- Thrown when a Hub API request fails.
- 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.