Bi-directional connector trait

[lxsaah]

Implement Bidirectional Connector Trait Enhancement

Summary

Extend the Connector trait to support bidirectional data flow, enabling connectors to both publish data (outbound) and subscribe to external data sources (inbound). This unblocks multiple connector implementations including KNX, MQTT subscribe, Kafka consumers, and WebSocket.

Full Design: See 012-M5-bidirectional-connector-trait.md

Motivation

Currently, connectors only support outbound data flow (AimDB → External System). Many protocols require inbound support:

• KNX: Listen to building automation bus telegrams
• MQTT: Subscribe to broker topics
• Kafka: Consume from topics
• WebSocket: Receive messages

This enhancement enables AimDB to act as both producer and consumer in IoT/edge architectures.

Key Design Decisions

✅ Stream Trait: Use futures-core::Stream (minimal, standard, no_std compatible)
✅ Embassy Support: Implement ChannelStream adapter (~30 lines) for unified API
✅ Breaking Change: Replace .link() with .link_from() / .link_to() for clarity
✅ Backward Compat: None needed (pre-1.0 project)

Implementation Tasks

Phase 1: Core Infrastructure (Week 1)

• Add futures-core dependency to aimdb-core
• Add Connector::subscribe() method with default empty stream implementation
• Add InboundConnectorLink struct for type erasure
• Add ChannelStream adapter in aimdb-embassy-adapter/src/stream.rs
• Unit tests

Phase 2: Builder API (Week 1-2)

• Remove .link() method from RecordRegistrar
• Implement .link_from() → InboundConnectorBuilder
• Implement .link_to() → OutboundConnectorBuilder
• Add validation (buffer required, deserializer required)
• Unit tests

Phase 3: Task Spawning (Week 2)

• Add AimDb::producer<T>() method
• Extend TokioAdapter::spawn_connector_tasks() for inbound
• Extend EmbassyAdapter::spawn_connector_tasks() with ChannelStream
• Integration tests

Phase 4: MQTT Validation (Week 2-3)

• Implement subscribe() in Tokio MQTT connector
• Implement subscribe() in Embassy MQTT connector
• Add MQTT subscribe example
• End-to-end tests

Phase 5: Documentation (Week 3)

• API documentation with examples
• Connector author guide (ChannelStream usage)
• Migration guide (.link() → .link_to())
• Update all examples

Success Criteria

• ✅ MQTT connector supports both publish and subscribe
• ✅ Same Connector trait works on Tokio and Embassy
• ✅ All tests pass (unit, integration, end-to-end)
• ✅ Documentation complete with examples
• ✅ Examples updated to use .link_to() / .link_from()

Timeline

Target: 2-3 weeks
Priority: P0 (blocking KNX, MQTT subscribe, Kafka)

Related

• Design Doc: 012-M5-bidirectional-connector-trait.md
• Blocked Issues: KNX Connector, MQTT Subscribe, Kafka Consumer
• Related: aimdb-knx-connector-design.md Section 8