Connector Supervisor and Adapters
TheConnectorSupervisor is the central orchestrator for all active connector instances. It manages their lifecycle (Running, Stopped, or Quarantined) and delegates platform-specific logic to implementations of the ConnectorAdapter trait.
Implementation Details
- ConnectorAdapter: A trait defining the interface for specific platforms. Key methods include
kind(),availability(), andsend_outbound()crates/palyra-connectors/src/supervisor.rs#34-47. - ConnectorInstanceRecord: Represents the persisted state of a connector, including its
ConnectorKind,ConnectorLiveness, andConnectorReadinesscrates/palyra-connectors/src/storage.rs#105-123. - Availability Tiers: Connectors are categorized by
ConnectorAvailability(e.g.,Supported,Deferred, orInternalTestOnly) crates/palyra-connectors/src/protocol.rs#39-41.
Connector Lifecycle and Data Flow
The following diagram illustrates how theConnectorSupervisor manages an adapter and its persistent state.
Connector Management Architecture
Sources: crates/palyra-connectors/src/supervisor.rs#34-47, crates/palyra-connectors/src/storage.rs#105-123, crates/palyra-connectors/src/connectors/mod.rs#15-18
Channel Router and Concurrency Model
TheChannelRouter acts as the traffic controller between external platforms and the Palyra daemon. It enforces per-channel concurrency limits, manages backpressure, and handles message retry logic.
Concurrency and Backpressure
- Per-Channel Limits: The router enforces a
concurrency_limitper channel (defaulting to 2) to prevent a single noisy channel from exhausting daemon resources crates/palyra-daemon/src/channel_router.rs#174-190. - Retry Queue: Inbound and outbound messages that fail due to transient issues are placed in a retry queue with a
max_retry_queue_depth_per_channel(default 64) crates/palyra-daemon/src/channel_router.rs#181-199. - Backoff: Retries follow a configurable
retry_backoff_ms(default 250ms) crates/palyra-daemon/src/channel_router.rs#183-201.
Routing Rules
Routing is governed byChannelRoutingRule crates/palyra-daemon/src/channel_router.rs#161-175, which includes:
mention_patterns: Patterns that trigger the bot (e.g., @botname).allow_from/deny_from: ACLs for specific sender handles.isolate_session_by_sender: If true, each user in a channel gets a private session context.broadcast_strategy: Determines if the bot can use@everyoneor@herecrates/palyra-daemon/src/channel_router.rs#28-32.
Pairing Rules and DM Policy
For Direct Messages (DMs), Palyra implements a strict pairing protocol to prevent unauthorized access.Direct Message Policies
TheDirectMessagePolicy enum defines three modes crates/palyra-daemon/src/channel_router.rs#57-61:
- Deny: All DMs are ignored.
- Allow: DMs are accepted from any sender.
- Pairing: Requires a user to provide a valid pairing code before a session is established.
Pairing Lifecycle
- Code Issuance: An admin generates a
PairingCodeRecordvia the console crates/palyra-daemon/src/channel_router.rs#85-91. - Consumption: The user sends the code to the bot in a DM.
- Pending State: A
PairingPendingRecordis created, which may require manual approval crates/palyra-daemon/src/channel_router.rs#94-101. - Grant: Upon approval, a
PairingGrantRecordis stored, enabling future communication crates/palyra-daemon/src/channel_router.rs#104-110.
| Feature | Configuration Symbol | Default Value |
|---|---|---|
| Pairing Code Length | DM_PAIRING_CODE_LENGTH | 8 characters crates/palyra-daemon/src/channel_router.rs#19 |
| Code TTL | DEFAULT_DM_PAIRING_CODE_TTL_MS | 10 minutes crates/palyra-daemon/src/channel_router.rs#17 |
| Session TTL | DEFAULT_DM_PAIRING_SESSION_TTL_MS | 8 hours crates/palyra-daemon/src/channel_router.rs#21 |
Reliability and Dead-Letter Handling
The framework is designed for high reliability, handling connector crashes and message delivery failures gracefully.Dead-Letter Handling
If a message exceedsmax_retry_attempts (default 3), it is moved to a dead-letter state.
- DeadLetterRecord: Stores the failed message, the
connector_id, and the final error reason crates/palyra-connector-core/src/lib.rs#8. - Quarantine: Channels or connectors that consistently fail may be placed in a quarantine state to prevent cascading failures crates/palyra-daemon/src/channel_router.rs#13.
Idempotency
Adapters like theEchoConnectorAdapter demonstrate idempotency by tracking delivered_native_ids crates/palyra-connectors/src/connectors/echo.rs#22. If the framework retries a send due to a simulated crash (CRASH_ONCE_MARKER), the adapter ensures the same message is not delivered twice to the end-user crates/palyra-connectors/src/connectors/echo.rs#48-75.
Outbound Delivery and Retry Logic
Sources: crates/palyra-daemon/src/channel_router.rs#181-183, crates/palyra-connectors/src/connectors/echo.rs#48-75, crates/palyra-connectors/src/protocol.rs#12