palyra-connector-core and palyra-connectors crates, defining how the Palyra daemon communicates with third-party APIs while maintaining consistent message routing, delivery guarantees, and security policies.
Architecture Overview
The framework follows a supervisor-adapter pattern. TheConnectorSupervisor manages the lifecycle and state of various ConnectorAdapter implementations.
Code Entity Mapping
The following diagram maps high-level framework concepts to their specific implementation entities in the codebase.| Concept | Code Entity | Role |
|---|---|---|
| Adapter Interface | ConnectorAdapter | Trait defining how to send messages and report capabilities. |
| Lifecycle Manager | ConnectorSupervisor | Orchestrates starting, stopping, and monitoring connector instances. |
| Persistence | ConnectorStore | Trait for persisting connector configuration and state. |
| Routing Logic | ConnectorRouter | Logic for dispatching inbound/outbound messages to the correct adapter. |
| Outbound Request | OutboundMessageRequest | Standardized payload for sending messages to external platforms. |
ConnectorAdapter Trait
TheConnectorAdapter is the core trait that every platform integration must implement. It defines the identity, availability, and message delivery capabilities of a connector.
Key Functions
kind(): Returns theConnectorKind(e.g.,Echo,Discord) crates/palyra-connectors/src/connectors/echo.rs#35-37.availability(): Reports if the connector isSupported,InternalTestOnly, orDeferredcrates/palyra-connectors/src/connectors/echo.rs#39-41.send_outbound(): The primary method for delivering messages. It accepts anOutboundMessageRequestand returns aDeliveryOutcomecrates/palyra-connectors/src/connectors/echo.rs#43-75.
Outbound Messaging and Delivery
When the system sends a message, it uses theOutboundMessageRequest struct, which contains the target conversation, text, and optional attachments crates/palyra-connector-core/src/protocol.rs#312-332.
The result of a send operation is a DeliveryOutcome:
Delivered: Successful delivery with anative_message_idfrom the platform crates/palyra-connector-core/src/protocol.rs#408-410.Retry: Indicates a transient failure (e.g., rate limits or connector restarting) with aRetryClasscrates/palyra-connector-core/src/protocol.rs#411-415.Failed: Permanent failure that should not be retried crates/palyra-connector-core/src/protocol.rs#416-419.
Connector Lifecycle and Supervision
TheConnectorSupervisor manages ConnectorInstanceRecord objects, which represent configured instances of a connector (e.g., a specific Discord bot).
ConnectorInstanceRecord
This record tracks the operational state of a connector instance:readiness: (Ready,MissingCredential,AuthFailed,Misconfigured) crates/palyra-connector-core/src/protocol.rs#110-115.liveness: (Stopped,Running,Restarting,Crashed) crates/palyra-connector-core/src/protocol.rs#142-147.restart_count: Tracks how many times the supervisor has attempted to recover the instance crates/palyra-connector-core/src/storage.rs#35-35.
Dead-Letter Handling
If a message fails delivery after the configured maximum attempts (defined inChannelRouterConfig.max_retry_attempts crates/palyra-daemon/src/channel_router.rs#182-182), it is moved to a dead-letter state. The DeadLetterRecord captures the failed OutboundMessageRequest along with the final error reason for manual operator intervention crates/palyra-connector-core/src/storage.rs#104-115.
Sources: crates/palyra-connector-core/src/storage.rs#24-50, crates/palyra-daemon/src/channel_router.rs#178-192
Data Flow: Message Delivery
The following diagram illustrates the flow of an outbound message from the Palyra CLI/Daemon through the framework to an external platform. Diagram: Outbound Message Data Flow Sources: crates/palyra-cli/src/commands/message.rs#47-81, crates/palyra-cli/src/client/message.rs#95-123, crates/palyra-daemon/src/channel_router.rs#215-235EchoConnector (Testing)
TheEchoConnectorAdapter is a reference implementation used for internal testing and validation of the framework crates/palyra-connectors/src/connectors/echo.rs#21-24.
Features
- Idempotency: It tracks
delivered_native_idsin aMutex<HashMap>to ensure that re-sending the sameenvelope_idreturns the samenative_message_idcrates/palyra-connectors/src/connectors/echo.rs#68-70. - Simulated Failure: If the message text contains
[connector-crash-once], the adapter returns aRetryClass::ConnectorRestartingoutcome exactly once for thatenvelope_id, allowing verification of the supervisor’s retry logic crates/palyra-connectors/src/connectors/echo.rs#48-61. - Fallback IDs: It generates stable hex fingerprints for messages using SHA-256 to simulate platform-generated IDs crates/palyra-connectors/src/connectors/echo.rs#78-91.
Capabilities and Discovery
Connectors report their capabilities via theConnectorCapabilitySet crates/palyra-connector-core/src/protocol.rs#205-215. This allows the UI and CLI to gracefully degrade or inform the user when certain actions (like editing or reacting to messages) are not supported by a specific platform.
The CLI uses the capabilities command to query these from the daemon:
- Calls
runtime.message_capabilities()crates/palyra-cli/src/commands/message.rs#35-44. - The daemon responds with a
MessageCapabilitiesstruct crates/palyra-cli/src/client/message.rs#51-56. - The CLI filters
SUPPORTED_MESSAGE_ACTIONSandUNSUPPORTED_MESSAGE_ACTIONSto display status to the operator crates/palyra-cli/src/client/message.rs#16-25.