Channel Trait

​

Overview

​

Channel Trait

#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    async fn receive(&self) -> Result<Option<IncomingMessage>>;
    async fn send(&self, message: &OutgoingMessage) -> Result<()>;
}

​

Methods

​

name()

fn name(&self) -> &str

​

receive()

async fn receive(&self) -> Result<Option<IncomingMessage>>

• Ok(Some(IncomingMessage)) - A message was received
• Ok(None) - No message currently available (caller should poll again later)
• Err(OneClawError) - Channel error occurred

• Non-blocking: Returns immediately if no message is ready
• Async: Can be awaited efficiently without blocking the runtime
• Sequential polling: ChannelManager polls channels in order

​

send()

async fn send(&self, message: &OutgoingMessage) -> Result<()>

• message: &OutgoingMessage - The message to send

• Ok(()) - Message sent successfully
• Err(OneClawError) - Send failed

​

Message Types

​

IncomingMessage

#[derive(Debug, Clone)]
pub struct IncomingMessage {
    pub source: String,
    pub content: String,
    pub timestamp: chrono::DateTime<chrono::Utc>,
}

• source - Source identifier (e.g., “cli”, “tcp:8080”, “telegram:12345”, “mqtt:sensors/temp”)
• content - Text content of the message
• timestamp - UTC timestamp when the message was received

​

OutgoingMessage

#[derive(Debug, Clone)]
pub struct OutgoingMessage {
    pub destination: String,
    pub content: String,
}

• destination - Destination identifier (channel-specific routing)
• content - Text content of the message

​

Channel Lifecycle

1. Construction - Channel is created and configured
2. Registration - Channel is added to ChannelManager via add_channel()
3. Polling Loop - ChannelManager repeatedly calls receive() on all channels
4. Message Handling - First channel with a message wins (sequential polling)
5. Response Routing - Responses sent back via send() using source/destination mapping

​

NoopChannel

pub struct NoopChannel;

impl Channel for NoopChannel {
    fn name(&self) -> &str { "noop" }
    async fn receive(&self) -> Result<Option<IncomingMessage>> { Ok(None) }
    async fn send(&self, _message: &OutgoingMessage) -> Result<()> { Ok(()) }
}

• Testing and development
• Placeholder when no channels are configured
• Disabling I/O during unit tests

​

Implementation Requirements

​

Thread Safety

• Send + Sync - Channels must be safe to share across threads
• Internal mutability via Mutex or similar for state management

​

Non-Blocking Design

• receive() should return immediately if no message is ready
• Use timeouts (1-100ms) for network operations
• Buffer incoming messages for sequential delivery

​

Error Handling

• Return Ok(None) for transient “no data” conditions
• Return Err() for fatal errors (connection loss, invalid config)
• Log warnings for recoverable errors (dropped messages, timeouts)

​

Example Implementation Pattern

use async_trait::async_trait;
use oneclaw_core::channel::{Channel, IncomingMessage, OutgoingMessage};
use oneclaw_core::error::Result;
use tokio::sync::Mutex;

pub struct MyChannel {
    buffer: Mutex<Vec<IncomingMessage>>,
}

#[async_trait]
impl Channel for MyChannel {
    fn name(&self) -> &str { "my_channel" }
    
    async fn receive(&self) -> Result<Option<IncomingMessage>> {
        let mut buffer = self.buffer.lock().await;
        Ok(buffer.pop())
    }
    
    async fn send(&self, msg: &OutgoingMessage) -> Result<()> {
        // Send implementation
        Ok(())
    }
}

​

See Also

• ChannelManager - Multi-channel coordination
• Built-in Channels - CLI, TCP, Telegram, MQTT implementations