refactor: rename socket_path to endpoint in AimDB MCP tools#127
Draft
lxsaah wants to merge 2 commits into
Draft
Conversation
- 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.
7 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Transport-agnostic host client — pick the transport at runtime (Issue #123)
Follow-up to #39 / #122. The host-side toolset (
aimdb-client, theaimdbCLI,and
aimdb-mcp) no longer hard-codes the Unix-domain socket transport. A targetis now named by an endpoint — a
scheme://URL (or a bare path) — and thescheme 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.
What changed
aimdb-coreimpl Dialer for Box<dyn Dialer>— a boxed dialer is itself aDialer, so aruntime-selected
Box<dyn Dialer>(the resolver's return type) can be handedstraight to
run_client<D: Dialer>without a generic transport at the call site.aimdb-clientendpointmodule, split into two deliberately separate layers:parse_endpoint(&str) -> ParsedEndpoint— pure, feature-independent grammar.Recognizes
unix:///uds:///serial://DEVICE?baud=Nand 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 thematching
transport-*feature. A scheme whose transport isn't compiled in isrejected here, with a clear error distinct from "unknown scheme".
AimxConnection::connectnow takes a&strendpoint (wasimpl AsRef<Path>),resolved through the
endpointmodule. Newconnect_over(dialer)/connect_over_with_timeoutdial over an explicitDialer, bypassing resolution.transport-uds(default) gatesaimdb-uds-connectorand thediscoverymodule (a Unix-socket scan);transport-serial(off by default) gatesaimdb-serial-connector(
tokio-serial→ libudev).ClientError::UnsupportedEndpoint;ConnectionFailed.socket→endpoint;discovery::InstanceInfo.socket_path→endpoint.aimdbCLI--socket <path>flags replaced by a global--connect <endpoint>(+
AIMDB_CONNECTenv). Precedence:--connect→AIMDB_CONNECT→ auto-discovery.instance info/pingnow work over any endpoint;instance liststaysdiscovery-only. New
transport-serialfeature wiresserial://into the resolver.aimdb-mcpsocket_pathparameter renamedendpointand now accepts anyendpoint URL. Startup
--socket→--connect;AIMDB_SOCKET→AIMDB_CONNECT.endpoint.get_instance_info's result fieldsocket_path→endpoint(
discover_instanceskeepssocket_path). Newtransport-serialfeature.Examples — worked demonstrations of
--connectThe 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:
tokio-knx-connector-demoUdsServer)aimdb --connect unix:///tmp/aimdb-knx.sock record listembassy-knx-connector-demoSerialServer, USART3 / ST-LINK VCP)aimdb --features transport-serial --connect serial:///dev/ttyACM0?baud=115200 record listembassy-mqtt-connector-demoSerialServer, USART3 / ST-LINK VCP)existing KNX/MQTT connector (the builder drives any number of them).
source) is the single writer for each key, so remoterecord.setis refused —this preserves AimDB's single-writer-per-key invariant.
knx-/mqtt-connector-demo-commoncrates gained a no_std-capableserdefeature (serde derive was previously gated onstd), so the embassydemos can serialize the real demo records over serial — not a stand-in.
alongside embassy-net.
Breaking changes
AimxConnection::connect/connect_with_timeouttake&str(was a path).ClientError::ConnectionFailed.socket→endpoint;discovery::InstanceInfo.socket_path→endpoint.--socketremoved; use the global--connect(bare paths still work).socket_path→endpoint;--socket→--connect;AIMDB_SOCKET→AIMDB_CONNECT;get_instance_inforesultsocket_path→endpoint.--features transport-serial.Testing
aimdb-clienttests pass in both feature configs (defaulttransport-uds, and--no-default-features --features transport-serial); the UDS integration testsride
#![cfg(feature = "transport-uds")].-D warnings) onaimdb-client/aimdb-cli/aimdb-mcpforboth the default and serial-transport feature arms (Makefile parity).
tokio-knx-connector-demobuilds and was smoke-tested end-to-end: the UDSserver comes up even with the KNX gateway unreachable, and against it the CLI
resolved a bare path, a
unix://URL, andAIMDB_CONNECT;instance pingreported the endpoint;
record setwas correctly refused (read-only).thumbv7em-none-eabihf; the tokio demosstill build after the shared-crate serde change.