Skip to main content

wechat_protocol/
account_operations.rs

1//! Account-owned asynchronous protocol operations.
2use super::*;
3
4impl NativeClient {
5    /// Fetch one sync page using the owned account. The application still owns
6    /// command retention, projection and committing the returned cursor.
7    pub async fn sync(&self, cursor: &[u8]) -> Result<crate::SyncBatch> {
8        let cursor = cursor.to_vec();
9        self.account_request(move |transport, state, _| transport.sync_snapshot(state, &cursor))
10            .await
11    }
12
13    pub async fn heartbeat(&self, cursor: &[u8]) -> Result<crate::Heartbeat> {
14        let cursor = cursor.to_vec();
15        self.account_request(move |transport, state, _| {
16            transport.heartbeat_snapshot(state, &cursor)
17        })
18        .await
19    }
20
21    pub async fn sync_scene(&self, cursor: &[u8], scene: u32) -> Result<crate::SyncBatch> {
22        let cursor = cursor.to_vec();
23        self.account_request(move |transport, state, _| {
24            transport.sync_scene_snapshot(state, &cursor, scene)
25        })
26        .await
27    }
28
29    pub async fn lookup_contacts(&self, usernames: &[String]) -> Result<crate::ContactLookup> {
30        let usernames = usernames.to_vec();
31        self.account_request(move |transport, state, _| {
32            transport.lookup_contacts_snapshot(state, &usernames)
33        })
34        .await
35    }
36
37    pub async fn lookup_room(&self, room_id: &str, version: u32) -> Result<crate::RoomRoster> {
38        let room_id = room_id.to_owned();
39        self.account_request(move |transport, state, _| {
40            transport.lookup_room_snapshot(state, &room_id, version)
41        })
42        .await
43    }
44
45    pub async fn init_contacts(
46        &self,
47        contact_sequence: u32,
48        room_sequence: u32,
49    ) -> Result<crate::InitContactPage> {
50        self.account_request(move |transport, state, _| {
51            transport.init_contacts_snapshot(state, contact_sequence, room_sequence)
52        })
53        .await
54    }
55
56    pub async fn download_avatars(&self, usernames: &[String]) -> Result<Vec<crate::AvatarBytes>> {
57        let usernames = usernames.to_vec();
58        self.account_request(move |transport, state, _| {
59            transport.download_avatars_snapshot(state, &usernames)
60        })
61        .await
62    }
63
64    pub async fn download_voice_chunk(
65        &self,
66        server_message_id: u64,
67        total_length: u32,
68        offset: u32,
69    ) -> Result<crate::VoiceChunk> {
70        self.account_request(move |transport, state, _| {
71            transport.download_voice_chunk_snapshot(state, server_message_id, total_length, offset)
72        })
73        .await
74    }
75
76    pub async fn cdn_config(&self) -> Result<crate::media::CdnConfig> {
77        self.account_request(|transport, state, _| transport.cdn_config_snapshot(state))
78            .await
79    }
80
81    pub async fn large_cdn_config(
82        &self,
83        route: crate::media::LargeCdnRoute,
84    ) -> Result<crate::media::CdnConfig> {
85        self.account_request(move |transport, state, _| {
86            transport.large_cdn_config_snapshot(state, route)
87        })
88        .await
89    }
90
91    pub async fn group_inventory(&self, cursor: &[u8]) -> Result<crate::GroupMetadataPage> {
92        let cursor = cursor.to_vec();
93        self.account_request(move |transport, state, _| {
94            transport.group_inventory_snapshot(state, &cursor)
95        })
96        .await
97    }
98
99    pub async fn lookup_contacts_raw(&self, usernames: &[String]) -> Result<Vec<u8>> {
100        let usernames = usernames.to_vec();
101        self.account_request(move |transport, state, _| {
102            transport.lookup_contacts_raw_snapshot(state, &usernames)
103        })
104        .await
105    }
106
107    pub async fn lookup_contacts_receipt(
108        &self,
109        usernames: &[String],
110    ) -> Result<crate::MetadataReply<crate::ContactLookup>> {
111        let usernames = usernames.to_vec();
112        self.account_request(move |transport, state, _| {
113            transport.lookup_contacts_receipt_snapshot(state, &usernames)
114        })
115        .await
116    }
117
118    pub async fn lookup_room_receipt(
119        &self,
120        room_id: &str,
121        version: u32,
122    ) -> Result<crate::MetadataReply<crate::RoomRoster>> {
123        let room_id = room_id.to_owned();
124        self.account_request(move |transport, state, _| {
125            transport.lookup_room_receipt_snapshot(state, &room_id, version)
126        })
127        .await
128    }
129
130    pub async fn lookup_room_raw(&self, room_id: &str, version: u32) -> Result<Vec<u8>> {
131        let room_id = room_id.to_owned();
132        self.account_request(move |transport, state, _| {
133            transport.lookup_room_raw_snapshot(state, &room_id, version)
134        })
135        .await
136    }
137
138    pub async fn init_contacts_receipt(
139        &self,
140        contact_sequence: u32,
141        room_sequence: u32,
142    ) -> Result<crate::MetadataReply<crate::InitContactPage>> {
143        self.account_request(move |transport, state, _| {
144            transport.init_contacts_receipt_snapshot(state, contact_sequence, room_sequence)
145        })
146        .await
147    }
148
149    pub async fn group_detail_raw(&self, group_id: &str) -> Result<Vec<u8>> {
150        let group_id = group_id.to_owned();
151        self.account_request(move |transport, state, _| {
152            transport.group_detail_raw_snapshot(state, &group_id)
153        })
154        .await
155    }
156
157    pub async fn group_mutation_raw(&self, request: &crate::GroupRpc) -> Result<Vec<u8>> {
158        let request = request.clone();
159        self.account_request(move |transport, state, _| {
160            transport.group_mutation_raw_snapshot(state, &request)
161        })
162        .await
163    }
164
165    pub async fn recall_message(
166        &self,
167        request: &crate::MessageRecall,
168    ) -> Result<crate::MessageRecallReply> {
169        let request = request.clone();
170        self.account_request(move |transport, state, _| {
171            transport.recall_message_snapshot(state, &request)
172        })
173        .await
174    }
175
176    pub async fn notify_read_session(
177        &self,
178        notification: &crate::SessionReadNotification,
179    ) -> Result<crate::SessionReadReply> {
180        let notification = notification.clone();
181        self.account_request(move |transport, state, _| {
182            transport.notify_read_session_snapshot(state, &notification)
183        })
184        .await
185    }
186
187    pub async fn contact_sync(
188        &self,
189        cursor: &[u8],
190        message_cursor: &[u8],
191        continuation: bool,
192    ) -> Result<crate::contact_sync::ContactSyncBatch> {
193        let cursor = cursor.to_vec();
194        let message_cursor = message_cursor.to_vec();
195        self.account_request(move |transport, state, _| {
196            transport.contact_sync_snapshot(state, &cursor, &message_cursor, continuation)
197        })
198        .await
199    }
200
201    pub async fn send_share(
202        &self,
203        destination: &str,
204        client_id: &str,
205        created_at: u32,
206        content: &str,
207    ) -> Result<crate::media_send::MediaSendResult> {
208        let (destination, client_id, content) = (
209            destination.to_owned(),
210            client_id.to_owned(),
211            content.to_owned(),
212        );
213        self.account_request(move |transport, state, _| {
214            transport.send_share_snapshot(state, &destination, &client_id, created_at, &content)
215        })
216        .await
217    }
218
219    pub async fn send_quote(
220        &self,
221        destination: &str,
222        client_id: &str,
223        created_at: u32,
224        content: &str,
225        source: Option<&str>,
226    ) -> Result<crate::media_send::MediaSendResult> {
227        let (destination, client_id, content) = (
228            destination.to_owned(),
229            client_id.to_owned(),
230            content.to_owned(),
231        );
232        let source = source.map(str::to_owned);
233        self.account_request(move |transport, state, _| {
234            transport.send_quote_with_source_snapshot(
235                state,
236                &destination,
237                &client_id,
238                created_at,
239                &content,
240                source.as_deref(),
241            )
242        })
243        .await
244    }
245
246    pub async fn reserve_file_upload(
247        &self,
248        destination: &str,
249        progress_client_id: &str,
250        file_name: &str,
251        plaintext_bytes: usize,
252        md5: &str,
253    ) -> Result<crate::file_upload::FileUploadReservation> {
254        let (destination, progress_client_id, file_name, md5) = (
255            destination.to_owned(),
256            progress_client_id.to_owned(),
257            file_name.to_owned(),
258            md5.to_owned(),
259        );
260        self.account_request(move |transport, state, _| {
261            transport.reserve_file_upload_snapshot(
262                state,
263                &destination,
264                &progress_client_id,
265                &file_name,
266                plaintext_bytes,
267                &md5,
268            )
269        })
270        .await
271    }
272
273    pub async fn send_file(
274        &self,
275        destination: &str,
276        client_id: &str,
277        created_at: u32,
278        upload: &crate::media::UploadedMedia,
279        reservation: Option<&crate::file_upload::FileUploadReservation>,
280    ) -> Result<crate::media_send::MediaSendResult> {
281        let (destination, client_id) = (destination.to_owned(), client_id.to_owned());
282        let upload = upload.clone();
283        let reservation = reservation.cloned();
284        self.account_request(move |transport, state, _| {
285            transport.send_file_with_reservation_snapshot(
286                state,
287                &destination,
288                &client_id,
289                created_at,
290                &upload,
291                reservation.as_ref(),
292            )
293        })
294        .await
295    }
296
297    pub async fn send_image(
298        &self,
299        destination: &str,
300        client_id: &str,
301        upload: &crate::media::UploadedImage,
302    ) -> Result<crate::media_send::MediaSendResult> {
303        let (destination, client_id) = (destination.to_owned(), client_id.to_owned());
304        let upload = upload.clone();
305        self.account_request(move |transport, state, _| {
306            transport.send_image_snapshot(state, &destination, &client_id, &upload)
307        })
308        .await
309    }
310
311    pub async fn send_video(
312        &self,
313        destination: &str,
314        client_id: &str,
315        upload: &crate::media::UploadedVideo,
316        play_seconds: u32,
317    ) -> Result<crate::media_send::MediaSendResult> {
318        let (destination, client_id) = (destination.to_owned(), client_id.to_owned());
319        let upload = upload.clone();
320        self.account_request(move |transport, state, _| {
321            transport.send_video_snapshot(state, &destination, &client_id, &upload, play_seconds)
322        })
323        .await
324    }
325
326    pub async fn send_voice(
327        &self,
328        destination: &str,
329        client_id: &str,
330        created_at: u32,
331        duration_ms: u32,
332        encoded: &[u8],
333    ) -> Result<crate::media_send::MediaSendResult> {
334        let (destination, client_id) = (destination.to_owned(), client_id.to_owned());
335        let encoded = encoded.to_vec();
336        self.account_request(move |transport, state, _| {
337            transport.send_voice_snapshot(
338                state,
339                &destination,
340                &client_id,
341                created_at,
342                duration_ms,
343                &encoded,
344            )
345        })
346        .await
347    }
348
349    /// Explicitly renew this account once. Concurrent requests from the prior
350    /// credential generation cannot submit or adopt responses after acceptance.
351    /// There is no QR fallback and no retry after an uncertain auth outcome.
352    pub async fn renew_session(&self, computer_name: &str) -> Result<()> {
353        let (exchange, state) = self.owned_account()?.begin()?;
354        let exchange = Arc::new(exchange);
355        let computer_name = computer_name.to_owned();
356        let options = self.options.clone();
357        let cancellation = Arc::new(AtomicBool::new(false));
358        let _cancel_on_drop = CancelOnDrop(cancellation.clone());
359        tokio::task::spawn_blocking(move || {
360            let mut transport = NativeClient::new(options)?;
361            let submission_exchange = exchange.clone();
362            transport.submission_guard = Some(Arc::new(move || {
363                ensure!(
364                    !cancellation.load(Ordering::Acquire),
365                    "Account authentication cancelled before submission"
366                );
367                submission_exchange.check()
368            }));
369            let returned = transport.renew_session_snapshot(&state, &computer_name)?;
370            exchange.accept_credentials(returned)
371        })
372        .await
373        .context("Account authentication worker failed")?
374    }
375
376    /// Fence admission, drain prior requests, then submit logout at most once.
377    /// The owner stays stopped after rejection, cancellation or uncertainty;
378    /// this operation does not revoke remembered-device trust or delete profiles.
379    pub async fn logout(&self) -> Result<crate::LogoutReply> {
380        self.prepare_logout()?.submit().await
381    }
382
383    /// Submit one text message without automatic renewal or retry. Inspect both
384    /// receipt correlation fields and acceptance before reporting success.
385    pub async fn send_text(
386        &self,
387        destination: &str,
388        content: &str,
389        options: TextSendOptions,
390    ) -> Result<crate::TextSendResult> {
391        self.send_text_guarded(destination, content, options, || Ok(()))
392            .await
393    }
394
395    pub async fn send_text_guarded<F>(
396        &self,
397        destination: &str,
398        content: &str,
399        options: TextSendOptions,
400        before_submit: F,
401    ) -> Result<crate::TextSendResult>
402    where
403        F: FnOnce() -> Result<()> + Send + 'static,
404    {
405        let destination = destination.to_owned();
406        let content = content.to_owned();
407        self.account_request(move |transport, state, _| {
408            let request = crate::wire::text_send_request_with_source(
409                &destination,
410                &content,
411                options.created_at,
412                options.client_message_id,
413                options.source.as_deref(),
414            )?;
415            let reply = transport.authenticated_rpc_guarded(
416                state,
417                522,
418                "/cgi-bin/micromsg-bin/newsendmsg",
419                &request,
420                before_submit,
421            )?;
422            crate::wire::decode_text_send(&reply, &destination, options.client_message_id)
423        })
424        .await
425    }
426
427    /// Execute one call request using this client's account. No automatic retry.
428    pub async fn call_rpc(
429        &self,
430        route: crate::calls::host_policy::CallHostRoute,
431        request: Vec<u8>,
432    ) -> Result<Vec<u8>> {
433        self.call_rpc_guarded(route, request, || Ok(())).await
434    }
435
436    /// Recheck account lifetime and caller authority immediately before transport
437    /// handoff. A returned error must not be interpreted as proof of no submission.
438    pub async fn call_rpc_guarded<F>(
439        &self,
440        route: crate::calls::host_policy::CallHostRoute,
441        request: Vec<u8>,
442        before_submit: F,
443    ) -> Result<Vec<u8>>
444    where
445        F: FnOnce() -> Result<()> + Send + 'static,
446    {
447        self.call_rpc_observed(route, request, before_submit, |_| Ok(()))
448            .await
449    }
450
451    /// Retain a verified call reply before adopting its cookie or returning it to
452    /// the calling runtime. The callback must protect these account-specific
453    /// bytes, must not log them, and must not reenter this client. Failure is an
454    /// uncertain submitted operation, not permission to submit another request.
455    pub async fn call_rpc_observed<F, O>(
456        &self,
457        route: crate::calls::host_policy::CallHostRoute,
458        request: Vec<u8>,
459        before_submit: F,
460        retain_reply: O,
461    ) -> Result<Vec<u8>>
462    where
463        F: FnOnce() -> Result<()> + Send + 'static,
464        O: Fn(&[u8]) -> Result<()> + Send + Sync + 'static,
465    {
466        self.account_request(move |transport, state, check| {
467            let mut transport = transport.clone();
468            transport.call_reply_observer = Some(Arc::new(retain_reply));
469            transport.call_rpc_snapshot_guarded(state, route, &request, || {
470                check()?;
471                before_submit()
472            })
473        })
474        .await
475    }
476
477    /// Poll call notifications with caller cancellation and account shutdown.
478    /// Interruption is not proof that the read-only request was never submitted.
479    pub async fn call_live_sync_guarded<F, C>(
480        &self,
481        request: Vec<u8>,
482        before_submit: F,
483        cancellation: C,
484    ) -> Result<Vec<u8>>
485    where
486        F: FnOnce() -> Result<()> + Send + 'static,
487        C: Future<Output = ()> + Send + 'static,
488    {
489        self.call_live_sync_with_wait_timeout(
490            request,
491            self.options.timeout,
492            before_submit,
493            cancellation,
494        )
495        .await
496    }
497
498    /// Keep the handshake deadline independent of the long read-only wait.
499    /// The caller owns any retry/reconciliation policy; this submits at most once.
500    pub async fn call_live_sync_with_wait_timeout<F, C>(
501        &self,
502        request: Vec<u8>,
503        wait_timeout: Duration,
504        before_submit: F,
505        cancellation: C,
506    ) -> Result<Vec<u8>>
507    where
508        F: FnOnce() -> Result<()> + Send + 'static,
509        C: Future<Output = ()> + Send + 'static,
510    {
511        self.call_live_sync_observed(request, wait_timeout, before_submit, cancellation, |_| {
512            Ok(())
513        })
514        .await
515    }
516
517    pub async fn call_live_sync_observed<F, C, O>(
518        &self,
519        request: Vec<u8>,
520        wait_timeout: Duration,
521        before_submit: F,
522        cancellation: C,
523        retain_reply: O,
524    ) -> Result<Vec<u8>>
525    where
526        F: FnOnce() -> Result<()> + Send + 'static,
527        C: Future<Output = ()> + Send + 'static,
528        O: Fn(&[u8]) -> Result<()> + Send + Sync + 'static,
529    {
530        ensure!(
531            !wait_timeout.is_zero() && wait_timeout <= Duration::from_secs(120),
532            "Invalid call poll wait timeout"
533        );
534        let runtime = tokio::runtime::Handle::current();
535        let account = self.owned_account()?.clone();
536        self.account_request(move |transport, state, check| {
537            let mut transport = transport.clone();
538            transport.call_reply_observer = Some(Arc::new(retain_reply));
539            transport.call_live_sync_snapshot_with_wait_timeout(
540                state,
541                &request,
542                wait_timeout,
543                || {
544                    check()?;
545                    before_submit()
546                },
547                |reply| runtime.block_on(wait_for_poll(reply, cancellation, account.stopped())),
548            )
549        })
550        .await
551    }
552}