Module remote 

Remote access subsystem for AimDB (AimX protocol)

Provides introspection and management APIs over Unix domain sockets, enabling external tools (CLI, dashboards, MCP adapters) to interact with running AimDB instances.

Protocol

AimX uses NDJSON (newline-delimited JSON) tagged frames over a session transport (Unix domain sockets via aimdb-uds-connector, serial via aimdb-serial-connector). The envelope codec lives in session::aimx (feature connector-session). Compatibility is by major version — see PROTOCOL_VERSION and version_compatible.

Security

• Read-only by default: No writes unless explicitly enabled
• UDS permissions: Primary security mechanism (file permissions)
• Optional auth tokens: Additional authentication layer
• Per-record write permissions: Explicit opt-in required

Usage

Remote access is registered like any other connector — via with_connector using aimdb_uds_connector::UdsServer (this replaced the former AimDbBuilder::with_remote_access(config)). Illustrative (not compiled: the connector lives in a downstream crate aimdb-core cannot depend on):

use aimdb_core::remote::{AimxConfig, SecurityPolicy};
use aimdb_uds_connector::UdsServer;

let config = AimxConfig::uds_default()
    .socket_path("/var/run/aimdb/aimdb.sock")
    .security_policy(SecurityPolicy::ReadOnly)
    .max_connections(16)
    .max_subs_per_connection(32);

let (db, runner) = AimDbBuilder::new()
    .runtime(tokio_adapter)
    .with_connector(UdsServer::from_config(config))
    .build()
    .await?;

Structs

AimxConfig

Configuration for AimX remote access

ErrorObject

Error object in response

Event

Event message from server (subscription push)

HelloMessage

Client hello message

QueryHandlerParams

Parameters for the type-erased query handler.

QueryRecord

One row of a record.query result — the canonical shape every transport shares.

RecordMetadata

Metadata about a registered record type

Request

Request message from client

WelcomeMessage

Server welcome message

Enums

RemoteError

Error type for remote access operations

Response

Response message from server

SecurityPolicy

Security policy for remote access

Constants

PROTOCOL_VERSION

Version of the AimX wire protocol spoken by this crate.

QUERY_ALL_PATTERN

The pattern a record.query with no name resolves to: every record, at every depth.

VERSION_PARAM

Query-parameter name a WebSocket client uses to declare its PROTOCOL_VERSION at the HTTP upgrade. The socket transports gate the version inside the hello handshake, but a browser cannot set custom headers on the WebSocket handshake and the WS server runs reads_hello:false, so the WS upgrade carries the version in the URL instead (…/ws?v=3.0) and the server refuses an incompatible/absent one before the socket opens. See ws_url_with_version.

Functions

topic_leaf

The leaf (entity) segment of a record key — the trailing component after the last separator. Both . and / are treated as delimiters, since keys use either convention (temp.vienna or sensors/temp/vienna), and both yield vienna. Servers report this as a record’s entity, which identifies the node only where the leaf is the node: station.17.temperature yields temperature, not 17.

version_compatible

Whether a peer advertising their_version is wire-compatible with this crate’s PROTOCOL_VERSION.

ws_url_with_version

Append this crate’s PROTOCOL_VERSION as the VERSION_PARAM query parameter to a WebSocket upgrade url, joining with & if url already carries a query string and ? otherwise. Every first-party WS client dialer routes its URL through this so the server’s upgrade-time gate sees a version; keeping the NAME=VALUE contract here means the reader (the server) and the writers (the dialers) never drift.

Type Aliases

QueryHandlerFn

Type-erased query handler registered by aimdb-persistence via Extensions.

RemoteResult

Result type for remote operations