Skip to main content

walrus_pchannel/
lib.rs

1//! Channel abstraction for the walrus protocol.
2//!
3//! Defines the [`Channel`] trait, platform types, message types, routing,
4//! and menu abstractions. Channel implementations (e.g. Telegram) live in
5//! separate crates and implement [`Channel`] to produce a [`ChannelHandle`].
6
7use anyhow::Result;
8use compact_str::CompactString;
9use std::{future::Future, pin::Pin, sync::Arc};
10use tokio::sync::mpsc;
11
12/// Type-erased async sender function.
13type SenderFn =
14    Arc<dyn Fn(ChannelMessage) -> Pin<Box<dyn Future<Output = Result<()>> + Send>> + Send + Sync>;
15
16pub mod menu;
17pub mod router;
18
19pub use router::{ChannelRouter, RoutingRule, parse_platform};
20
21/// Messaging platform identifier.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23#[non_exhaustive]
24pub enum Platform {
25    /// Telegram messaging platform.
26    Telegram,
27}
28
29/// A message received from or sent to a channel.
30#[derive(Debug, Clone)]
31pub struct ChannelMessage {
32    /// Platform this message belongs to.
33    pub platform: Platform,
34    /// Channel/chat identifier on the platform.
35    pub channel_id: CompactString,
36    /// Sender identifier on the platform.
37    pub sender_id: CompactString,
38    /// Message text content.
39    pub content: String,
40    /// Attached files or media.
41    pub attachments: Vec<Attachment>,
42    /// ID of the message being replied to, if any.
43    pub reply_to: Option<CompactString>,
44    /// Unix timestamp when the message was created.
45    pub timestamp: u64,
46}
47
48/// A file or media attachment.
49#[derive(Debug, Clone)]
50pub struct Attachment {
51    /// Type of attachment.
52    pub kind: AttachmentKind,
53    /// URL or path to the attachment.
54    pub url: String,
55    /// Optional human-readable name.
56    pub name: Option<String>,
57}
58
59/// Type of attachment content.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub enum AttachmentKind {
62    /// Image file (PNG, JPG, etc.).
63    Image,
64    /// Generic file.
65    File,
66    /// Audio file.
67    Audio,
68    /// Video file.
69    Video,
70}
71
72impl From<ChannelMessage> for wcore::model::Message {
73    fn from(msg: ChannelMessage) -> Self {
74        wcore::model::Message::user(msg.content)
75    }
76}
77
78/// A live channel connection that can receive and send messages.
79///
80/// Created by [`Channel::connect`]. Owns all connection state internally
81/// via `Arc`, so both recv and send work concurrently without lifetime issues.
82pub struct ChannelHandle {
83    /// Platform for this handle.
84    platform: Platform,
85    /// Incoming message receiver.
86    rx: mpsc::UnboundedReceiver<ChannelMessage>,
87    /// Send function (boxed for type erasure across channel implementations).
88    sender: SenderFn,
89}
90
91impl ChannelHandle {
92    /// Create a new channel handle.
93    pub fn new<F, Fut>(
94        platform: Platform,
95        rx: mpsc::UnboundedReceiver<ChannelMessage>,
96        sender: F,
97    ) -> Self
98    where
99        F: Fn(ChannelMessage) -> Fut + Send + Sync + 'static,
100        Fut: Future<Output = Result<()>> + Send + 'static,
101    {
102        Self {
103            platform,
104            rx,
105            sender: Arc::new(move |msg| Box::pin(sender(msg))),
106        }
107    }
108
109    /// The platform this handle connects to.
110    pub fn platform(&self) -> Platform {
111        self.platform
112    }
113
114    /// Receive the next incoming message.
115    pub async fn recv(&mut self) -> Option<ChannelMessage> {
116        self.rx.recv().await
117    }
118
119    /// Send a message through the channel.
120    pub async fn send(&self, message: ChannelMessage) -> Result<()> {
121        (self.sender)(message).await
122    }
123
124    /// Get a cloneable sender for use from other tasks.
125    pub fn sender(&self) -> ChannelSender {
126        ChannelSender {
127            platform: self.platform,
128            sender: Arc::clone(&self.sender),
129        }
130    }
131}
132
133/// A cloneable sender extracted from a [`ChannelHandle`].
134///
135/// Use [`ChannelHandle::sender`] to get a sender that can be moved
136/// into spawned tasks for concurrent send operations.
137#[derive(Clone)]
138pub struct ChannelSender {
139    /// Platform for this sender.
140    platform: Platform,
141    /// Send function.
142    sender: SenderFn,
143}
144
145impl ChannelSender {
146    /// The platform this sender connects to.
147    pub fn platform(&self) -> Platform {
148        self.platform
149    }
150
151    /// Send a message through the channel.
152    pub async fn send(&self, message: ChannelMessage) -> Result<()> {
153        (self.sender)(message).await
154    }
155}
156
157/// A connection to a messaging platform.
158///
159/// Implementations provide platform-specific connection logic. Call
160/// [`connect`](Channel::connect) to establish a live connection and
161/// get a [`ChannelHandle`] for receiving and sending messages.
162pub trait Channel: Send {
163    /// Open a connection and return a handle for bidirectional messaging.
164    ///
165    /// Consumes self — the handle owns all connection state.
166    fn connect(self) -> impl Future<Output = Result<ChannelHandle>> + Send;
167}