ChannelRouter sits atop this framework, implementing concurrency policies, message filtering, and session isolation.
System Architecture
The framework is divided into a core logic layer (palyra-connector-core), a collection of platform-specific adapters (palyra-connectors), and a management layer within the daemon (ChannelPlatform).
Component Interaction
The following diagram illustrates how an inbound message flows from a platform adapter through the supervisor and into the gRPC-backed router. Data Flow: Inbound Message Processing Sources: crates/palyra-connector-core/src/supervisor.rs#128-134, crates/palyra-daemon/src/channels.rs#125-132Connector Supervisor and Storage
TheConnectorSupervisor is the central orchestrator for all connector instances. It uses a ConnectorStore (backed by SQLite) to persist message state, ensuring that outbound messages are not lost during restarts.
Key Responsibilities
- Registration: Adding new connector instances via
ConnectorInstanceSpeccrates/palyra-connector-core/src/supervisor.rs#221-241. - Deduplication: Inbound messages are tracked in the
ConnectorStoreto prevent processing the same event multiple times within a sliding window (default 7 days) crates/palyra-connector-core/src/supervisor.rs#44-44. - Lifecycle Management: Monitoring the
ConnectorLiveness(Running, Errored, Stopped) andConnectorReadinessof every instance crates/palyra-connectors/src/connectors/echo.rs#105-122.
Reliability and Dead Letter Queue
If a message fails to deliver after the maximum number of retries (default 5), it is moved to a Dead Letter Queue (DLQ).- Retry Policy: Uses exponential backoff defined in
ConnectorSupervisorConfigcrates/palyra-connector-core/src/supervisor.rs#25-36. - Dead Lettering: Failed messages are stored as
DeadLetterRecordin the database for manual inspection or replay crates/palyra-connector-core/src/storage.rs#19-21.
ChannelRouter and Concurrency Policies
TheChannelRouter (implemented in palyra-daemon) defines how Palyra interacts with specific channels. It handles security, session management, and rate limiting.
Concurrency Policies
The router manages how multiple simultaneous requests to the same channel are handled viaconcurrency_limit crates/palyra-daemon/src/channel_router.rs#174-174. While the codebase supports various strategies, the primary mechanism is the ChannelRoutingRule.
Routing Rules
Each channel can be configured with aChannelRoutingRule crates/palyra-daemon/src/channel_router.rs#161-175:
| Field | Description |
|---|---|
mention_patterns | Regex/Strings that trigger the agent. |
isolate_session_by_sender | If true, every user in a channel gets a private session. |
direct_message_policy | Controls DM access: Deny, Allow, or Pairing. |
broadcast_strategy | Controls @everyone / @here usage: Deny, MentionOnly, Allow. |
Broadcast Strategies
TheBroadcastStrategy enum crates/palyra-daemon/src/channel_router.rs#28-32 prevents agents from accidentally spamming entire servers:
Deny: All mass mentions are stripped.MentionOnly: Only specific mentions are allowed.Allow: Full broadcast capability.
Protocol Abstraction
The framework uses a clean separation between the daemon’s internal logic and the external platform protocols.palyra-connector-core
Contains the traits and base structures:ConnectorAdapter: Trait for platform implementations (e.g.,send_outbound,poll_inbound) crates/palyra-connector-core/src/supervisor.rs#137-174.ConnectorRouter: Trait used by the supervisor to ask the daemon where an inbound message should go crates/palyra-connector-core/src/supervisor.rs#128-134.
palyra-connectors
Contains the concrete adapters:- Discord: Implements the Discord Gateway/REST API crates/palyra-daemon/src/channels.rs#35-40.
- Echo: A testing adapter used for internal validation that simply returns the input crates/palyra-connectors/src/connectors/echo.rs#21-31.
Management and Observability
The framework exposes detailed status via the Admin API.Channel Operations Snapshot
Thebuild_channel_operations_snapshot function aggregates data for the dashboard, including crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#55-147:
- Saturation State: Categorizes channel health as
healthy,paused,rate_limited,backpressure, ordead_lettered. - Queue Metrics: Counts for
pending_outbox,due_outbox, andclaimed_outbox. - Error Tracking: Surfaces the
last_permission_failureorlast_auth_failureby scanning error logs and DLQ records.
CLI Integration
Thepalyra channels command provides administrative access to these features:
palyra channels pairings: Manages DM pairing codes crates/palyra-cli/src/commands/channels/mod.rs#229-250.palyra channels capabilities: Queries what a specific connector is allowed to do crates/palyra-cli/src/commands/channels/mod.rs#206-224.