ConnectorAdapter Trait
TheConnectorAdapter trait is the core interface that every platform integration must implement. It abstracts away platform-specific APIs into a set of standard asynchronous operations.
| Function | Description |
|---|---|
kind() | Returns the ConnectorKind (e.g., Discord, Echo, Slack) crates/palyra-connector-core/src/supervisor.rs#138-138. |
availability() | Indicates if the connector is Supported, InternalTestOnly, or Deferred crates/palyra-connector-core/src/supervisor.rs#140-140. |
send_outbound() | The primary method for delivering messages to the external platform crates/palyra-connector-core/src/supervisor.rs#169-173. |
poll_inbound() | Optional method for connectors that use polling instead of WebSockets/Webhooks crates/palyra-connector-core/src/supervisor.rs#161-167. |
runtime_snapshot() | Returns platform-specific health and state data as JSON crates/palyra-connector-core/src/supervisor.rs#154-159. |
Data Flow: Outbound Message Path
Outbound messages follow a rigorous path through the supervisor and store to ensure they are never lost and are delivered exactly once where possible. Connector Outbound Pipeline Sources: crates/palyra-connector-core/src/supervisor.rs#194-214, crates/palyra-connector-core/src/supervisor.rs#431-443ConnectorSupervisor
TheConnectorSupervisor acts as the orchestrator for all active connectors. It maintains a registry of available ConnectorAdapter implementations and manages the background tasks for draining the outbox and polling for inbound events.
Key responsibilities:
- Registration: Persists connector instances (e.g., a specific Discord Bot) via
register_connectorcrates/palyra-connector-core/src/supervisor.rs#221-241. - Routing: Uses a
ConnectorRouterto map inbound platform events to internal principals crates/palyra-connector-core/src/supervisor.rs#128-134. - Queue Management: Monitors
ConnectorQueueSnapshotto provide health status to the Admin API crates/palyra-connector-core/src/supervisor.rs#19-21.
ConnectorStore (SQLite Persistence)
All connector state is backed by a SQLite database through theConnectorStore. This provides durability for messages and prevents loss during daemon restarts.
Schema Entities
| Entity | Description |
|---|---|
ConnectorInstanceRecord | Stores configuration, credentials (vault refs), and liveness state for a connector crates/palyra-connector-core/src/storage.rs#4-4. |
OutboxEntryRecord | Represents a message waiting for delivery. Includes envelope_id for idempotency crates/palyra-connector-core/src/storage.rs#20-21. |
DeadLetterRecord | Stores messages that failed permanently or exceeded max retries, including the failure reason crates/palyra-connector-core/src/storage.rs#8-8. |
Delivery Idempotency and Retries
The framework uses anenvelope_id to ensure that even if a network request is retried, the external platform does not create duplicate messages.
RetryClass and Backoff
Whensend_outbound fails, the adapter returns a RetryClass which determines the supervisor’s next action:
ConnectorRestarting: Immediate retry or short delay crates/palyra-connectors/src/connectors/echo.rs#56-56.RateLimited: Respectsretry_after_msprovided by the platform crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#68-71.PermanentFailure: Message is moved to the dead-letter queue crates/palyra-connectors/src/connectors/slack.rs#27-29.
EchoConnectorAdapter
TheEchoConnectorAdapter is a specialized implementation used for testing and internal diagnostics. It simulates delivery by storing “sent” messages in an in-memory map and supports a special marker [connector-crash-once] to test the supervisor’s retry logic.
- Idempotency: It calculates a
stable_fingerprint_hexof the message payload to ensure that re-sending the sameenvelope_idreturns the samenative_message_idcrates/palyra-connectors/src/connectors/echo.rs#78-91. - Failure Simulation: If a message contains the crash marker, it returns
RetryClass::ConnectorRestartingexactly once for thatenvelope_idcrates/palyra-connectors/src/connectors/echo.rs#48-60.
Webhook Management
The daemon includes aWebhookRegistry for managing inbound HTTP callbacks from external services.
- Persistence: Webhooks are stored in
webhooks.tomlcrates/palyra-daemon/src/webhooks.rs#16-16. - Security: Supports
signature_requiredand secret verification usingVaultRefcrates/palyra-daemon/src/webhooks.rs#61-62. - Diagnostics: The
WebhookDiagnosticsSnapshottracks how many integrations are ready, enabled, or failing due to missing secrets crates/palyra-daemon/src/webhooks.rs#96-104.