Connector framework¶
This chapter captures the requirements for taktora-connector: a framework
that connects taktora-executor applications to external protocols (MQTT, OPC UA,
gRPC, fieldbus) through a controlled boundary, so messy network code lives
outside the application’s deterministic core.
The decomposition is two-tier:
Top-level umbrella feature — Connector framework (FEAT_0030) — peer to PLC runtime heart on iceoryx2 (FEAT_0010). Taktora-connector is a general-purpose framework usable by any taktora-executor consumer; it is not bound to the PLC use case.
Capability-cluster sub-features — one per architectural concern, each
:satisfies:Connector framework (FEAT_0030).Requirements — concrete shall-clauses that
:satisfies:a capability-cluster feature.
This round covers the framework core plus an MQTT reference connector
(rumqttc-backed). OPC UA, gRPC, and Beckhoff ADS connectors are
deferred to follow-on specs that will reuse the same five contracts.
Each capability cluster lives on its own page (see the toctree): envelope transport (Envelope transport (FEAT_0031)), codec abstraction (Codec abstraction (FEAT_0032)), the connector trait and routing (Connector trait and routing (FEAT_0033)), connection lifecycle (Connection lifecycle (FEAT_0034)), process-boundary deployments (Process boundary deployments (FEAT_0035)), connector cycle telemetry (Connector cycle telemetry (FEAT_0038)), host wiring and builder (Host wiring and builder (FEAT_0037)), and the reference connectors — MQTT (MQTT reference connector (FEAT_0036)), EtherCAT (EtherCAT reference connector (FEAT_0041)), Zenoh (Zenoh reference connector (FEAT_0042)), and CAN (CAN (SocketCAN) reference c... (FEAT_0046)). The deliberately rejected anti-goals, the umbrella-level traceability tables, and the safety refinements live on Cross-cutting and anti-goals.
Top-level umbrella¶
A Rust framework that bridges taktora-executor applications to external
protocols through a typed envelope carried over iceoryx2 shared memory.
The framework provides five contracts — envelope, codec, routing, health,
lifecycle — that every protocol connector instantiates as a plugin
(in-app side) and a gateway (out-of-app side). Both halves are
taktora-executor Deployment chooses whether the gateway runs as a tokio task in-process alongside the plugin host, or as a separate gateway binary. The envelope contract is identical either way; only process-startup wiring differs. This umbrella is a peer of PLC runtime heart on iceoryx2 (FEAT_0010) “PLC runtime heart”; the
connector framework is a general-purpose mechanism, not PLC-specific.
Fieldbus integration interface (FEAT_0023) “Fieldbus integration interface” is later expected to
|
Requirements at a glance¶
ID |
Title |
Status |
Satisfies |
|---|---|---|---|
Envelope transport |
open |
||
Codec abstraction |
open |
||
Connector trait and routing |
open |
||
Connection lifecycle |
open |
||
Process boundary deployments |
open |
||
MQTT reference connector |
open |
||
Host wiring and builder |
open |
||
Connector cycle telemetry |
open |
||
EtherCAT reference connector |
open |
||
Zenoh reference connector |
open |
||
Zenoh pub/sub |
open |
||
Zenoh queries |
open |
||
Zenoh session topology and health |
open |
||
CAN (SocketCAN) reference connector |
open |
||
CAN frame transport (classical + FD) |
open |
||
Multi-interface gateway and per-channel filtering |
open |
||
Bus health, error frames, and reconnect |
open |
||
ConnectorEnvelope is a POD type |
open |
||
Per-channel max payload size |
approved |
||
Sequence number monotonically increasing |
implemented |
||
Timestamp recorded at send |
implemented |
||
Correlation id is a passive carrier |
implemented |
||
Zero-copy publish via iceoryx2 loan |
implemented |
||
One iceoryx2 service per channel direction |
implemented |
||
PayloadCodec trait |
implemented |
||
Codec is a generic parameter on connectors |
open |
||
JsonCodec is the default codec |
implemented |
||
Codec encode error variant |
open |
||
Codec decode error variant |
open |
||
Connector trait |
open |
||
ChannelDescriptor carries typed routing |
implemented |
||
Routing is a marker trait with bounds |
open |
||
create_writer / create_reader return concrete handles |
open |
||
Connector ships its own routing struct |
approved |
||
ConnectorHealth state machine |
approved |
||
subscribe_health returns a Channel of HealthEvent |
approved |
||
ReconnectPolicy trait |
open |
||
ExponentialBackoff default policy |
open |
||
HealthEvent emitted on every transition |
approved |
||
Stack-internal-reconnect connectors emit health uniformly |
approved |
||
Same envelope contract for both deployments |
approved |
||
In-process gateway is a tokio task |
open |
||
Separate-process gateway is a self-contained binary |
open |
||
Clean exit on SIGINT / SIGTERM on both sides |
open |
||
No app↔gateway control-plane envelopes |
approved |
||
MqttConnector implements Connector |
open |
||
MqttRouting carries topic, qos, retained |
open |
||
QoS 0 and 1 supported |
open |
||
Retained-message publish supported |
open |
||
Wildcard subscriptions supported |
open |
||
Username/password authentication |
open |
||
TLS is optional via cargo feature |
open |
||
MQTT 3.1.1 baseline |
open |
||
Tokio sidecar inside the gateway crate |
open |
||
Bridge channels are bounded |
open |
||
Outbound bridge saturation surfaces as BackPressure |
open |
||
Inbound bridge saturation drops frames and signals Degraded |
open |
||
Wire-round duration statistics |
draft |
||
Working-counter quality counter |
draft |
||
Freshness and staleness statistics |
draft |
||
Connector statistics query API |
draft |
||
Cycle-phase wait (slack) statistics |
draft |
||
Connector push fault semantics |
draft |
||
ConnectorHost builder API |
approved |
||
ConnectorGateway builder API |
approved |
||
Host registers connector items with the executor |
approved |
||
Optional Observer adapter for tracing |
open |
||
NO request/response matching by the framework |
rejected |
||
NO app↔gateway control plane |
rejected |
||
NO persistent outbox or durable buffering |
rejected |
||
NO schema/contract enforcement across the boundary |
rejected |
||
NO protocol-portable Channel<T> |
rejected |
||
NO multi-broker / multi-tenant gateway |
rejected |
||
NO supervision / panic recovery |
rejected |
||
EthercatConnector implements Connector |
approved |
||
EthercatRouting carries SubDevice and PDO addressing |
implemented |
||
Single MainDevice per gateway instance |
approved |
||
Bus reaches OP before serving traffic |
approved |
||
Static PDO mapping per SubDevice |
approved |
||
PDO mapping applied during PRE-OP to SAFE-OP transition |
implemented |
||
Cycle time configurable with millisecond resolution |
implemented |
||
Missed cycle ticks are skipped not queued |
implemented |
||
Distributed Clocks bring-up is opt-in |
approved |
||
Working-counter-based health policy |
implemented |
||
Working-counter mismatch degrades health |
approved |
||
Tokio sidecar contained inside the connector crate |
approved |
||
Bridge channels are bounded |
approved |
||
Outbound bridge saturation surfaces as BackPressure |
approved |
||
Inbound bridge saturation drops PDUs and signals Degraded |
implemented |
||
Linux raw socket required on gateway host |
approved |
||
Outbound payload written to PDI bit slice per routing |
implemented |
||
Inbound payload read from PDI bit slice per routing |
implemented |
||
Per-channel routing registry on the gateway |
approved |
||
Asymmetric working counter declared per SubDevice |
implemented |
||
Distributed Clocks cycle path uses tx_rx_dc |
open |
||
Bus-level recovery on cycle error |
implemented |
||
Reconnect policy factory in connector options |
implemented |
||
Health transitions during recovery |
implemented |
||
ZenohConnector implements Connector |
approved |
||
ZenohRouting carries key_expr and pub/sub QoS fields |
open |
||
JsonCodec is the default codec for Zenoh |
approved |
||
Tokio sidecar contained inside the Zenoh connector crate |
implemented |
||
Zenoh bridge channels are bounded |
approved |
||
Outbound bridge saturation surfaces as BackPressure |
approved |
||
Inbound bridge saturation drops samples and signals Degraded |
open |
||
Zenoh zero-copy publish via iceoryx2 loan |
approved |
||
Zenoh gateway is byte-only on the inbound publish path |
approved |
||
ZenohConnector exposes create_querier and create_queryable |
implemented |
||
ZenohQuerier maps QueryId to envelope correlation_id |
approved |
||
ZenohQueryable correlates replies via correlation_id |
implemented |
||
Multi-reply per query supported |
implemented |
||
Reply stream end-of-stream framed in payload |
approved |
||
Query timeout sourced from options, overridable per-querier |
approved |
||
terminate(id) finalizes the upstream zenoh::Query |
implemented |
||
Codec applied to Q on send and to R on reply |
approved |
||
Reply-side inbound saturation drops chunks and signals Degraded |
open |
||
Zenoh session mode is a config knob |
implemented |
||
NO ReconnectPolicy on Zenoh session loss |
rejected |
||
HealthEvent emitted on every Zenoh session transition |
implemented |
||
Connect and listen locators surfaced to zenoh::Config |
open |
||
zenoh-integration cargo feature gates the real zenoh dep |
implemented |
||
MockZenohSession ships unfeature-gated |
implemented |
||
Linux, macOS, and Windows are supported host operating systems |
implemented |
||
CanConnector implements Connector |
approved |
||
CanRouting carries iface, can_id, mask, kind, fd_flags |
approved |
||
Linux is the supported host OS for real I/O |
open |
||
socketcan-integration cargo feature gates the real socketcan dep |
approved |
||
MockCanInterface ships unfeature-gated |
approved |
||
Tokio sidecar contained inside the CAN connector crate |
approved |
||
CAN bridge channels are bounded |
approved |
||
Outbound bridge saturation surfaces as BackPressure |
approved |
||
Inbound bridge saturation drops frames and signals Degraded |
open |
||
Classical CAN frames supported |
approved |
||
CAN-FD frames supported |
approved |
||
Channel payload sizing keyed on frame kind |
open |
||
Outbound payload serialised to socketcan frame |
approved |
||
Inbound gateway is byte-only on the publish path |
approved |
||
CAN ID extended flag preserved end-to-end |
approved |
||
Multiple interfaces per gateway |
approved |
||
Routing identifies the interface |
open |
||
Per-interface filter is the union of channel masks |
approved |
||
Filter recomputed on channel add/remove |
approved |
||
Inbound demux to all matching readers |
approved |
||
Per-iface routing registry has stable iteration order |
approved |
||
ConnectorHealth aggregates per-iface state via worst-of |
approved |
||
Error frames consumed internally |
approved |
||
error-passive transitions to Degraded |
approved |
||
bus-off transitions to Down and triggers reconnect |
approved |
||
ReconnectPolicy reused; ExponentialBackoff default |
approved |
||
HealthEvent emitted on every transition |
approved |
||
Error frames not exposed to plugin |
approved |
||
NO DBC parsing or typed signal extraction in taktora-connector-can |
rejected |
||
NO ISO-TP or J1939 support in taktora-connector-can |
rejected |
||
NO CAN-XL support |
rejected |
||
NO plugin-visible error-frame channel |
rejected |
||
NO can-restart-ms management from the gateway |
rejected |
||
SAFE-OP to OP transition exchanges cyclic process data |
implemented |
||
Bring-up failure is observable via health |
implemented |
||
Master programs the SubDevice SM-watchdog registers |
implemented |
||
Health subscriptions are independent broadcast streams |
implemented |
||
Operator-declared startup SDOs applied before PDO assignment |
implemented |
- Envelope transport
- Codec abstraction
- Connector trait and routing
- Connection lifecycle
- Process boundary deployments
- MQTT reference connector
- EtherCAT reference connector
- Host wiring and builder
- Zenoh reference connector
- CAN (SocketCAN) reference connector
- Connector cycle telemetry
- Cross-cutting and anti-goals