palyra-connectors crate provides a provider-neutral runtime for managing external communication platforms (e.g., Discord, Slack). It handles message persistence, outbound queuing with retry logic, dead-lettering, and media artifact management via a centralized supervisor.
Architecture Overview
The connector subsystem is divided into a generic Core runtime and specific Provider adapters. TheConnectorSupervisor acts as the orchestrator, utilizing a ConnectorStore for persistence and a ConnectorRouter to dispatch inbound messages to the daemon’s gateway.
System Entity Mapping
The following diagram maps high-level connector concepts to their specific Rust implementations and storage entities. Connector Entity Mapping Sources: crates/palyra-connectors/src/lib.rs#1-10, crates/palyra-connectors/src/core/mod.rs#9-30Connector Supervisor
TheConnectorSupervisor is the primary interface for the ChannelPlatform in the daemon. It manages the lifecycle of connector instances and handles the “drain” loop for outbound messages.
Key Functions
initialize: Opens theConnectorStoreand registers provider adapters like Discord and Echo crates/palyra-daemon/src/channels.rs#142-169.enqueue_outbound: Persists a message to theoutboxtable before attempting delivery crates/palyra-daemon/src/channels/discord.rs#128-128.drain_due_outbox_for_connector: Processes pending messages for a specific connector, respecting rate limits and retry backoffs crates/palyra-daemon/src/channels/discord.rs#129-135.
Data Flow: Outbound Message
Sources: crates/palyra-connectors/src/core/supervisor.rs#1-30, crates/palyra-daemon/src/channels/discord.rs#112-152Provider Implementations
Palyra uses a trait-based system (ConnectorAdapter) to support multiple platforms.
| Provider | Implementation | Status | Description |
|---|---|---|---|
| Discord | DiscordConnectorAdapter | Supported | Full support for messaging, threads, reactions, and media crates/palyra-connectors/src/providers/discord/mod.rs#34-37. |
| Echo | EchoConnectorAdapter | Internal | A loopback provider used for testing and diagnostics crates/palyra-connectors/src/providers/echo.rs#25-28. |
| Slack | SlackConnectorAdapter | Deferred | Roadmap item; currently returns PermanentFailure crates/palyra-connectors/src/providers/slack.rs#15-26. |
| Telegram | TelegramConnectorAdapter | Deferred | Roadmap item; currently returns PermanentFailure crates/palyra-connectors/src/providers/telegram.rs#15-26. |
Echo Provider (Simulator)
TheEchoConnectorAdapter is used extensively in the simulator_harness.rs to verify the supervisor’s state machine. It supports special markers like [connector-crash-once] to trigger simulated failures and verify that the supervisor correctly retries the message crates/palyra-connectors/src/providers/echo.rs#123-136.
Sources: crates/palyra-connectors/src/providers/discord/mod.rs#1-63, crates/palyra-connectors/src/providers/echo.rs#1-45, crates/palyra-connectors/src/providers/slack.rs#1-26, crates/palyra-connectors/src/providers/telegram.rs#1-26
Storage and Reliability
ConnectorStore
TheConnectorStore is a SQLite-backed persistence layer. It maintains several critical tables:
outbox: Messages awaiting delivery.dead_letter_queue: Messages that failed after maximum retries or encountered aPermanentFailurecrates/palyra-connectors/src/core/storage.rs#22-25.events: Audit log of inbound and outbound activities.
Dead-Letter Queues (DLQ)
When a message cannot be delivered, it is moved to the DLQ. Operators can view these via the Console or CLI.ConnectorMessageMutationResult: Captures the outcome of edits or deletions crates/palyra-connectors/src/core/protocol.rs#14-15.DeadLetterRecord: Contains the original request, the failure reason, and the final timestamp crates/palyra-connectors/src/core/storage.rs#26-26.
Testing and Simulation
Thesimulator_harness.rs provides a deterministic environment for testing connector logic without external network dependencies.
Key Testing Entities
SimulatorRouter: A mock implementation ofConnectorRouterthat echoes inbound messages back as outbound replies crates/palyra-connectors/tests/simulator_harness.rs#41-71.MockConnectorServer: A stateful simulator that tracks delivery attempts and native IDs crates/palyra-connectors/tests/simulator_harness.rs#73-85.