Skip to main content
The Connector Framework provides a standardized, trait-based interface for integrating external communication platforms (e.g., Discord, Slack, Telegram) into the Palyra ecosystem. It manages the lifecycle of connector instances, reliable message delivery with retry logic, inbound event ingestion, and storage of connector state and message history.

​
Core Architecture

The framework is divided into two primary layers: palyra-connector-core, which defines the protocols and base traits, and palyra-connectors, which provides the implementation of the supervisor, storage, and specific platform adapters.

​
Data Flow: Inbound and Outbound

The following diagram illustrates the flow of messages through the system, bridging the platform-specific adapters to the central ChannelRouter. Connector Message Flow Sources: [crates/palyra-connector-core/src/supervisor.rs#131-137](http://crates/palyra-connector-core/src/supervisor.rs#131-137), [crates/palyra-daemon/src/channels.rs#148-182](http://crates/palyra-daemon/src/channels.rs#148-182), [crates/palyra-connectors/src/lib.rs#2-18](http://crates/palyra-connectors/src/lib.rs#2-18)

​
Key Code Entities

EntityRoleDefinition
ConnectorAdapterTrait implemented by specific platforms (Discord, Slack, Echo). Handles raw network I/O.[crates/palyra-connector-core/src/supervisor.rs#140-140](http://crates/palyra-connector-core/src/supervisor.rs#140-140)
ConnectorSupervisorManages the lifecycle, retries, and background polling for all active connectors.[crates/palyra-connector-core/src/supervisor.rs#25-25](http://crates/palyra-connector-core/src/supervisor.rs#25-25)
ConnectorStoreSQLite-backed persistence for connector instances, outbox queues, and dead-letter records.[crates/palyra-connector-core/src/storage.rs#20-20](http://crates/palyra-connector-core/src/storage.rs#20-20)
ConnectorRouterInterface used by the supervisor to dispatch inbound events to the daemon’s agent logic.[crates/palyra-connector-core/src/supervisor.rs#131-131](http://crates/palyra-connector-core/src/supervisor.rs#131-131)
OutboundMessageRequestStandardized structure for messages leaving the system.[crates/palyra-connector-core/src/protocol.rs#16-16](http://crates/palyra-connector-core/src/protocol.rs#16-16)

​
Trait-Based Interface (ConnectorAdapter)

The ConnectorAdapter trait is the core abstraction for adding new platforms. It defines how a connector interacts with its external service.

​
Primary Methods

  • send_outbound: Sends a message to the platform. Returns a DeliveryOutcome (Delivered, Retry, or DeadLetter). [crates/palyra-connector-core/src/supervisor.rs#172-176](http://crates/palyra-connector-core/src/supervisor.rs#172-176)
  • poll_inbound: Optional method for platforms that do not support webhooks, allowing the supervisor to pull new messages. [crates/palyra-connector-core/src/supervisor.rs#164-170](http://crates/palyra-connector-core/src/supervisor.rs#164-170)
  • capabilities: Returns a ConnectorCapabilitySet defining supported features like message editing, reactions, or thread support. [crates/palyra-connector-core/src/supervisor.rs#145-147](http://crates/palyra-connector-core/src/supervisor.rs#145-147)
  • edit_message / delete_message: Methods for mutating existing content on the platform. [crates/palyra-connector-core/src/supervisor.rs#200-220](http://crates/palyra-connector-core/src/supervisor.rs#200-220)
Sources: [crates/palyra-connector-core/src/supervisor.rs#140-230](http://crates/palyra-connector-core/src/supervisor.rs#140-230)

​
Connector Supervisor & Storage

The ConnectorSupervisor acts as the engine of the framework. It ensures reliability through several mechanisms:
  1. Deduplication: Inbound events are checked against the ConnectorStore using platform-specific IDs to prevent double-processing. [crates/palyra-connector-core/src/supervisor.rs#47-47](http://crates/palyra-connector-core/src/supervisor.rs#47-47)
  2. Retry Logic: If send_outbound returns a RetryClass, the supervisor schedules a retry with exponential backoff. [crates/palyra-connector-core/src/supervisor.rs#32-35](http://crates/palyra-connector-core/src/supervisor.rs#32-35)
  3. Dead Letter Queue: Messages that exceed max_retry_attempts are moved to a DeadLetterRecord for manual operator intervention. [crates/palyra-connector-core/src/supervisor.rs#50-50](http://crates/palyra-connector-core/src/supervisor.rs#50-50)
  4. Queue Management: The supervisor can pause queues per connector instance to prevent cascading failures during platform outages. [crates/palyra-daemon/src/transport/http/handlers/console/channels/mod.rs#183-197](http://crates/palyra-daemon/src/transport/http/handlers/console/channels/mod.rs#183-197)
Entity Relationship: Supervisor and Storage Sources: [crates/palyra-connector-core/src/supervisor.rs#25-28](http://crates/palyra-connector-core/src/supervisor.rs#25-28), [crates/palyra-connector-core/src/storage.rs#20-22](http://crates/palyra-connector-core/src/storage.rs#20-22), [crates/palyra-daemon/src/channels.rs#169-174](http://crates/palyra-daemon/src/channels.rs#169-174)

​
Simulator & Testing

The framework includes a simulator harness for testing connector logic without requiring external network access.

​
Echo Connector

The EchoConnectorAdapter is used for internal integration tests. It simulates message delivery and can be triggered to simulate a crash using the [connector-crash-once] marker in the message text.
  • Implementation: [crates/palyra-connectors/src/connectors/echo.rs#21-76](http://crates/palyra-connectors/src/connectors/echo.rs#21-76)
  • Idempotency: It tracks delivered IDs in a Mutex<HashMap> to ensure that duplicate envelope_id requests return the same native_message_id. [crates/palyra-connectors/src/connectors/echo.rs#63-74](http://crates/palyra-connectors/src/connectors/echo.rs#63-74)

​
Multi-Connector Management

The palyra-connectors crate aggregates all available adapters via default_adapters(). 
pub fn default_adapters() -> HashMap<ConnectorKind, Box<dyn ConnectorAdapter>> {
    let mut adapters: HashMap<ConnectorKind, Box<dyn ConnectorAdapter>> = HashMap::new();
    adapters.insert(ConnectorKind::Discord, Box::new(DiscordConnectorAdapter::default()));
    adapters.insert(ConnectorKind::Slack, Box::new(SlackConnectorAdapter::default()));
    adapters.insert(ConnectorKind::Telegram, Box::new(TelegramConnectorAdapter::default()));
    adapters.insert(ConnectorKind::Echo, Box::new(EchoConnectorAdapter::default()));
    adapters
}
Sources: [crates/palyra-connectors/src/connectors/mod.rs]() (inferred from [crates/palyra-daemon/src/channels.rs#172-172](http://crates/palyra-daemon/src/channels.rs#172-172))

​
CLI Integration

The Palyra CLI provides a robust interface for managing connectors and testing message flow via the channels and message subcommands.
  • Capabilities: Operators can query what actions a specific connector supports (e.g., palyra message capabilities discord:123). [crates/palyra-cli/src/commands/message.rs#26-46](http://crates/palyra-cli/src/commands/message.rs#26-46)
  • Manual Dispatch: Messages can be sent directly via the CLI to verify routing: palyra message send --to <target> --text "hello". [crates/palyra-cli/src/commands/message.rs#47-81](http://crates/palyra-cli/src/commands/message.rs#47-81)
  • History & Search: The CLI supports reading message history (read) and searching across platform-specific conversations (search). [crates/palyra-cli/src/commands/message.rs#118-191](http://crates/palyra-cli/src/commands/message.rs#118-191)
Sources: [crates/palyra-cli/src/commands/channels/mod.rs#61-224](http://crates/palyra-cli/src/commands/channels/mod.rs#61-224), [crates/palyra-cli/src/client/message.rs#156-215](http://crates/palyra-cli/src/client/message.rs#156-215)