Skip to main content
The Connector Framework provides the infrastructure for Palyra to interact with external messaging platforms. It is built on a supervisor pattern that manages the lifecycle of individual connector instances, handles message persistence via an outbox, and enforces routing policies through a centralized ChannelRouter.

​
Architecture Overview

The framework is divided into three primary layers:
  1. Connector Supervisor: Manages the lifecycle, state, and retries for connector instances.
  2. Channel Router: Handles message ingestion, pairing logic, concurrency limits, and backpressure.
  3. Connector Adapters: Implementation-specific logic for external platforms (e.g., Discord, Echo).

​
System Data Flow

The following diagram illustrates the flow of an inbound message from a platform through the framework into the Palyra core. Diagram: Inbound Message Routing Sources: crates/palyra-daemon/src/channels.rs#112-140, crates/palyra-daemon/src/channel_router.rs#215-226

​
Connector Supervisor & Storage

The ConnectorSupervisor is the central authority for managing ConnectorInstanceRecord entries. It uses a SQLite-backed ConnectorStore to persist the state of all configured connectors, including their readiness and liveness status.

​
Key Components

​
Connector Lifecycle States

StateDescription
Liveness::RunningThe connector’s background worker is active.
Liveness::StoppedThe connector has been manually disabled or failed to start.
Readiness::ReadyThe connector has successfully authenticated with the platform.
Readiness::DegradedThe connector is operational but experiencing partial failures (e.g., rate limits).
Sources: crates/palyra-connectors/src/lib.rs#1-12, crates/palyra-connectors/src/connectors/echo.rs#105-123

​
Channel Router

The ChannelRouter in palyra-daemon acts as the traffic controller between the connectors and the Palyra gateway. It implements security policies, concurrency management, and the “pairing” mechanism for Direct Messages (DMs).

​
Concurrency & Backpressure

The router enforces a concurrency_limit per channel crates/palyra-daemon/src/channel_router.rs#174-174. If a channel exceeds its limit, messages are queued or rejected based on the max_retry_queue_depth_per_channel configuration crates/palyra-daemon/src/channel_router.rs#181-181.

​
Pairing & Security

For platforms like Discord, the router supports a DirectMessagePolicy crates/palyra-daemon/src/channel_router.rs#57-61: Diagram: DM Pairing Flow Sources: crates/palyra-daemon/src/channel_router.rs#147-158, crates/palyra-daemon/src/channel_router.rs#121-144

​
Implementation: Echo & Test Connector

The EchoConnectorAdapter is a reference implementation used for internal testing and CI. It demonstrates idempotency handling and failure simulation.

​
Features

Sources: crates/palyra-connectors/src/connectors/echo.rs#20-31, crates/palyra-connectors/src/connectors/echo.rs#145-163

​
Configuration & Setup

Connectors are initialized within the ChannelPlatform struct in the daemon. 
// crates/palyra-daemon/src/channels.rs:113-132
pub fn initialize(
    grpc_url: String,
    auth: GatewayAuthConfig,
    db_path: PathBuf,
    media_config: MediaRuntimeConfig,
) -> Result<Self, ChannelPlatformError> {
    let store = Arc::new(palyra_connectors::ConnectorStore::open(db_path)?);
    // ...
    let supervisor = Arc::new(ConnectorSupervisor::new(
        Arc::clone(&store),
        router,
        default_adapters(),
        ConnectorSupervisorConfig::default(),
    ));
    // ...
}

​
CLI Integration

The Palyra CLI provides commands for managing these connections, specifically for the Discord onboarding flow, which uses the channels/discord/onboarding endpoints to validate tokens and apply routing rules crates/palyra-cli/src/commands/channels/connectors/discord/setup.rs#33-46. Sources: crates/palyra-daemon/src/channels.rs#113-132, crates/palyra-cli/src/commands/channels/connectors/discord/setup.rs#73-95