Skip to content

refactor: rename socket_path to endpoint in AimDB MCP tools#127

Merged
lxsaah merged 4 commits into
mainfrom
123-transport-agnostic-host-client-climcp---connect-url-resolver
Jun 7, 2026
Merged

refactor: rename socket_path to endpoint in AimDB MCP tools#127
lxsaah merged 4 commits into
mainfrom
123-transport-agnostic-host-client-climcp---connect-url-resolver

Conversation

@lxsaah

@lxsaah lxsaah commented Jun 7, 2026

Copy link
Copy Markdown
Contributor

Transport-agnostic host client — pick the transport at runtime (Issue #123)

Follow-up to #39 / #122. The host-side toolset (aimdb-client, the aimdb CLI,
and aimdb-mcp) no longer hard-codes the Unix-domain socket transport. A target
is now named by an endpoint — a scheme:// URL (or a bare path) — and the
scheme picks the transport at connect time, the same way a record's link URL
already picks one. Adding a transport is opt-in via a Cargo feature.

# Unix-domain socket (default transport)
aimdb --connect unix:///tmp/aimdb.sock record list
aimdb --connect /tmp/aimdb.sock record list          # bare path = unix:// shorthand

# Serial / UART (requires building with --features transport-serial)
aimdb --features transport-serial \
      --connect serial:///dev/ttyACM0?baud=115200 record list

# Falls back to AIMDB_CONNECT, then UDS auto-discovery
AIMDB_CONNECT=unix:///tmp/aimdb.sock aimdb record list
aimdb record list                                    # auto-discovery

What changed

aimdb-core

  • impl Dialer for Box<dyn Dialer> — a boxed dialer is itself a Dialer, so a
    runtime-selected Box<dyn Dialer> (the resolver's return type) can be handed
    straight to run_client<D: Dialer> without a generic transport at the call site.

aimdb-client

  • New endpoint module, split into two deliberately separate layers:
    • parse_endpoint(&str) -> ParsedEndpointpure, feature-independent grammar.
      Recognizes unix:// / uds:// / serial://DEVICE?baud=N and a bare path
      (the unix:// shorthand). An unknown scheme (e.g. tcp://) is rejected here.
    • dial(&str) -> Box<dyn Dialer> — builds the concrete transport under the
      matching transport-* feature. A scheme whose transport isn't compiled in is
      rejected here, with a clear error distinct from "unknown scheme".
  • AimxConnection::connect now takes a &str endpoint (was impl AsRef<Path>),
    resolved through the endpoint module. New connect_over(dialer) /
    connect_over_with_timeout dial over an explicit Dialer, bypassing resolution.
  • Transports are opt-in features: transport-uds (default) gates
    aimdb-uds-connector and the discovery module (a Unix-socket scan);
    transport-serial (off by default) gates aimdb-serial-connector
    (tokio-serial → libudev).
  • New ClientError::UnsupportedEndpoint; ConnectionFailed.socketendpoint;
    discovery::InstanceInfo.socket_pathendpoint.

aimdb CLI

  • Per-command --socket <path> flags replaced by a global --connect <endpoint>
    (+ AIMDB_CONNECT env). Precedence: --connectAIMDB_CONNECT → auto-discovery.
  • instance info / ping now work over any endpoint; instance list stays
    discovery-only. New transport-serial feature wires serial:// into the resolver.

aimdb-mcp

  • Every tool's socket_path parameter renamed endpoint and now accepts any
    endpoint URL. Startup --socket--connect; AIMDB_SOCKETAIMDB_CONNECT.
  • Connection pool re-keyed by endpoint URL; public-mode SSRF stripping strips
    endpoint. get_instance_info's result field socket_pathendpoint
    (discover_instances keeps socket_path). New transport-serial feature.

Examples — worked demonstrations of --connect

The connector examples now stand up a remote-access server so the new client
toolset has something real to talk to, exercising both transports end-to-end:

Example Transport How to reach it
tokio-knx-connector-demo UDS (UdsServer) aimdb --connect unix:///tmp/aimdb-knx.sock record list
embassy-knx-connector-demo Serial (SerialServer, USART3 / ST-LINK VCP) aimdb --features transport-serial --connect serial:///dev/ttyACM0?baud=115200 record list
embassy-mqtt-connector-demo Serial (SerialServer, USART3 / ST-LINK VCP) same as above
  • The remote-access server is registered as a second connector alongside the
    existing KNX/MQTT connector (the builder drives any number of them).
  • All records are exposed read-only: the KNX/MQTT connector (or a sensor
    source) is the single writer for each key, so remote record.set is refused —
    this preserves AimDB's single-writer-per-key invariant.
  • The shared knx-/mqtt-connector-demo-common crates gained a no_std-capable
    serde feature (serde derive was previously gated on std), so the embassy
    demos can serialize the real demo records over serial — not a stand-in.
  • The embassy heap was bumped 32 → 48 KB to give the AimX server's JSON path room
    alongside embassy-net.

Breaking changes

  • AimxConnection::connect / connect_with_timeout take &str (was a path).
  • ClientError::ConnectionFailed.socketendpoint;
    discovery::InstanceInfo.socket_pathendpoint.
  • CLI: per-command --socket removed; use the global --connect (bare paths still work).
  • MCP: tools' socket_pathendpoint; --socket--connect;
    AIMDB_SOCKETAIMDB_CONNECT; get_instance_info result socket_pathendpoint.
  • Serial endpoints require building the CLI/MCP with --features transport-serial.

Testing

  • aimdb-client tests pass in both feature configs (default transport-uds, and
    --no-default-features --features transport-serial); the UDS integration tests
    ride #![cfg(feature = "transport-uds")].
  • Clippy clean (-D warnings) on aimdb-client / aimdb-cli / aimdb-mcp for
    both the default and serial-transport feature arms (Makefile parity).
  • tokio-knx-connector-demo builds and was smoke-tested end-to-end: the UDS
    server comes up even with the KNX gateway unreachable, and against it the CLI
    resolved a bare path, a unix:// URL, and AIMDB_CONNECT; instance ping
    reported the endpoint; record set was correctly refused (read-only).
  • Both embassy demos cross-compile to thumbv7em-none-eabihf; the tokio demos
    still build after the shared-crate serde change.

lxsaah added 2 commits June 7, 2026 11:18
- Updated CLI argument from `--socket` to `--connect` for specifying the AimDB connection endpoint.
- Changed all references in the codebase from `socket_path` to `endpoint`, including in parameter structures and connection logic.
- Updated documentation and comments to reflect the new terminology and usage of endpoint URLs (e.g., `unix://PATH`, `serial://DEVICE?baud=N`).
- Ensured backward compatibility by replacing environment variable `AIMDB_SOCKET` with `AIMDB_CONNECT`.
…components

- Updated InstanceInfo struct to use `endpoint` instead of `socket_path`.
- Adjusted all related code in discovery, CLI, and MCP tools to reflect this change.
- Enhanced documentation to clarify endpoint usage, supporting various connection schemes.
- Added serial remote-access server support in embassy and MQTT connector demos.
- Updated dependencies in Cargo.toml files to include new features for serial transport.
- Ensured compatibility with serde for shared types in no_std environments.
@lxsaah lxsaah linked an issue Jun 7, 2026 that may be closed by this pull request
7 tasks
@lxsaah lxsaah self-assigned this Jun 7, 2026
@lxsaah lxsaah added the 🏗️ core Core engine work label Jun 7, 2026
@lxsaah lxsaah marked this pull request as ready for review June 7, 2026 19:41
@lxsaah lxsaah merged commit 5fa2013 into main Jun 7, 2026
9 checks passed
@lxsaah lxsaah deleted the 123-transport-agnostic-host-client-climcp---connect-url-resolver branch June 7, 2026 19:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

🏗️ core Core engine work

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Transport-agnostic host client + cli/mcp --connect <url> resolver

1 participant