Skip to content

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

Draft
lxsaah wants to merge 2 commits into
mainfrom
123-transport-agnostic-host-client-climcp---connect-url-resolver
Draft

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

Conversation

@lxsaah
Copy link
Copy Markdown
Contributor

@lxsaah lxsaah commented Jun 7, 2026

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant