Connector Architecture
The system is built on a provider-agnostic architecture where platform-specific logic is encapsulated in Adapters, managed by a central Supervisor.Key Components
| Component | Class/Trait | Responsibility |
|---|---|---|
| Supervisor | ConnectorSupervisor | Manages the lifecycle of all connector instances, including startup, heartbeats, and error recovery. crates/palyra-connectors/src/lib.rs#13 |
| Adapter | ConnectorAdapter | Platform-specific implementation (e.g., Discord) for sending messages and handling gateway events. crates/palyra-connectors/src/lib.rs#3 |
| Store | ConnectorStore | SQLite-backed persistence for connector configurations, outbox queues, and dead letters. crates/palyra-connectors/src/lib.rs#12 |
| Router | ConnectorRouter | Logic for dispatching inbound messages to the appropriate internal sessions. crates/palyra-connectors/src/lib.rs#12 |
Data Flow: Code Entity Mapping
The following diagram maps the natural language flow of a message to the specific code entities in thepalyra-connectors and palyra-daemon crates.
Message Inbound and Outbound Flow
Sources: crates/palyra-daemon/src/channels.rs#148-182, crates/palyra-connector-discord/src/adapter.rs#77-118, crates/palyra-connectors/src/lib.rs#1-18
Message Routing and Backpressure
Routing is handled by theChannelRouter, which applies rules for session isolation, broadcast strategies, and concurrency limits.
Routing Policies
The system supports several policies defined inChannelRouterConfig:
- Direct Message Policy: Controls how DMs are handled (
Deny,Pairing,Allow). crates/palyra-daemon/src/channel_router.rs#57-61 - Broadcast Strategy: Controls mass mentions like
@everyone(Deny,MentionOnly,Allow). crates/palyra-daemon/src/channel_router.rs#28-32 - Session Isolation: If
isolate_session_by_senderis true, messages from different users in the same channel are routed to distinct sessions. crates/palyra-daemon/src/channel_router.rs#169
Backpressure and Queue Model
To prevent overwhelming external APIs and handle transient failures, the system implements a multi-stage queue:- Outbox: Pending messages are stored in
OutboxEntryRecord. crates/palyra-connectors/src/lib.rs#16 - Retry Logic: Messages failing with
RetryClass::RateLimitorRetryClass::ConnectorRestartingare rescheduled with exponential backoff. crates/palyra-connectors/src/lib.rs#16, crates/palyra-daemon/src/channel_router.rs#12 - Dead Letters: Messages that exceed
max_retry_attemptsare moved toDeadLetterRecordfor manual operator intervention. crates/palyra-connectors/src/lib.rs#14, crates/palyra-daemon/src/channel_router.rs#182
Connector Implementations
Discord (palyra-connector-discord)
The Discord connector is the most feature-complete, supporting:
- Gateway Integration: Real-time inbound message monitoring via WebSockets. crates/palyra-connector-discord/src/adapter.rs#44-52
- Message Splitting: Automatically chunks messages exceeding Discord’s 2,000 character limit via
split_outbound. crates/palyra-connector-discord/src/adapter.rs#120-164 - Governance: Enforces approval requirements for edits and deletions based on message age and channel type. crates/palyra-daemon/src/channels/discord.rs#61-141
Webhooks
TheWebhookRegistry manages generic HTTP inbound integrations.
- Signature Verification: Optional requirement for payload signing. crates/palyra-daemon/src/webhooks.rs#41
- Payload Constraints: Enforces
max_payload_bytes(default 64KB) to prevent DoS. crates/palyra-daemon/src/webhooks.rs#23 - Secret Management: Secrets are stored in the Palyra Vault via
secret_vault_ref. crates/palyra-daemon/src/webhooks.rs#56
Other Connectors
- Slack/Telegram: Currently defined but marked as
ConnectorAvailability::Deferred. crates/palyra-connectors/src/connectors/slack.rs#19, crates/palyra-connectors/src/connectors/telegram.rs#19 - Echo: An internal test connector used for deterministic simulation and CI. crates/palyra-connectors/src/connectors/echo.rs#21
Administration and Monitoring
The daemon exposes an HTTP API for monitoring connector health and managing queues.Health Diagnostics
Theadmin_channels_list_handler provides a snapshot of all active connectors, including:
- Saturation State: Identifies if a connector is
healthy,rate_limited,backpressure(high queue depth), orpaused. crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#125-158 - Permission Gaps: Specifically for Discord, it detects missing scopes like
View ChannelsorSend Messages. crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#98-115
Queue Draining
Operators can trigger aDrainOutcome to clear queues or move specific messages out of dead letters. This is managed via the ConnectorSupervisor which handles the concurrent execution of these operations. crates/palyra-connectors/src/lib.rs#14
Sources: crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#22-64, crates/palyra-connectors/src/lib.rs#13-17