Discord Connector Integration
The Discord integration is implemented as a specialized adapter within theConnectorSupervisor framework. It handles the translation between Discord-specific events (via Bot API or Webhooks) and the internal InboundMessageEvent and OutboundMessageRequest protocols.
Implementation Architecture
The integration spans several layers:palyra-connector-discord: Contains the shared logic for identity normalization and specification building crates/palyra-daemon/src/channels/discord.rs#6-10.palyra-daemon(Channel Subsystem): Manages the lifecycle of Discord connectors, including ID generation viadiscord_connector_idcrates/palyra-daemon/src/channels/discord.rs#6-10.- Admin API: Provides endpoints for onboarding, identity probing, and permission validation crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-40.
Onboarding and Identity Probing
Discord integration uses an “Onboarding Probe” to verify bot credentials and permissions before final activation. Theadmin_discord_onboarding_probe_handler triggers a preflight check that validates the bot token and retrieves the bot’s identity crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#6-22.
Permission Normalization
Discord permissions are normalized into a standard set of requirements to ensure the bot can function correctly within a channel.- Required Permissions: Includes
VIEW_CHANNEL,SEND_MESSAGES,READ_MESSAGE_HISTORY,EMBED_LINKS, andATTACH_FILEScrates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#94-103. - Gap Detection: The system identifies missing permissions and surface them via the
last_permission_failurefield in the status payload crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#87-104.
Discord Data Flow
The following diagram illustrates the flow of a message from Discord into the Palyra Gateway. Diagram: Discord Inbound Message Routing Sources: crates/palyra-connector-core/src/supervisor.rs#161-167, crates/palyra-daemon/src/channels/discord.rs#6-21, crates/palyra-connector-core/src/supervisor.rs#128-134Webhook Integration Subsystem
The Webhook subsystem provides a generic mechanism for receiving signed payloads from external providers. It is managed by theWebhookRegistry, which persists integration metadata in a webhooks.toml file crates/palyra-daemon/src/webhooks.rs#16-17.
Registry and Security
TheWebhookRegistry enforces strict security boundaries:
- Owner-only Permissions: The registry ensures that the storage directory and files are accessible only by the daemon user crates/palyra-daemon/src/webhooks.rs#11-11.
- Vault Integration: Secrets (like signing keys) are never stored in the registry; they are referenced via
secret_vault_refand retrieved from thepalyra-vaultcrates/palyra-daemon/src/webhooks.rs#37-37.
Payload Validation and Replay Protection
Thepalyra-common crate provides the verify_webhook_payload and parse_webhook_payload utilities used by the daemon crates/palyra-common/src/lib.rs#26-29.
| Feature | Implementation |
|---|---|
| Signature Verification | WebhookSignatureVerifier validates HMAC or RSA signatures crates/palyra-common/src/lib.rs#28-28. |
| Replay Protection | ReplayNonceStore tracks nonces and timestamps to prevent duplicate attacks crates/palyra-common/src/lib.rs#27-27. |
| Payload Limits | Enforced via max_payload_bytes (default 64KB, max 1MB) crates/palyra-daemon/src/webhooks.rs#23-24. |
Webhook Processing Logic
Diagram: Webhook Ingestion Pipeline Sources: crates/palyra-common/src/webhook.rs#26-29, crates/palyra-daemon/src/webhooks.rs#107-111, crates/palyra-daemon/src/webhooks.rs#218-222Admin Operations API
The Admin API provides operational visibility into the health and saturation of connectors.Connector Status and Saturation
Thebuild_channel_status_payload function aggregates data from the ConnectorStore and ConnectorSupervisor to determine the “saturation state” of a channel crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#29-53.
Saturation states include:
paused: Connector is disabled or the queue is manually paused crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#114-117.dead_lettered: Messages exist in the dead-letter queue requiring manual intervention crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#123-125.rate_limited: Activeretry_after_msor route-specific rate limits are in effect crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#126-133.backpressure: The outbox contains claimed or due messages exceeding immediate processing capacity crates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rs#134-141.
Lifecycle Management
Admin handlers support explicit logout and removal of accounts:admin_discord_account_logout_handler: Disables the connector but can optionally retain credentials crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#42-58.admin_discord_account_remove_handler: Completely removes the connector configuration and deletes associated vault secrets if requested crates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rs#77-93.
crates/palyra-daemon/src/webhooks.rscrates/palyra-common/src/lib.rscrates/palyra-daemon/src/transport/http/handlers/admin/channels/mod.rscrates/palyra-daemon/src/transport/http/handlers/admin/channels/connectors/discord.rscrates/palyra-daemon/src/channels/discord.rscrates/palyra-connector-core/src/supervisor.rs