palyra-connector-core and palyra-connectors crates. The system decouples the daemon’s internal message routing logic from the platform-specific API implementations (adapters) and provides a robust supervisor to manage connector lifecycles, persistence, and reliability.
Architecture Overview
The framework follows a supervisor-adapter pattern. TheConnectorSupervisor acts as the central management node, overseeing multiple ConnectorInstanceRecord entries stored in a SQLite database.
Key Components
| Component | Role | Location |
|---|---|---|
ConnectorSupervisor | Manages lifecycle, outbox processing, and adapter dispatch. | crates/palyra-connector-core/src/supervisor.rs#18-22 |
ConnectorAdapter | Trait for platform-specific implementations (e.g., Discord, Echo). | crates/palyra-connector-core/src/supervisor.rs#18-22 |
ConnectorStore | SQLite-backed persistence for connector specs, state, and outbox. | crates/palyra-connector-core/src/storage.rs#14-17 |
ConnectorRouter | Interface used by the supervisor to push inbound events to the daemon. | crates/palyra-connector-core/src/supervisor.rs#18-22 |
Data Flow: Inbound and Outbound
The following diagram illustrates the relationship between code entities during message transit. Connector Message Pipeline Sources: crates/palyra-connector-core/src/supervisor.rs#18-22, crates/palyra-daemon/src/channels.rs#106-137Connector Protocol
The framework uses a standardized protocol for message envelopes to ensure consistency across different platforms.Message Envelopes
Outbound messages are encapsulated inOutboundMessageRequest crates/palyra-connector-core/src/protocol.rs#6-13. Key fields include:
envelope_id: A unique ULID for idempotency.conversation_id: The platform-specific channel or DM identifier.text: The raw message content.attachments: A list ofOutboundAttachmentrefs.a2ui_update: OptionalOutboundA2uiUpdatefor dynamic UI patches.
Connector Capabilities
Each connector reports its capabilities viaConnectorCapabilitySet crates/palyra-connector-core/src/protocol.rs#205-215. This allows the CLI and Web Console to determine if features like threading, reactions, or message editing are supported for a specific instance crates/palyra-cli/src/client/message.rs#51-56.
ConnectorSupervisor Lifecycle
TheConnectorSupervisor is responsible for the “Ground Truth” state of all connectors.
- Initialization: The
ChannelPlatformin the daemon initializes the supervisor with aConnectorStoreand a set ofConnectorAdapterimplementations crates/palyra-daemon/src/channels.rs#113-132. - Registration: Connectors are registered using a
ConnectorInstanceSpeccrates/palyra-connector-core/src/protocol.rs#6-13. - Liveness Monitoring: The supervisor tracks
ConnectorLiveness(Stopped, Running, Restarting, Crashed) andConnectorReadiness(Ready, MissingCredential, etc.) crates/palyra-connector-core/src/protocol.rs#110-147. - Outbox Processing: The supervisor maintains an internal outbox in SQLite. If a delivery fails with a
RetryClass::ConnectorRestartingerror, the supervisor manages the backoff and retry logic crates/palyra-connector-core/src/protocol.rs#6-13.
Echo Connector and Simulator
For testing and development, thepalyra-connectors crate includes an EchoConnectorAdapter.
Echo Connector
TheEchoConnectorAdapter crates/palyra-connectors/src/connectors/echo.rs#21-24 provides a loopback mechanism:
- It simulates message delivery without external network calls.
- It supports a
[connector-crash-once]marker in message text to simulate a single failure and subsequent retry, allowing for testing of the supervisor’s resilience logic crates/palyra-connectors/src/connectors/echo.rs#18-18. - It maintains idempotency by tracking
envelope_idin an internal mutex crates/palyra-connectors/src/connectors/echo.rs#22-22.
CLI Simulator Harness
The Palyra CLI provides commands to interact with connectors directly for diagnostics:palyra message capabilities: Queries what a connector can do crates/palyra-cli/src/args/message.rs#5-19.palyra message send: Manually dispatches a message through a specific connector instance crates/palyra-cli/src/args/message.rs#20-46.
Implementation Details
Storage Schema
TheConnectorStore manages the following entities in SQLite:
- Instances: Configuration and runtime status of connectors (
ConnectorInstanceRecord) crates/palyra-connector-core/src/storage.rs#14-17. - Outbox: Pending outbound messages (
OutboxEntryRecord) crates/palyra-connector-core/src/storage.rs#14-17. - Dead Letter Office: Messages that failed permanently after all retries (
DeadLetterRecord) crates/palyra-connector-core/src/storage.rs#14-17.
Connector Availability Tiers
Connectors are classified by their implementation maturity crates/palyra-connector-core/src/protocol.rs#75-79:- Supported: Fully functional (e.g., Discord).
- InternalTestOnly: Used for CI/CD and local dev (e.g., Echo).
- Deferred: Planned but not yet implemented (e.g., Slack, Telegram) crates/palyra-connectors/src/connectors/slack.rs#19-19.
- crates/palyra-daemon/src/channels.rs
- crates/palyra-connectors/src/lib.rs
- crates/palyra-connectors/src/connectors/echo.rs
- crates/palyra-connector-core/src/supervisor.rs
- crates/palyra-connector-core/src/protocol.rs
- crates/palyra-connector-core/src/storage.rs
- crates/palyra-cli/src/client/message.rs
- crates/palyra-cli/src/args/message.rs