Connector Platform and Message Pipeline

The Connector Platform is the subsystem responsible for bridging external communication platforms (e.g., Discord, Slack) with the Palyra daemon. It provides a unified API for managing connector lifecycles, processing inbound messages through a structured pipeline, and draining outbound message queues with built-in retry logic and dead-letter handling.

ChannelPlatform and ConnectorSupervisor

The ChannelPlatform serves as the high-level coordinator within the daemon crates/palyra-daemon/src/channels.rs#106-110. It encapsulates the ConnectorSupervisor, which manages the lifecycle of individual ConnectorAdapter instances.

Key Components

Component	Responsibility
`ChannelPlatform`	Orchestrates initialization, default inventory, and provides the public API for the daemon crates/palyra-daemon/src/channels.rs#106-110.
`ConnectorSupervisor`	Manages the runtime state, registration, and status of all connectors crates/palyra-connectors/src/lib.rs#2-12.
`ConnectorStore`	A SQLite-backed store for persisting connector configurations, instance records, and outbox messages crates/palyra-daemon/src/channels.rs#119-119.
`ConnectorAdapter`	A trait implemented by specific platform integrations (e.g., `DiscordConnectorAdapter`) to handle low-level transport crates/palyra-connectors/src/connectors/mod.rs#16-18.

Initialization Lifecycle

When ChannelPlatform::initialize is called, it performs the following steps:

Opens the ConnectorStore at the specified path crates/palyra-daemon/src/channels.rs#119-119.
Initializes the MediaArtifactStore for handling message attachments crates/palyra-daemon/src/channels.rs#120-124.
Creates a GrpcChannelRouter to bridge inbound connector events back to the daemon’s gRPC services crates/palyra-daemon/src/channels.rs#125-126.
Instantiates the ConnectorSupervisor with a set of default_adapters (Echo and Discord) crates/palyra-daemon/src/channels.rs#127-132.

Sources: crates/palyra-daemon/src/channels.rs#106-140, crates/palyra-connectors/src/connectors/mod.rs#16-18

Inbound Message Pipeline

Inbound messages flow from the external platform through the adapter into the ConnectorSupervisor, which then routes them to the daemon via the GrpcChannelRouter.

Data Flow: Inbound Message

Ingestion: The ConnectorAdapter receives a message and emits an InboundMessageEvent.
Preprocessing: Attachments are preprocessed and stored in the MediaArtifactStore crates/palyra-daemon/src/channels.rs#125-126.
Routing: The GrpcChannelRouter constructs a RouteMessageRequest crates/palyra-daemon/src/channels.rs#32-33.
Daemon Entry: The message is submitted to the Gateway’s gRPC endpoint using HEADER_CHANNEL and HEADER_PRINCIPAL for authentication crates/palyra-daemon/src/channels.rs#31-31.

Code Entity Mapping: Inbound Routing

The following diagram shows how inbound messages are transformed from raw events into routed requests. Title: Inbound Routing Pipeline Sources: crates/palyra-daemon/src/channels.rs#125-132, crates/palyra-daemon/src/channel_router.rs#215-227, crates/palyra-daemon/src/transport/grpc/auth.rs#31-31

Outbound Message Pipeline

Outbound messages are enqueued in the ConnectorStore outbox and processed by a background “drain” loop.

Outbound Drain Logic

The ConnectorSupervisor periodically drains the outbox for each active connector.

Selection: It fetches OutboxEntryRecord items that are pending or scheduled for retry.
Dispatch: It calls ConnectorAdapter::send_outbound crates/palyra-connectors/src/connectors/echo.rs#43-47.
Outcome Handling:
- Delivered: The record is marked as succeeded with a native_message_id crates/palyra-connectors/src/connectors/echo.rs#69-69.
- Retry: If the adapter returns RetryClass, the message is rescheduled with exponential backoff crates/palyra-connectors/src/connectors/echo.rs#55-59.
- Permanent Failure: The message is moved to the DeadLetterRecord table for manual inspection crates/palyra-connectors/src/lib.rs#8-11.

Code Entity Mapping: Outbound Pipeline

The following diagram illustrates the lifecycle of an outbound message from enqueue to delivery. Title: Outbound Drain and Retry Lifecycle Sources: crates/palyra-connectors/src/connectors/echo.rs#43-75, crates/palyra-connectors/src/lib.rs#8-12

Echo Connector

The EchoConnectorAdapter is a specialized implementation used for internal testing and validation of the pipeline crates/palyra-connectors/src/connectors/echo.rs#21-24.

Idempotency: It maintains a delivered_native_ids map to ensure the same envelope_id always results in the same native_message_id crates/palyra-connectors/src/connectors/echo.rs#68-70.
Crash Simulation: If a message contains the string [connector-crash-once], the adapter will return a RetryClass::ConnectorRestarting outcome exactly once for that envelope_id to test daemon resilience crates/palyra-connectors/src/connectors/echo.rs#48-61.
Availability: It is marked as ConnectorAvailability::InternalTestOnly crates/palyra-connectors/src/connectors/echo.rs#40-41.

Sources: crates/palyra-connectors/src/connectors/echo.rs#18-86

Supported Connectors

The platform defines several connector kinds, though implementation status varies:

Connector Kind	Availability	Status
`Echo`	`InternalTestOnly`	Fully functional for tests crates/palyra-connectors/src/connectors/echo.rs#35-41.
`Discord`	`Supported`	Primary production connector crates/palyra-connectors/src/connectors/mod.rs#38-38.
`Slack`	`Deferred`	Roadmap item; returns `PermanentFailure` crates/palyra-connectors/src/connectors/slack.rs#14-30.
`Telegram`	`Deferred`	Roadmap item; returns `PermanentFailure` crates/palyra-connectors/src/connectors/telegram.rs#14-30.

Sources: crates/palyra-connectors/src/connectors/mod.rs#1-18, crates/palyra-connectors/src/connectors/slack.rs#1-31, crates/palyra-connectors/src/connectors/telegram.rs#1-31

​ChannelPlatform and ConnectorSupervisor

​Key Components

​Initialization Lifecycle

​Inbound Message Pipeline

​Data Flow: Inbound Message

​Code Entity Mapping: Inbound Routing

​Outbound Message Pipeline

​Outbound Drain Logic

​Code Entity Mapping: Outbound Pipeline

​Echo Connector

​Supported Connectors