omnyshell_hub library

Classes

ActiveSessionDetachRequest: Client → Hub: detach an active (attached) session on nodeId from another connection — e.g. when a full-screen program owns the original terminal. sessionRef is an id/short-id/prefix, or empty to target the caller's sole active session. Correlated by requestId.
ActiveSessionDetachResponse: Hub → Client: the result of an active-session detach. Correlated by requestId.
AuditLog: A bounded, in-memory audit log of Hub security events.
AuditRecord: A single audit entry recording a security-relevant Hub event.
Authenticator: Validates a Credential and resolves it to a Principal.
AuthFail: Failed authentication.
AuthOk: Successful authentication, carrying the resolved identity and a session token bound to this connection.
AuthorizedKey: A single authorized identity: a principal, the public key that proves it, and the roles it is granted.
AuthorizedKeysStore: An in-memory authorized_keys-style trust store consulted by PublicKeyAuthenticator.
Authorizer: Decides whether an authenticated Principal may open a session on a node.
AuthRequest: A login attempt presenting a credential.
CertGenerator: Generates the TLS certificate material an OmnyShell Hub needs to run.
CertificateIdentity: Extracts a stable public-key identity from an X.509 certificate.
Channel: One logical, bidirectional stream multiplexed over a connection.
ChannelClose: Tear down a channel.
ChannelEof: Half-close a stream (typically stdin) on the channel.
ChannelExit: Node → Client: the process exited.
ChannelId: A logical channel identifier, scoped to a single physical connection.
ChannelMultiplexer: Multiplexes logical Channels over a single OmnyShellConnection.
ChannelResize: Resize the terminal of an interactive session.
ChannelSignal: Deliver a POSIX signal to the session's process.
ChannelWindow: Backpressure credit grant for a stream on a channel.
Clock: Time source used throughout OmnyShell so tests can fix now.
CompositeAuthenticator: Combines several Authenticators, trying each in order until one succeeds.
ControlFrame: A control message frame (carried as a WebSocket text frame).
ControlMessage: Base class for every structured control message.
Credential: A credential presented during the authentication handshake.
CredentialProvider: Produces the AuthRequest a node or client sends in response to the Hub's challenge hello.
CredentialStore: On-disk store of Hub logins, keyed by Hub URL, with a remembered default.
DataFrame: A binary stream-data frame (carried as a WebSocket binary frame) with a fixed 10-byte header followed by the raw payload bytes.
DetachedSessionInfo: A user-facing view of a detached session living in a node's in-memory registry, as returned by the list API and relayed through the Hub.
DetachedSessionKillRequest: Client → Hub: terminate the caller's detached session sessionRef (an unambiguous id or prefix) on nodeId. Correlated by requestId.
DetachedSessionKillResponse: Hub → Client: the result of a detached-session kill. Correlated by requestId.
DetachedSessionsRequest: Client → Hub: list the caller's detached sessions on nodeId. Correlated to the response by requestId (a connection-level request/response RPC).
DetachedSessionsResponse: Hub → Client: the caller's detached sessions. Correlated by requestId.
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 OmnyShellExceptions.
FrameCodec: Encodes and decodes OmnyShellFrames to and from WebSocket events.
GeneratedCertificates: The paths of the TLS files produced by CertGenerator.generate.
HeartbeatMonitor: Watches node liveness and reports nodes that have stopped heartbeating.
Hello: First frame after the WebSocket upgrade. The Hub sends hello with a single-use nonce; the peer replies with its role and capabilities.
HubBroker: The brain of the Hub: authenticates peers, registers nodes, authorizes and brokers sessions, and relays session bytes between clients and nodes.
HubConfig: Configuration for an OmnyShellHub.
MachineId: Reads a stable, per-machine identifier provided by the operating system.
NodeActiveSessionDetach: Hub → Node: detach the principal's active session sessionRef.
NodeActiveSessionDetachResponse: Node → Hub: the result of an active-session detach. Correlated by requestId.
NodeCapabilities: What a node can do, advertised to the Hub after registration and relayed to clients during discovery.
NodeCapabilitiesMessage: Node → Hub: advertises capabilities after registration.
NodeDescriptor: A node's public description as registered with the Hub and returned by discovery (nodes list). Combines identity, platform, operator labels and advertised capabilities.
NodeDetachedSessionKillRequest: Hub → Node: terminate the principal's detached session sessionRef.
NodeDetachedSessionKillResponse: Node → Hub: the result of a detached-session kill. Correlated by requestId.
NodeDetachedSessionsRequest: Hub → Node: list the principal's detached sessions. Correlated by requestId.
NodeDetachedSessionsResponse: Node → Hub: the principal's detached sessions. Correlated by requestId.
NodeHeartbeat: Node → Hub: periodic liveness signal with a monotonic sequence number.
NodeHeartbeatAck: Hub → Node: acknowledges a heartbeat.
NodeId: Stable identity of a node, used by clients to address it (instead of a host:port). Equality is by value.
NodeListRequest: Client → Hub: requests the list of nodes the client may see.
NodeListResponse: Hub → Client: the discovered nodes.
NodeRegister: Node → Hub: registers the node's identity and platform.
NodeRegistered: Hub → Node: confirms registration.
NodeRegistry: Tracks the nodes registered with the Hub and answers discovery queries.
NodeSessionDetach: Hub → Node: detach the session on the node-side channel, on behalf of principal. Mirrors SessionDetachRequest across the relay.
NodeSessionDetached: Node → Hub: the session was detached and now lives in the node registry.
NodeSessionOpen: Hub → Node: instructs the node to start a session on a node-side channel.
NodeSessionOpened: Node → Hub: the node accepted and started the session.
NodeSessionRejected: Node → Hub: the node refused the session.
NodeSessionScreenRequest: Hub → Node: fetch the current screen snapshot of the principal's session sessionRef. Correlated by requestId.
NodeSessionScreenResponse: Node → Hub: the current screen snapshot of a session. The replayable bytes (the same a resume would paint) are base64-encoded in screenBase64. Correlated by requestId.
NodeTunnelConnect: Hub → exposer (node or client): a public connection arrived; adopt channel, dial targetHost:targetPort, and bridge bytes. Reply with NodeTunnelConnected or NodeTunnelConnectFailed.
NodeTunnelConnected: Exposer → Hub: the target was dialed; the Hub may relay bytes on channel.
NodeTunnelConnectFailed: Exposer → Hub: the target dial failed; the Hub closes the public socket.
OmnyShellConnection: A duplex, frame-oriented link between two OmnyShell peers.
OmnyShellFrame: A decoded unit travelling over a connection: either a structured control message (ControlFrame) or a binary stream payload (DataFrame).
OmnyShellHub: An embeddable OmnyShell Hub: a TLS WebSocket endpoint wired to a HubBroker.
OmnyUid: A deterministic, globally-stable identifier for a node or a hub.
Ping: Application-level keepalive request, used to measure round-trip latency and detect half-open connections.
PlatformInfo: Describes the operating system and architecture a node runs on, advertised to clients during discovery and shown by the :info local command.
Pong: Reply to a Ping.
PortRange: An inclusive TCP port range [start, end].
Principal: An authenticated identity, as resolved by an Authenticator.
PrincipalId: Identity of an authenticated principal (a user or a node account) as known to the Hub. Equality is by value.
ProtocolError: A connection- or channel-level error.
PtySpec: Requested pseudo-terminal geometry for an interactive shell.
PublicKeyAuthenticator: Authenticates PublicKeyCredentials against an AuthorizedKeysStore.
PublicKeyCredential: An Ed25519 public-key credential: the client proves possession of the private key by signing the connection challenge.
PublicKeyCredentialProvider: A CredentialProvider that signs the connection nonce with an Ed25519 private key.
RegisteredNode: A node currently registered with the Hub, with its live connection and liveness bookkeeping.
RoleBasedAuthorizer: A role-based Authorizer with a small, predictable policy:
Session: A domain view of a brokered session: who opened it, on which node, in what mode, and its current state and exit code.
SessionDetached: Hub → Client: the session was detached; resume it later by shortId.
SessionDetachRequest: Client → Hub: detach the live session on channel, keeping the node-side PTY/shell/processes running. Optional timeoutSeconds schedules automatic cleanup; null keeps the session indefinitely.
SessionId: Unique identity of a brokered session, minted by the Hub when a session is opened. Equality is by value.
SessionOpen: Client → Hub: opens a session on a node over a new client channel.
SessionOpened: Hub → Client: the session is open.
SessionRejected: Hub → Client (or Node → Hub via NodeSessionRejected): the session could not be opened.
SessionRoute: A live route bridging a client-side channel to a node-side channel for one brokered session. The Hub relays bytes by rewriting the channel id between the two ends.
SessionRouter: Holds the Hub's live session routes with O(1) lookup from either end and by session id.
SessionScreenRequest: Client → Hub: fetch the current screen snapshot of the caller's session sessionRef (active or detached) on nodeId, without attaching to it. Correlated by requestId.
SessionScreenResponse: Hub → Client: the current screen snapshot of a session. Correlated by requestId.
ShellBackend: Starts ShellSessions on a node in response to authorized session opens.
ShellRequest: A request to start a process or interactive shell on a node.
ShellSession: A running process or shell on the node, with byte streams wired to the session channel.
StoredSession: A persisted login to a single Hub.
SystemClock: The default Clock, backed by the system wall clock (UTC).
TokenAuthenticator: Authenticates TokenCredentials against an in-memory token store.
TokenCredential: A bearer-token credential, validated against a token store. Relies on TLS for secrecy in transit.
TokenCredentialProvider: A CredentialProvider that presents a bearer token.
TokenGrant: A token and the identity it grants.
TunnelCloseRequest: Client → Hub: close the caller's tunnel tunnelRef (a full id or unambiguous prefix). Correlated by requestId.
TunnelCloseResponse: Hub → Client: the result of a tunnel close. Correlated by requestId.
TunnelInfo: A user-facing view of an active TCP tunnel held by the Hub, as returned by the list API and relayed to the owning client.
TunnelListRequest: Client → Hub: list the caller's active tunnels. Correlated by requestId.
TunnelListResponse: Hub → Client: the caller's active tunnels. Correlated by requestId.
TunnelOpened: Hub → Client: the tunnel is open and listening. Correlated by requestId.
TunnelOpenRequest: Client → Hub: open a tunnel that exposes targetHost:targetPort (reachable by nodeId, or the requesting client's own machine when nodeId is the @local sentinel) on a public Hub port. When publicPort is set the Hub validates it against its configured range; otherwise the Hub allocates a free port in range. Correlated by requestId.
TunnelRegistration: A live tunnel held by the Hub: a public serverSocket whose accepted connections are bridged to targetHost:targetPort over the exposer's connection.
TunnelRegistry: The Hub's table of active tunnels plus the set of public ports in use, so allocation and specific-port validation are O(1).
TunnelRejected: Hub → Client: the tunnel was refused. Correlated by requestId.
UidComputer: Computes deterministic OmnyUids from identity material.
UidResolution: The outcome of resolving an entity's UID against its persisted value.
UidStore: Persists an entity's UID under ~/.omnyshell/<fileName> and detects changes.
WsServerEndpoint: A Hub-side TLS WebSocket listener.

Enums

DataOpcode: The stream a binary data frame belongs to, encoded as the msgType byte of the data-frame header.
SessionMode: How a session runs on the node.
SessionState: Lifecycle state of a session as tracked by the Hub.
ShellFamily: The command-language family of a node's interactive shell.

Constants

kMinProtocolVersion → const int: The lowest protocol version this build can interoperate with.
kProtocolVersion → const int: The wire protocol version implemented by this package.
omnyShellVersion → const String: The canonical OmnyShell package version (kept in sync with pubspec.yaml).

Functions

isProtocolCompatible(int remoteVersion, {int? remoteMin}) → bool: Whether a peer advertising remoteVersion (with optional remoteMin) is compatible with this build.
newId() → String: Generates a new globally-unique identifier (UUID v4).
newSecureToken([int byteLength = 32]) → String: Returns byteLength cryptographically secure random bytes encoded as a URL-safe, unpadded base64 string.
shortId(String id, [int length = 8]) → String: Derives a short, human-friendly handle from a full id.

Typedefs

ControlDecoder = ControlMessage Function(int? channelId, Map<String, dynamic> data): Decodes a control-message payload (the envelope d) for a registered type.
OnConnection = void Function(WebSocketConnection connection): Called for every accepted WebSocket connection.

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.
ChannelException: A logical channel was closed or referenced after teardown.
NodeUnavailableException: The requested node is unknown or offline.
OmnyShellException: Base type for every expected, classified failure raised by OmnyShell.
OmnyShellTimeoutException: An operation exceeded its deadline.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
SessionRejectedException: A session could not be opened (rejected by the Hub or node).
TransportException: The underlying transport failed or closed unexpectedly.
TunnelRejectedException: A tunnel could not be opened (rejected by the Hub).

omnyshell_hub library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyshell package

omnyshell_hub library