# aimdb-client
Internal client library for the AimX remote access protocol (v2 NDJSON wire).
## Overview
`aimdb-client` is an **internal library** that provides the Rust client
implementation for the AimX remote access protocol. It enables programmatic
connections to running AimDB instances over a transport picked at runtime via
a `scheme://` endpoint URL — Unix domain sockets (`unix://PATH` / `uds://PATH`,
or a bare path), serial (`serial://DEVICE?baud=N`), and TCP
(`tcp://HOST:PORT`, behind the `transport-tcp` feature).
**This library is used by:**
- `tools/aimdb-cli` - Command-line interface for AimDB
- `tools/aimdb-mcp` - Model Context Protocol server for LLM integration
**Not intended for direct use by application developers.** If you need to interact with AimDB, use the CLI or MCP tools instead.
## Features
- **Async Connection Management**: `AimxConnection` over the shared session engine
- **Protocol Implementation**: AimX handshake plus RPC and streaming subscriptions
- **Instance Discovery**: Automatic detection of running AimDB instances (UDS)
- **Record Operations**: List, get, set, subscribe, drain, graph introspection, query
- **Type-Safe**: Strongly typed API with serde integration
## API Overview
### Core Types
- `AimxConnection` - Main client for connecting to AimDB instances
- `InstanceInfo` - Information about discovered instances
- `RecordMetadata` - Metadata about registered records
- `ClientError` - Error types for client operations
### Main Operations
- **Discovery**: `discover_instances()`, `find_instance()`
- **Connection**: `AimxConnection::connect(endpoint)`, `connect_over(dialer)`
- **Records**: `list_records()`, `get_record()`, `set_record()`, `drain_record()`
- **Subscriptions**: `subscribe()` (returns a `Stream` of `Result<RecordUpdate, ClientError>` —
value, topic, gap count, snapshot-burst marker; a refused subscription is one `Err` item)
- **Introspection**: `graph_nodes()`, `graph_edges()`, `graph_topo_order()`, `query()`
### Discovery
Automatically scans for running AimDB instances:
- `/tmp/*.sock`
- `/var/run/aimdb/*.sock`
## Protocol
The client speaks the **AimX** wire: NDJSON (newline-delimited JSON) tagged
frames mapping onto the session engine's role-neutral message set. It declares
`PROTOCOL_VERSION` (currently `3.0`) at `hello`; compatibility is by major
version, so a pre-3.x peer is refused at the handshake.
See `docs/design/remote-access-via-connectors.md` for the architecture and
`aimdb-core/src/session/aimx/` for the codec.
## Usage Examples
This library is used internally by:
- **`tools/aimdb-cli`** - Command-line interface for interacting with AimDB instances
- **`tools/aimdb-mcp`** - Model Context Protocol server for LLM integration
See these tools for real-world usage patterns.
## Testing
```bash
# Run tests
cargo test -p aimdb-client
# Run TCP endpoint resolver tests
cargo test -p aimdb-client --no-default-features --features transport-tcp
# Start test server
cargo run --example remote-access-demo
```
## Documentation
For detailed API documentation:
```bash
cargo doc -p aimdb-client --open
```
## License
See [LICENSE](../LICENSE) file.