use futures_core::Stream;
use futures_util::StreamExt;
use std::collections::{HashMap, VecDeque};
use std::future::Future;
use std::path::Path;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use tokio::sync::{broadcast, oneshot, Mutex, Notify, RwLock};
use tokio::time::sleep;
use tracing::{error, info, warn};
use crate::cdn::CdnClient;
use crate::crypto;
use crate::error::{Result, WechatIlinkError};
use crate::protocol::{self, ILinkClient, ILinkClientOptions};
use crate::types::*;
use md5::{Digest, Md5};
use rand::Rng;
use serde_json::json;
use uuid::Uuid;
const EVENT_CHANNEL_CAPACITY: usize = 256;
#[derive(Debug, Clone)]
pub enum WechatEvent {
ContextObserved(WechatContext),
Message(IncomingMessage),
CursorAdvanced { account_key: String, cursor: String },
AuthSessionExpired { account_key: String },
UserInteractionRequested {
account_key: String,
user_id: Option<String>,
reason: UserInteractionReason,
},
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SendReceipt {
pub message_ids: Vec<String>,
pub visible_texts: Vec<String>,
}
impl SendReceipt {
pub fn last_message_id(&self) -> Option<&str> {
self.message_ids.last().map(String::as_str)
}
fn single(message_id: String) -> Self {
Self {
message_ids: vec![message_id],
visible_texts: Vec::new(),
}
}
fn empty() -> Self {
Self {
message_ids: Vec::new(),
visible_texts: Vec::new(),
}
}
fn append(&mut self, mut other: SendReceipt) {
self.message_ids.append(&mut other.message_ids);
self.visible_texts.append(&mut other.visible_texts);
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UserInteractionReason {
ContextExpiring {
observed_at: SystemTime,
expires_at: SystemTime,
remind_before: Duration,
},
OutboundRateLimitApproaching {
sent_count: usize,
window: Duration,
threshold: usize,
},
}
pub struct WechatEventStream<'a> {
inner: Pin<Box<dyn Stream<Item = Result<WechatEvent>> + Send + 'a>>,
}
impl<'a> WechatEventStream<'a> {
fn new(stream: impl Stream<Item = Result<WechatEvent>> + Send + 'a) -> Self {
Self {
inner: Box::pin(stream),
}
}
pub async fn next(&mut self) -> Option<Result<WechatEvent>> {
self.inner.next().await
}
}
impl Stream for WechatEventStream<'_> {
type Item = Result<WechatEvent>;
fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
self.inner.as_mut().poll_next(cx)
}
}
#[derive(Debug)]
pub enum LoginQrEvent {
QrCode { content: String },
StatusChanged { status: String },
NeedVerifyCode {
prompt: String,
responder: VerifyCodeResponder,
},
Confirmed { credentials: Credentials },
}
#[derive(Debug)]
pub struct VerifyCodeResponder {
tx: oneshot::Sender<Option<String>>,
}
impl VerifyCodeResponder {
pub fn send(self, code: impl Into<String>) -> std::result::Result<(), Option<String>> {
let code = Some(code.into());
self.tx.send(code)
}
pub fn cancel(self) -> std::result::Result<(), Option<String>> {
self.tx.send(None)
}
}
pub struct LoginQrStream<'a> {
inner: Pin<Box<dyn Stream<Item = Result<LoginQrEvent>> + Send + 'a>>,
}
impl<'a> LoginQrStream<'a> {
fn new(stream: impl Stream<Item = Result<LoginQrEvent>> + Send + 'a) -> Self {
Self {
inner: Box::pin(stream),
}
}
pub async fn next(&mut self) -> Option<Result<LoginQrEvent>> {
self.inner.next().await
}
}
impl Stream for LoginQrStream<'_> {
type Item = Result<LoginQrEvent>;
fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
self.inner.as_mut().poll_next(cx)
}
}
#[derive(Debug, Clone)]
pub struct WechatRateLimitOptions {
pub retry_after: Duration,
pub retry_attempts: usize,
pub interaction_window: Duration,
pub interaction_threshold: usize,
pub context_ttl: Duration,
pub context_remind_before: Duration,
}
impl Default for WechatRateLimitOptions {
fn default() -> Self {
Self {
retry_after: protocol::DEFAULT_RATE_LIMIT_RETRY_AFTER,
retry_attempts: 5,
interaction_window: Duration::from_secs(5 * 60),
interaction_threshold: 6,
context_ttl: Duration::from_secs(24 * 60 * 60),
context_remind_before: Duration::from_secs(30 * 60),
}
}
}
#[derive(Default)]
struct AccountRateLimitState {
sent_at: VecDeque<Instant>,
next_allowed_at: Option<Instant>,
}
struct ContextRefreshState {
user_id: String,
observed_at: SystemTime,
expires_at: SystemTime,
reminded: bool,
}
pub struct WechatIlinkClientBuilder {
base_url: Option<String>,
bot_agent: Option<String>,
ilink_app_id: Option<String>,
route_tag: Option<String>,
markdown_filter: bool,
rate_limit: WechatRateLimitOptions,
credentials: Option<Credentials>,
http_client: Option<reqwest::Client>,
}
impl Default for WechatIlinkClientBuilder {
fn default() -> Self {
Self {
base_url: None,
bot_agent: None,
ilink_app_id: None,
route_tag: None,
markdown_filter: true,
rate_limit: WechatRateLimitOptions::default(),
credentials: None,
http_client: None,
}
}
}
impl WechatIlinkClientBuilder {
pub fn base_url(mut self, base_url: impl Into<String>) -> Self {
self.base_url = Some(base_url.into());
self
}
pub fn bot_agent(mut self, bot_agent: impl Into<String>) -> Self {
self.bot_agent = Some(bot_agent.into());
self
}
pub fn ilink_app_id(mut self, ilink_app_id: impl Into<String>) -> Self {
self.ilink_app_id = Some(ilink_app_id.into());
self
}
pub fn route_tag(mut self, route_tag: impl Into<String>) -> Self {
self.route_tag = Some(route_tag.into());
self
}
pub fn markdown_filter(mut self, enabled: bool) -> Self {
self.markdown_filter = enabled;
self
}
pub fn rate_limit_options(mut self, options: WechatRateLimitOptions) -> Self {
self.rate_limit = options;
self
}
pub fn rate_limit_retry_after(mut self, retry_after: Duration) -> Self {
self.rate_limit.retry_after = if retry_after.is_zero() {
protocol::DEFAULT_RATE_LIMIT_RETRY_AFTER
} else {
retry_after
};
self
}
pub fn rate_limit_retry_attempts(mut self, retry_attempts: usize) -> Self {
self.rate_limit.retry_attempts = retry_attempts;
self
}
pub fn rate_limit_max_retries(mut self, max_retries: usize) -> Self {
self.rate_limit.retry_attempts = max_retries;
self
}
pub fn context_ttl(mut self, ttl: Duration) -> Self {
if !ttl.is_zero() {
self.rate_limit.context_ttl = ttl;
}
self
}
pub fn context_expiry_remind_before(mut self, remind_before: Duration) -> Self {
self.rate_limit.context_remind_before = remind_before;
self
}
pub fn rate_limit_interaction_window(mut self, window: Duration) -> Self {
if !window.is_zero() {
self.rate_limit.interaction_window = window;
}
self
}
pub fn rate_limit_interaction_threshold(mut self, threshold: usize) -> Self {
self.rate_limit.interaction_threshold = threshold;
self
}
pub fn credentials(mut self, credentials: Credentials) -> Self {
self.credentials = Some(credentials);
self
}
pub fn http_client(mut self, http_client: reqwest::Client) -> Self {
self.http_client = Some(http_client);
self
}
pub fn build(self) -> WechatIlinkClient {
WechatIlinkClient::from_builder(self)
}
}
pub struct WechatIlinkClient {
client: Arc<ILinkClient>,
cdn: CdnClient,
credentials: RwLock<Option<Credentials>>,
event_tx: broadcast::Sender<WechatEvent>,
rate_limit_states: Mutex<HashMap<String, AccountRateLimitState>>,
context_refresh_states: Mutex<HashMap<(String, String), ContextRefreshState>>,
rate_limit_notify: Notify,
base_url: RwLock<String>,
stopped: RwLock<bool>,
rate_limit: WechatRateLimitOptions,
}
impl WechatIlinkClient {
pub fn new() -> Self {
Self::builder().build()
}
pub fn builder() -> WechatIlinkClientBuilder {
WechatIlinkClientBuilder::default()
}
fn from_builder(builder: WechatIlinkClientBuilder) -> Self {
let base_url = builder
.credentials
.as_ref()
.map(|creds| creds.base_url.clone())
.or(builder.base_url)
.unwrap_or_else(|| protocol::DEFAULT_BASE_URL.to_string());
let options = ILinkClientOptions {
bot_agent: builder.bot_agent,
route_tag: builder.route_tag,
ilink_app_id: builder.ilink_app_id,
markdown_filter: builder.markdown_filter,
};
let (client, cdn) = match builder.http_client {
Some(http_client) => (
ILinkClient::with_http_client_and_options(http_client.clone(), options),
CdnClient::with_client(http_client),
),
None => (ILinkClient::with_options(options), CdnClient::new()),
};
Self {
client: Arc::new(client),
cdn,
credentials: RwLock::new(builder.credentials),
event_tx: broadcast::channel(EVENT_CHANNEL_CAPACITY).0,
rate_limit_states: Mutex::new(HashMap::new()),
context_refresh_states: Mutex::new(HashMap::new()),
rate_limit_notify: Notify::new(),
base_url: RwLock::new(base_url),
stopped: RwLock::new(false),
rate_limit: builder.rate_limit,
}
}
const MAX_QR_REFRESH: u32 = 3;
const FIXED_QR_BASE_URL: &'static str = "https://ilinkai.weixin.qq.com";
pub async fn set_credentials(&self, creds: Credentials) {
*self.base_url.write().await = creds.base_url.clone();
*self.credentials.write().await = Some(creds);
}
pub async fn credentials(&self) -> Option<Credentials> {
self.credentials.read().await.clone()
}
pub fn login_qr(&self) -> LoginQrStream<'_> {
LoginQrStream::new(async_stream::stream! {
let base_url = self.base_url.read().await.clone();
let mut qr_refresh_count = 0u32;
loop {
qr_refresh_count += 1;
if qr_refresh_count > Self::MAX_QR_REFRESH {
yield Err(WechatIlinkError::Auth(format!(
"QR code expired {} times — login aborted",
Self::MAX_QR_REFRESH
)));
return;
}
let qr = match self.client.get_qr_code(Self::FIXED_QR_BASE_URL).await {
Ok(qr) => qr,
Err(err) => {
yield Err(err);
return;
}
};
yield Ok(LoginQrEvent::QrCode {
content: qr.qrcode_img_content.clone(),
});
let mut last_status = String::new();
let mut current_poll_base_url = Self::FIXED_QR_BASE_URL.to_string();
let mut pending_verify_code: Option<String> = None;
loop {
let status = match self
.client
.poll_qr_status_with_verify_code(
¤t_poll_base_url,
&qr.qrcode,
pending_verify_code.as_deref(),
)
.await
{
Ok(status) => status,
Err(err) => {
yield Err(err);
return;
}
};
if status.status != last_status {
last_status = status.status.clone();
match status.status.as_str() {
"scaned" => info!("QR scanned — confirm in WeChat"),
"expired" => warn!("QR expired — requesting new one"),
"confirmed" => info!("Login confirmed"),
"need_verifycode" => info!("QR verification code required"),
"verify_code_blocked" => warn!("QR verification code blocked"),
"binded_redirect" => warn!("QR already bound"),
_ => {}
}
yield Ok(LoginQrEvent::StatusChanged {
status: status.status.clone(),
});
}
if status.status == "wait" {
sleep(Duration::from_secs(1)).await;
continue;
}
if status.status == "need_verifycode" {
let prompt = if pending_verify_code.is_some() {
"QR verification code mismatch"
} else {
"QR verification code required"
};
let (tx, rx) = oneshot::channel();
yield Ok(LoginQrEvent::NeedVerifyCode {
prompt: prompt.to_string(),
responder: VerifyCodeResponder { tx },
});
let code = match rx.await {
Ok(Some(value)) => value.trim().to_string(),
_ => String::new(),
};
if code.is_empty() {
yield Err(WechatIlinkError::Auth(
"QR verification code was not provided".into(),
));
return;
}
pending_verify_code = Some(code);
continue;
}
if status.status == "verify_code_blocked" {
break;
}
if status.status == "binded_redirect" {
yield Err(WechatIlinkError::Auth(
"QR login is already bound to this app".into(),
));
return;
}
if status.status == "confirmed" {
let token = match status.bot_token {
Some(token) => token,
None => {
yield Err(WechatIlinkError::Auth("missing bot_token".into()));
return;
}
};
let creds = Credentials {
token,
base_url: status.baseurl.unwrap_or_else(|| base_url.clone()),
account_id: status.ilink_bot_id.unwrap_or_default(),
user_id: status.ilink_user_id.unwrap_or_default(),
saved_at: Some(chrono_now()),
};
*self.credentials.write().await = Some(creds.clone());
*self.base_url.write().await = creds.base_url.clone();
yield Ok(LoginQrEvent::Confirmed { credentials: creds });
return;
}
if status.status == "scaned_but_redirect" {
if let Some(ref host) = status.redirect_host {
current_poll_base_url = format!("https://{}", host);
info!("IDC redirect, switching polling host to {}", host);
} else {
warn!("Received scaned_but_redirect but redirect_host is missing");
}
sleep(Duration::from_secs(2)).await;
continue;
}
if status.status == "scaned" && pending_verify_code.is_some() {
pending_verify_code = None;
}
if status.status == "expired" {
break;
}
sleep(Duration::from_secs(2)).await;
}
}
})
}
pub fn events_from_cursor(
self: Arc<Self>,
cursor: Option<String>,
) -> WechatEventStream<'static> {
let mut rx = self.event_tx.subscribe();
let runner = Arc::clone(&self);
let mut task =
tokio::spawn(async move { runner.run_loop(cursor.unwrap_or_default()).await });
let abort_on_drop = AbortOnDrop(task.abort_handle());
WechatEventStream::new(async_stream::stream! {
let _abort_on_drop = abort_on_drop;
loop {
tokio::select! {
biased;
result = &mut task => {
match result {
Ok(Ok(())) => return,
Ok(Err(err)) => {
yield Err(err);
return;
}
Err(err) => {
yield Err(WechatIlinkError::Other(format!(
"wechat poll task failed: {err}"
)));
return;
}
}
}
event = rx.recv() => match event {
Ok(event) => yield Ok(event),
Err(broadcast::error::RecvError::Lagged(skipped)) => {
yield Err(WechatIlinkError::Other(format!(
"wechat event stream lagged by {skipped} events"
)));
}
Err(broadcast::error::RecvError::Closed) => return,
}
}
}
})
}
fn emit_event(&self, event: WechatEvent) {
let _ = self.event_tx.send(event);
}
pub async fn reply(&self, msg: &IncomingMessage, text: &str) -> Result<SendReceipt> {
let context = msg
.context
.as_ref()
.ok_or_else(|| WechatIlinkError::NoContext(msg.user_id.clone()))?;
self.send_text_with_context(context, text).await
}
pub async fn send_text_with_context(
&self,
context: &WechatContext,
text: &str,
) -> Result<SendReceipt> {
self.send_text(&context.user_id, text, &context.context_token)
.await
}
pub async fn send_media_with_context(
&self,
context: &WechatContext,
content: SendContent,
) -> Result<SendReceipt> {
self.send_content(&context.user_id, &context.context_token, content)
.await
}
pub async fn send_typing_with_context(&self, context: &WechatContext) -> Result<()> {
let (base_url, token) = self.get_auth().await?;
let config = self
.retry_rate_limited(|| {
self.client
.get_config(&base_url, &token, &context.user_id, &context.context_token)
})
.await?;
if let Some(ticket) = config.typing_ticket {
self.retry_rate_limited(|| {
self.client
.send_typing(&base_url, &token, &context.user_id, &ticket, 1)
})
.await?;
}
Ok(())
}
pub async fn reply_media(
&self,
msg: &IncomingMessage,
content: SendContent,
) -> Result<SendReceipt> {
let context = msg
.context
.as_ref()
.ok_or_else(|| WechatIlinkError::NoContext(msg.user_id.clone()))?;
self.send_media_with_context(context, content).await
}
pub async fn download(&self, msg: &IncomingMessage) -> Result<Option<DownloadedMedia>> {
if let Some(img) = msg.images.first() {
if let Some(ref media) = img.media {
let data = self.cdn.download(media, img.aes_key.as_deref()).await?;
return Ok(Some(DownloadedMedia {
data,
media_type: "image".into(),
file_name: None,
format: None,
}));
}
}
if let Some(file) = msg.files.first() {
if let Some(ref media) = file.media {
require_download_aes_key("file", media)?;
let data = self.cdn.download(media, None).await?;
return Ok(Some(DownloadedMedia {
data,
media_type: "file".into(),
file_name: Some(file.file_name.clone().unwrap_or_else(|| "file.bin".into())),
format: None,
}));
}
}
if let Some(video) = msg.videos.first() {
if let Some(ref media) = video.media {
require_download_aes_key("video", media)?;
let data = self.cdn.download(media, None).await?;
return Ok(Some(DownloadedMedia {
data,
media_type: "video".into(),
file_name: None,
format: None,
}));
}
}
if let Some(voice) = msg.voices.first() {
if let Some(ref media) = voice.media {
require_download_aes_key("voice", media)?;
let data = self.cdn.download(media, None).await?;
return Ok(Some(DownloadedMedia {
data,
media_type: "voice".into(),
file_name: None,
format: Some("silk".into()),
}));
}
}
Ok(None)
}
pub async fn download_raw(
&self,
media: &CDNMedia,
aeskey_override: Option<&str>,
) -> Result<Vec<u8>> {
self.cdn.download(media, aeskey_override).await
}
pub async fn upload(
&self,
data: &[u8],
user_id: &str,
media_type: i32,
) -> Result<UploadResult> {
let (base_url, token) = self.get_auth().await?;
self.cdn_upload(&base_url, &token, data, user_id, media_type)
.await
}
async fn run_loop(&self, mut cursor: String) -> Result<()> {
*self.stopped.write().await = false;
info!("Long-poll loop started");
let mut retry_delay = Duration::from_secs(1);
if let Ok((base_url, token)) = self.get_auth().await {
match self.client.notify_start(&base_url, &token).await {
Ok(resp) if resp.ret.is_some_and(|ret| ret != 0) => warn!(
"notify_start returned ret={:?} errmsg={:?}",
resp.ret, resp.errmsg
),
Ok(_) => {}
Err(err) => warn!("notify_start failed: {}", err),
}
}
loop {
if *self.stopped.read().await {
break;
}
let (base_url, token) = self.get_auth().await?;
match self.client.get_updates(&base_url, &token, &cursor).await {
Ok(updates) => {
let account_key = self.account_key().await;
let new_cursor = updates.get_updates_buf.clone();
let mut cursor_changed = false;
if !new_cursor.is_empty() && cursor.as_str() != new_cursor.as_str() {
cursor_changed = true;
cursor = new_cursor.clone();
}
retry_delay = Duration::from_secs(1);
for wire in &updates.msgs {
if let Some(incoming) =
IncomingMessage::from_wire_for_account(wire, &account_key)
{
self.reset_account_rate_limit(&account_key).await;
if let Some(context) = incoming.context.clone() {
self.observe_context_for_interaction(&context).await;
self.emit_event(WechatEvent::ContextObserved(context));
}
self.emit_event(WechatEvent::Message(incoming.clone()));
}
}
self.emit_due_context_interaction_requests().await;
if cursor_changed {
self.emit_event(WechatEvent::CursorAdvanced {
account_key: account_key.clone(),
cursor: new_cursor.clone(),
});
}
}
Err(e) if e.is_session_expired() => {
warn!("Session expired — re-login required");
let account_key = self.account_key().await;
self.emit_event(WechatEvent::AuthSessionExpired {
account_key: account_key.clone(),
});
cursor.clear();
break;
}
Err(e) if e.is_rate_limited() => {
self.report_error(&e);
sleep(self.rate_limit.retry_after).await;
retry_delay = Duration::from_secs(1);
continue;
}
Err(e) => {
self.report_error(&e);
sleep(retry_delay).await;
retry_delay = std::cmp::min(retry_delay * 2, Duration::from_secs(10));
continue;
}
}
}
info!("Long-poll loop stopped");
if let Ok((base_url, token)) = self.get_auth().await {
match self.client.notify_stop(&base_url, &token).await {
Ok(resp) if resp.ret.is_some_and(|ret| ret != 0) => warn!(
"notify_stop returned ret={:?} errmsg={:?}",
resp.ret, resp.errmsg
),
Ok(_) => {}
Err(err) => warn!("notify_stop failed: {}", err),
}
}
Ok(())
}
async fn retry_rate_limited<F, Fut, T>(&self, mut operation: F) -> Result<T>
where
F: FnMut() -> Fut,
Fut: Future<Output = Result<T>>,
{
let account_key = self.account_key().await;
if let Some(wait) = self.active_rate_limit_backoff(&account_key).await {
return Err(rate_limited_error(wait));
}
let mut retries = 0usize;
loop {
match operation().await {
Ok(value) => return Ok(value),
Err(err) if err.is_rate_limited() => {
let err = with_rate_limit_retry_after(err, self.rate_limit.retry_after);
self.defer_account_rate_limit(&account_key, self.rate_limit.retry_after)
.await;
if retries >= self.rate_limit.retry_attempts {
return Err(err);
}
retries += 1;
self.wait_for_rate_limit_reset_or_timeout(
&account_key,
self.rate_limit.retry_after,
)
.await;
}
Err(err) => return Err(err),
}
}
}
async fn active_rate_limit_backoff(&self, account_key: &str) -> Option<Duration> {
if account_key.is_empty() {
return None;
}
let mut states = self.rate_limit_states.lock().await;
let state = states.entry(account_key.to_string()).or_default();
match state.next_allowed_at {
Some(next_allowed_at) => match next_allowed_at.checked_duration_since(Instant::now()) {
Some(wait) if !wait.is_zero() => Some(wait),
_ => {
state.next_allowed_at = None;
None
}
},
None => None,
}
}
async fn wait_for_rate_limit_reset_or_timeout(&self, account_key: &str, wait: Duration) {
if account_key.is_empty() || wait.is_zero() {
return;
}
let _ = tokio::time::timeout(wait, self.rate_limit_notify.notified()).await;
}
async fn defer_account_rate_limit(&self, account_key: &str, retry_after: Duration) {
if account_key.is_empty() {
return;
}
let next_allowed_at = Instant::now() + retry_after;
let mut states = self.rate_limit_states.lock().await;
let state = states.entry(account_key.to_string()).or_default();
if state
.next_allowed_at
.map_or(true, |current| current < next_allowed_at)
{
state.next_allowed_at = Some(next_allowed_at);
}
}
async fn reset_account_rate_limit(&self, account_key: &str) {
if account_key.is_empty() {
return;
}
let mut states = self.rate_limit_states.lock().await;
let state = states.entry(account_key.to_string()).or_default();
state.sent_at.clear();
state.next_allowed_at = None;
drop(states);
self.rate_limit_notify.notify_waiters();
}
async fn observe_context_for_interaction(&self, context: &WechatContext) {
let observed_at = SystemTime::now();
let expires_at = observed_at + self.rate_limit.context_ttl;
self.context_refresh_states.lock().await.insert(
(context.account_key.clone(), context.user_id.clone()),
ContextRefreshState {
user_id: context.user_id.clone(),
observed_at,
expires_at,
reminded: false,
},
);
}
async fn emit_due_context_interaction_requests(&self) {
if self.rate_limit.context_ttl.is_zero() {
return;
}
let now = SystemTime::now();
let mut events = Vec::new();
{
let mut contexts = self.context_refresh_states.lock().await;
contexts.retain(|_, state| !(state.reminded && now > state.expires_at));
for ((account_key, _), state) in contexts.iter_mut() {
if state.reminded {
continue;
}
let remind_at = state
.expires_at
.checked_sub(self.rate_limit.context_remind_before)
.unwrap_or(state.observed_at);
if now >= remind_at {
state.reminded = true;
events.push(WechatEvent::UserInteractionRequested {
account_key: account_key.clone(),
user_id: Some(state.user_id.clone()),
reason: UserInteractionReason::ContextExpiring {
observed_at: state.observed_at,
expires_at: state.expires_at,
remind_before: self.rate_limit.context_remind_before,
},
});
}
}
}
for event in events {
self.emit_event(event);
}
}
async fn record_successful_message_send(&self) {
let account_key = self.account_key().await;
if account_key.is_empty() || self.rate_limit.interaction_threshold == 0 {
return;
}
let now = Instant::now();
let mut event = None;
{
let mut states = self.rate_limit_states.lock().await;
let state = states.entry(account_key.clone()).or_default();
while let Some(sent_at) = state.sent_at.front().copied() {
if now.duration_since(sent_at) > self.rate_limit.interaction_window {
state.sent_at.pop_front();
} else {
break;
}
}
state.sent_at.push_back(now);
let sent_count = state.sent_at.len();
if sent_count == self.rate_limit.interaction_threshold {
event = Some(WechatEvent::UserInteractionRequested {
account_key,
user_id: None,
reason: UserInteractionReason::OutboundRateLimitApproaching {
sent_count,
window: self.rate_limit.interaction_window,
threshold: self.rate_limit.interaction_threshold,
},
});
}
}
if let Some(event) = event {
self.emit_event(event);
}
}
pub async fn stop(&self) {
*self.stopped.write().await = true;
}
fn send_content<'a>(
&'a self,
user_id: &'a str,
context_token: &'a str,
content: SendContent,
) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<SendReceipt>> + Send + 'a>> {
Box::pin(async move {
let (base_url, token) = self.get_auth().await?;
match content {
SendContent::Text(text) => self.send_text(user_id, &text, context_token).await,
SendContent::Image { data, caption } => {
let result = self
.cdn_upload(&base_url, &token, &data, user_id, 1)
.await?;
let mut receipt = SendReceipt::empty();
if let Some(cap) = caption {
receipt.append(self.send_text(user_id, &cap, context_token).await?);
}
let item = json!({"type": 2, "image_item": {
"media": cdn_media_json(&result.media),
"mid_size": result.encrypted_file_size,
}});
receipt.append(
self.send_media_item(&base_url, &token, user_id, context_token, item)
.await?,
);
Ok(receipt)
}
SendContent::Video { data, caption } => {
let result = self
.cdn_upload(&base_url, &token, &data, user_id, 2)
.await?;
let mut receipt = SendReceipt::empty();
if let Some(cap) = caption {
receipt.append(self.send_text(user_id, &cap, context_token).await?);
}
let item = json!({"type": 5, "video_item": {
"media": cdn_media_json(&result.media),
"video_size": result.encrypted_file_size,
}});
receipt.append(
self.send_media_item(&base_url, &token, user_id, context_token, item)
.await?,
);
Ok(receipt)
}
SendContent::File {
data,
file_name,
caption,
} => {
let cat = categorize_by_extension(&file_name);
match cat {
"image" => {
self.send_content(
user_id,
context_token,
SendContent::Image { data, caption },
)
.await
}
"video" => {
self.send_content(
user_id,
context_token,
SendContent::Video { data, caption },
)
.await
}
_ => {
let mut receipt = SendReceipt::empty();
if let Some(cap) = caption {
receipt.append(self.send_text(user_id, &cap, context_token).await?);
}
let data_len = data.len();
let result = self
.cdn_upload(&base_url, &token, &data, user_id, 3)
.await?;
let item = json!({"type": 4, "file_item": {
"media": cdn_media_json(&result.media),
"file_name": file_name,
"len": data_len.to_string(),
}});
receipt.append(
self.send_media_item(
&base_url,
&token,
user_id,
context_token,
item,
)
.await?,
);
Ok(receipt)
}
}
}
}
})
}
async fn send_media_item(
&self,
base_url: &str,
token: &str,
user_id: &str,
context_token: &str,
item: serde_json::Value,
) -> Result<SendReceipt> {
let client_id = Uuid::new_v4().to_string();
let msg = protocol::build_media_message_with_client_id(
user_id,
context_token,
vec![item],
&client_id,
);
self.retry_rate_limited(|| self.client.send_message(base_url, token, &msg))
.await?;
self.record_successful_message_send().await;
Ok(SendReceipt::single(client_id))
}
async fn cdn_upload(
&self,
base_url: &str,
token: &str,
data: &[u8],
user_id: &str,
media_type: i32,
) -> Result<UploadResult> {
let aes_key = crypto::generate_aes_key();
let ciphertext = crypto::encrypt_aes_ecb(data, &aes_key);
let mut filekey_buf = [0u8; 16];
rand::rng().fill_bytes(&mut filekey_buf);
let filekey = hex::encode(filekey_buf);
let raw_md5 = hex::encode(Md5::digest(data));
let params = protocol::GetUploadUrlParams {
filekey: filekey.clone(),
media_type,
to_user_id: user_id.to_string(),
rawsize: data.len(),
rawfilemd5: raw_md5,
filesize: ciphertext.len(),
thumb_rawsize: None,
thumb_rawfilemd5: None,
thumb_filesize: None,
no_need_thumb: true,
aeskey: crypto::encode_aes_key_hex(&aes_key),
};
let upload_resp = self.client.get_upload_url(base_url, token, ¶ms).await?;
let upload_url = resolve_cdn_upload_url(&upload_resp, &filekey)?;
let encrypted_file_size = ciphertext.len();
let encrypt_query_param = self.client.upload_to_cdn(&upload_url, &ciphertext).await?;
Ok(UploadResult {
media: CDNMedia {
encrypt_query_param: Some(encrypt_query_param),
aes_key: Some(crypto::encode_aes_key_base64(&aes_key)),
encrypt_type: Some(1),
full_url: None,
},
aes_key,
encrypted_file_size,
})
}
async fn send_text(
&self,
user_id: &str,
text: &str,
context_token: &str,
) -> Result<SendReceipt> {
let (base_url, token) = self.get_auth().await?;
let mut message_ids = Vec::new();
let mut visible_texts = Vec::new();
for chunk in chunk_text(text, 4000) {
let client_id = Uuid::new_v4().to_string();
let msg = self.client.build_text_message_with_client_id(
user_id,
context_token,
&chunk,
&client_id,
);
self.retry_rate_limited(|| self.client.send_message(&base_url, &token, &msg))
.await?;
self.record_successful_message_send().await;
message_ids.push(client_id);
visible_texts.push(chunk);
}
Ok(SendReceipt {
message_ids,
visible_texts,
})
}
async fn get_auth(&self) -> Result<(String, String)> {
let creds = self.credentials.read().await;
let creds = creds
.as_ref()
.ok_or_else(|| WechatIlinkError::Auth("not logged in".into()))?;
Ok((creds.base_url.clone(), creds.token.clone()))
}
async fn account_key(&self) -> String {
let creds = self.credentials.read().await;
match creds.as_ref() {
Some(c) => context_account_key(c).to_string(),
None => String::new(),
}
}
fn report_error(&self, err: &WechatIlinkError) {
error!("{}", err);
}
}
#[cfg(test)]
fn event_stream_from_receiver(
mut rx: broadcast::Receiver<WechatEvent>,
) -> WechatEventStream<'static> {
WechatEventStream::new(async_stream::stream! {
loop {
match rx.recv().await {
Ok(event) => yield Ok(event),
Err(broadcast::error::RecvError::Lagged(skipped)) => {
yield Err(WechatIlinkError::Other(format!(
"wechat event stream lagged by {skipped} events"
)));
}
Err(broadcast::error::RecvError::Closed) => return,
}
}
})
}
struct AbortOnDrop(tokio::task::AbortHandle);
impl Drop for AbortOnDrop {
fn drop(&mut self) {
self.0.abort();
}
}
fn rate_limited_error(retry_after: Duration) -> WechatIlinkError {
WechatIlinkError::RateLimited {
retry_after,
message: "ret=-2".to_string(),
http_status: 200,
errcode: -2,
}
}
fn with_rate_limit_retry_after(err: WechatIlinkError, retry_after: Duration) -> WechatIlinkError {
match err {
WechatIlinkError::RateLimited {
message,
http_status,
errcode,
..
} => WechatIlinkError::RateLimited {
retry_after,
message,
http_status,
errcode,
},
other => other,
}
}
pub enum SendContent {
Text(String),
Image {
data: Vec<u8>,
caption: Option<String>,
},
Video {
data: Vec<u8>,
caption: Option<String>,
},
File {
data: Vec<u8>,
file_name: String,
caption: Option<String>,
},
}
fn cdn_media_json(media: &CDNMedia) -> serde_json::Value {
let mut v = json!({});
if let Some(param) = &media.encrypt_query_param {
v["encrypt_query_param"] = json!(param);
}
if let Some(key) = &media.aes_key {
v["aes_key"] = json!(key);
}
if let Some(et) = media.encrypt_type {
v["encrypt_type"] = json!(et);
}
if let Some(url) = &media.full_url {
v["full_url"] = json!(url);
}
v
}
fn resolve_cdn_upload_url(
response: &protocol::GetUploadUrlResponse,
filekey: &str,
) -> Result<String> {
if let Some(upload_full_url) = response
.upload_full_url
.as_deref()
.filter(|value| !value.is_empty())
{
return Ok(upload_full_url.to_string());
}
if let Some(upload_param) = response
.upload_param
.as_deref()
.filter(|value| !value.is_empty())
{
return Ok(protocol::build_cdn_upload_url(
protocol::CDN_BASE_URL,
upload_param,
filekey,
));
}
Err(WechatIlinkError::Media(
"getuploadurl did not return upload_full_url or upload_param".into(),
))
}
fn require_download_aes_key(media_type: &str, media: &CDNMedia) -> Result<()> {
if media
.aes_key
.as_deref()
.is_some_and(|value| !value.is_empty())
{
return Ok(());
}
Err(WechatIlinkError::Media(format!(
"{} CDN media missing AES key",
media_type
)))
}
fn categorize_by_extension(filename: &str) -> &'static str {
let ext = Path::new(filename)
.extension()
.and_then(|e| e.to_str())
.unwrap_or("")
.to_lowercase();
match ext.as_str() {
"png" | "jpg" | "jpeg" | "gif" | "webp" | "bmp" | "svg" => "image",
"mp4" | "mov" | "webm" | "mkv" | "avi" => "video",
_ => "file",
}
}
fn chunk_text(text: &str, limit: usize) -> Vec<String> {
if text.len() <= limit {
return vec![text.to_string()];
}
let mut chunks = Vec::new();
let mut remaining = text;
while !remaining.is_empty() {
if remaining.len() <= limit {
chunks.push(remaining.to_string());
break;
}
let window_end = char_boundary_at_or_before(remaining, limit);
let window = &remaining[..window_end];
let cut = window
.rfind("\n\n")
.filter(|&i| i > window_end * 3 / 10)
.map(|i| i + 2)
.or_else(|| {
window
.rfind('\n')
.filter(|&i| i > window_end * 3 / 10)
.map(|i| i + 1)
})
.or_else(|| {
window
.rfind(' ')
.filter(|&i| i > window_end * 3 / 10)
.map(|i| i + 1)
})
.unwrap_or(window_end);
chunks.push(remaining[..cut].to_string());
remaining = &remaining[cut..];
}
if chunks.is_empty() {
vec![String::new()]
} else {
chunks
}
}
fn char_boundary_at_or_before(text: &str, limit: usize) -> usize {
let mut end = limit.min(text.len());
while !text.is_char_boundary(end) {
end -= 1;
}
end
}
fn context_account_key(creds: &Credentials) -> &str {
if !creds.account_id.is_empty() {
&creds.account_id
} else {
&creds.user_id
}
}
fn chrono_now() -> String {
let dur = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
format!("{}Z", dur.as_secs())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn builder_accepts_caller_provided_reqwest_client() {
let http_client = reqwest::Client::new();
let _client = WechatIlinkClient::builder()
.http_client(http_client)
.build();
}
#[test]
fn chunk_text_short() {
let chunks = chunk_text("hello", 100);
assert_eq!(chunks, vec!["hello"]);
}
#[test]
fn chunk_text_empty() {
let chunks = chunk_text("", 100);
assert_eq!(chunks, vec![""]);
}
#[test]
fn chunk_text_splits_on_paragraph() {
let text = "aaaa\n\nbbbb";
let chunks = chunk_text(text, 7);
assert_eq!(chunks, vec!["aaaa\n\n", "bbbb"]);
}
#[test]
fn chunk_text_splits_on_newline() {
let text = "aaaa\nbbbb";
let chunks = chunk_text(text, 7);
assert_eq!(chunks, vec!["aaaa\n", "bbbb"]);
}
#[test]
fn chunk_text_exact_limit() {
let text = "abcdef";
let chunks = chunk_text(text, 6);
assert_eq!(chunks, vec!["abcdef"]);
}
#[test]
fn chunk_text_does_not_split_utf8_char_boundary() {
let mut text = "a".repeat(3999);
text.push('启');
text.push_str("tail");
let chunks = chunk_text(&text, 4000);
assert_eq!(chunks.concat(), text);
assert!(chunks.iter().all(|chunk| chunk.len() <= 4000));
}
#[test]
fn categorize_image_extensions() {
assert_eq!(categorize_by_extension("photo.png"), "image");
assert_eq!(categorize_by_extension("photo.JPG"), "image");
assert_eq!(categorize_by_extension("anim.gif"), "image");
assert_eq!(categorize_by_extension("pic.webp"), "image");
}
#[test]
fn categorize_video_extensions() {
assert_eq!(categorize_by_extension("clip.mp4"), "video");
assert_eq!(categorize_by_extension("clip.MOV"), "video");
assert_eq!(categorize_by_extension("movie.webm"), "video");
}
#[test]
fn categorize_file_extensions() {
assert_eq!(categorize_by_extension("report.pdf"), "file");
assert_eq!(categorize_by_extension("data.csv"), "file");
assert_eq!(categorize_by_extension("noext"), "file");
}
#[test]
fn cdn_media_json_with_encrypt_type() {
let media = CDNMedia {
encrypt_query_param: Some("param=1".to_string()),
aes_key: Some("key123".to_string()),
encrypt_type: Some(1),
full_url: None,
};
let j = cdn_media_json(&media);
assert_eq!(j["encrypt_query_param"], "param=1");
assert_eq!(j["aes_key"], "key123");
assert_eq!(j["encrypt_type"], 1);
}
#[test]
fn cdn_media_json_without_encrypt_type() {
let media = CDNMedia {
encrypt_query_param: Some("p".to_string()),
aes_key: Some("k".to_string()),
encrypt_type: None,
full_url: None,
};
let j = cdn_media_json(&media);
assert!(j.get("encrypt_type").is_none());
}
#[test]
fn upload_url_prefers_full_url() {
let response = protocol::GetUploadUrlResponse {
upload_param: Some("param".to_string()),
thumb_upload_param: None,
upload_full_url: Some("https://cdn.example/upload".to_string()),
};
let upload_url = resolve_cdn_upload_url(&response, "file-key").unwrap();
assert_eq!(upload_url, "https://cdn.example/upload");
}
#[test]
fn upload_url_falls_back_to_upload_param() {
let response = protocol::GetUploadUrlResponse {
upload_param: Some("param value".to_string()),
thumb_upload_param: None,
upload_full_url: None,
};
let upload_url = resolve_cdn_upload_url(&response, "file key").unwrap();
assert_eq!(
upload_url,
format!(
"{}/upload?encrypted_query_param=param%20value&filekey=file%20key",
protocol::CDN_BASE_URL
)
);
}
#[test]
fn upload_url_requires_full_url_or_upload_param() {
let response = protocol::GetUploadUrlResponse {
upload_param: None,
thumb_upload_param: None,
upload_full_url: None,
};
let err = resolve_cdn_upload_url(&response, "file-key").unwrap_err();
assert!(matches!(err, WechatIlinkError::Media(_)));
}
#[test]
fn non_image_download_requires_media_aes_key() {
let media = CDNMedia {
encrypt_query_param: Some("param".to_string()),
aes_key: None,
encrypt_type: Some(1),
full_url: None,
};
let err = require_download_aes_key("voice", &media).unwrap_err();
assert!(matches!(err, WechatIlinkError::Media(_)));
}
#[test]
fn non_image_download_accepts_media_aes_key() {
let media = CDNMedia {
encrypt_query_param: Some("param".to_string()),
aes_key: Some("key".to_string()),
encrypt_type: Some(1),
full_url: None,
};
require_download_aes_key("file", &media).unwrap();
}
#[tokio::test]
async fn events_from_cursor_reports_missing_auth_without_storing_cursor() {
let client = Arc::new(WechatIlinkClient::new());
let mut events = client.events_from_cursor(Some("external-cursor".to_string()));
let err = events
.next()
.await
.expect("stream item")
.expect_err("missing auth should be surfaced through stream");
assert!(matches!(err, WechatIlinkError::Auth(_)));
}
#[test]
fn rate_limit_builder_defaults_and_overrides_are_available() {
let default_options = WechatRateLimitOptions::default();
assert_eq!(default_options.retry_after, Duration::from_secs(90));
assert_eq!(default_options.retry_attempts, 5);
assert_eq!(default_options.interaction_window, Duration::from_secs(300));
assert_eq!(default_options.interaction_threshold, 6);
assert_eq!(
default_options.context_ttl,
Duration::from_secs(24 * 60 * 60)
);
let client = WechatIlinkClient::builder()
.rate_limit_retry_after(Duration::from_secs(60))
.rate_limit_max_retries(2)
.rate_limit_interaction_window(Duration::from_secs(120))
.rate_limit_interaction_threshold(4)
.context_ttl(Duration::from_secs(3600))
.context_expiry_remind_before(Duration::from_secs(300))
.build();
assert_eq!(client.rate_limit.retry_after, Duration::from_secs(60));
assert_eq!(client.rate_limit.retry_attempts, 2);
assert_eq!(
client.rate_limit.interaction_window,
Duration::from_secs(120)
);
assert_eq!(client.rate_limit.interaction_threshold, 4);
assert_eq!(client.rate_limit.context_ttl, Duration::from_secs(3600));
assert_eq!(
client.rate_limit.context_remind_before,
Duration::from_secs(300)
);
}
#[tokio::test]
async fn outbound_threshold_emits_interaction_event_and_incoming_resets_window() {
let client = WechatIlinkClient::builder()
.rate_limit_interaction_threshold(3)
.rate_limit_interaction_window(Duration::from_secs(300))
.build();
client.set_credentials(test_credentials()).await;
let mut events = event_stream_from_receiver(client.event_tx.subscribe());
client.record_successful_message_send().await;
client.record_successful_message_send().await;
assert!(
tokio::time::timeout(Duration::from_millis(5), events.next())
.await
.is_err()
);
client.record_successful_message_send().await;
assert_rate_limit_event(events.next().await, "account-1", 3, 3);
client.record_successful_message_send().await;
assert!(
tokio::time::timeout(Duration::from_millis(5), events.next())
.await
.is_err()
);
client.reset_account_rate_limit("account-1").await;
client.record_successful_message_send().await;
client.record_successful_message_send().await;
client.record_successful_message_send().await;
assert_rate_limit_event(events.next().await, "account-1", 3, 3);
}
#[tokio::test]
async fn context_expiry_emits_user_interaction_event_and_new_context_resets_it() {
let client = WechatIlinkClient::builder()
.context_ttl(Duration::from_millis(5))
.context_expiry_remind_before(Duration::from_millis(5))
.build();
let mut events = event_stream_from_receiver(client.event_tx.subscribe());
let context = WechatContext {
account_key: "account-1".to_string(),
user_id: "user-1".to_string(),
context_token: "ctx-1".to_string(),
observed_at_unix_ms: 1,
source_message_id: Some("msg-1".to_string()),
};
client.observe_context_for_interaction(&context).await;
tokio::time::sleep(Duration::from_millis(10)).await;
client.emit_due_context_interaction_requests().await;
assert_context_expiring_event(events.next().await, "account-1", "user-1");
client.observe_context_for_interaction(&context).await;
tokio::time::sleep(Duration::from_millis(10)).await;
client.emit_due_context_interaction_requests().await;
assert_context_expiring_event(events.next().await, "account-1", "user-1");
}
#[tokio::test]
async fn retry_rate_limited_uses_configured_retry_count() {
use std::sync::atomic::{AtomicUsize, Ordering};
let client = WechatIlinkClient::builder()
.rate_limit_retry_after(Duration::from_millis(1))
.rate_limit_max_retries(2)
.build();
client.set_credentials(test_credentials()).await;
let attempts = Arc::new(AtomicUsize::new(0));
let attempts_for_operation = Arc::clone(&attempts);
let err = client
.retry_rate_limited(move || {
let attempts_for_operation = Arc::clone(&attempts_for_operation);
async move {
attempts_for_operation.fetch_add(1, Ordering::SeqCst);
Err::<(), _>(rate_limited_error(Duration::from_millis(1)))
}
})
.await
.expect_err("rate limit should remain after configured retries");
assert!(err.is_rate_limited());
assert_eq!(attempts.load(Ordering::SeqCst), 3);
}
#[tokio::test]
async fn active_rate_limit_backoff_returns_error_without_queueing_new_request() {
let client = WechatIlinkClient::builder()
.rate_limit_retry_after(Duration::from_secs(90))
.build();
client.set_credentials(test_credentials()).await;
client
.defer_account_rate_limit("account-1", Duration::from_secs(90))
.await;
let mut called = false;
let err = client
.retry_rate_limited(|| {
called = true;
async { Ok::<_, WechatIlinkError>(()) }
})
.await
.expect_err("active backoff should return immediately");
assert!(!called);
assert!(err.is_rate_limited());
}
#[tokio::test]
async fn event_stream_accepts_context_observed_and_cursor_events() {
let client = WechatIlinkClient::new();
let mut events = event_stream_from_receiver(client.event_tx.subscribe());
client.emit_event(WechatEvent::ContextObserved(WechatContext {
account_key: "account-1".to_string(),
user_id: "user-1".to_string(),
context_token: "ctx-1".to_string(),
observed_at_unix_ms: 1,
source_message_id: Some("msg-1".to_string()),
}));
client.emit_event(WechatEvent::CursorAdvanced {
account_key: "account-1".to_string(),
cursor: "cursor-2".to_string(),
});
assert_eq!(format_event(events.next().await), "context:user-1");
assert_eq!(format_event(events.next().await), "cursor:cursor-2");
}
fn assert_rate_limit_event(
event: Option<Result<WechatEvent>>,
expected_account: &str,
expected_sent_count: usize,
expected_threshold: usize,
) {
match event.expect("event").expect("ok event") {
WechatEvent::UserInteractionRequested {
account_key,
reason:
UserInteractionReason::OutboundRateLimitApproaching {
sent_count,
threshold,
..
},
..
} => {
assert_eq!(account_key, expected_account);
assert_eq!(sent_count, expected_sent_count);
assert_eq!(threshold, expected_threshold);
}
other => panic!("expected rate-limit interaction event, got {other:?}"),
}
}
fn assert_context_expiring_event(
event: Option<Result<WechatEvent>>,
expected_account: &str,
expected_user: &str,
) {
match event.expect("event").expect("ok event") {
WechatEvent::UserInteractionRequested {
account_key,
user_id,
reason: UserInteractionReason::ContextExpiring { .. },
} => {
assert_eq!(account_key, expected_account);
assert_eq!(user_id.as_deref(), Some(expected_user));
}
other => panic!("expected context-expiring interaction event, got {other:?}"),
}
}
fn format_event(event: Option<Result<WechatEvent>>) -> String {
match event.expect("event").expect("ok event") {
WechatEvent::ContextObserved(ctx) => format!("context:{}", ctx.user_id),
WechatEvent::CursorAdvanced { cursor, .. } => format!("cursor:{cursor}"),
WechatEvent::Message(msg) => format!("message:{}", msg.user_id),
WechatEvent::AuthSessionExpired { account_key } => format!("auth:{account_key}"),
WechatEvent::UserInteractionRequested { reason, .. } => match reason {
UserInteractionReason::OutboundRateLimitApproaching { sent_count, .. } => {
format!("rate-limit:{sent_count}")
}
UserInteractionReason::ContextExpiring { .. } => "context-expiring".into(),
},
}
}
fn test_credentials() -> Credentials {
Credentials {
token: "token-1".into(),
base_url: "https://example.invalid".into(),
account_id: "account-1".into(),
user_id: "bot-1".into(),
saved_at: None,
}
}
#[tokio::test]
async fn credentials_are_supplied_by_caller() {
let client = WechatIlinkClient::new();
client.set_credentials(test_credentials()).await;
let creds = client.credentials().await.unwrap();
assert_eq!(creds.account_id, "account-1");
}
}