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}