Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

54.6 KB
Raw Blame
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
//
// Ported from whatsmeow client.go (MPL-2.0, Copyright (c) Tulir Asokan)
//
// Deliberate deviations:
// - Go's public mutable fields (`EnableAutoReconnect`, `SynchronousAck`,
//   `PrePairCallback`, …) are a [`ClientConfig`] passed to [`Client::new`].
// - The HTTP clients and proxy setters are replaced by [`Dialer`], which opens
//   the websocket (tests dial an in-memory fake server).
// - Event handlers are async ([`EventHandler`]) so a handler can persist an
//   event before the client acks it (`synchronous_ack`). [`Client::subscribe`]
//   gives a channel of events instead.
// - `context.Context` parameters are dropped. The per-connection context is a
//   `CancellationToken`; background tasks run on the client's `TaskTracker`.
// - Logs carry opaque IDs only: no node XML, JIDs or phone numbers.
// - `handler_queue_loop` handles a `stream:error` it dequeued after the
//   connection ended instead of dropping it (Go drops it, losing the
//   post-pairing 515 reconnect when the socket closes in the same write).
// - Not ported: Messenger (`MessengerConfig`, `RefreshCAT`), proxies.

//! The WhatsApp web multidevice client.

use std::collections::HashMap;
use std::panic::AssertUnwindSafe;
use std::sync::atomic::{AtomicBool, AtomicI64, AtomicU32, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, MutexGuard, PoisonError};
use std::time::Duration;

use async_trait::async_trait;
use chrono::{DateTime, Utc};
use futures::FutureExt;
use futures::future::BoxFuture;
use tokio::sync::{RwLock, mpsc, oneshot, watch};
use tokio_util::sync::CancellationToken;
use tokio_util::task::TaskTracker;
use tracing::Instrument;

use crate::binary::{Attrs, Node, NodeContent, marshal, unmarshal, unpack};
use crate::errors::ClientError;
use crate::handshake::do_handshake;
use crate::pair_code::PairClientType;
use crate::signal::{CurveSignatures, SignalProtocol};
use crate::socket::{FrameEvent, FrameSocket, NoiseEvent, NoiseSocket, SocketError, URL};
use crate::store::{Device, StoreError};
use crate::telemetry::ConnectReason;
use crate::types::events::{Disconnected, Event};
use crate::types::{AddressingMode, DEFAULT_USER_SERVER, HIDDEN_USER_SERVER, Jid};
use crate::util::keys::new_key_pair;

/// Everything the client needs from a Signal implementation: the protocol
/// and XEdDSA signatures. Implemented for every type that has both.
pub trait Signal: SignalProtocol + CurveSignatures {}

impl<Implementation: SignalProtocol + CurveSignatures> Signal for Implementation {}

/// Opens the websocket to WhatsApp.
///
/// Object safe (`Arc<dyn Dialer>`), hence `async_trait`.
#[async_trait]
pub trait Dialer: Send + Sync {
    /// Connects and returns the frame socket with its events.
    async fn dial(&self) -> Result<(FrameSocket, mpsc::Receiver<FrameEvent>), SocketError>;
}

/// Dials WhatsApp's real websocket endpoint ([`URL`]).
pub struct WebSocketDialer {
    /// The URL to dial.
    pub url: String,
}

impl Default for WebSocketDialer {
    fn default() -> Self {
        WebSocketDialer {
            url: URL.to_owned(),
        }
    }
}

#[async_trait]
impl Dialer for WebSocketDialer {
    async fn dial(&self) -> Result<(FrameSocket, mpsc::Receiver<FrameEvent>), SocketError> {
        FrameSocket::connect(&self.url).await
    }
}

/// Handles events emitted by the client. Returning `false` marks the event
/// as failed: with `synchronous_ack`, the node isn't acked so the server
/// redelivers it.
///
/// Object safe (`Arc<dyn EventHandler>`), hence `async_trait`.
#[async_trait]
pub trait EventHandler: Send + Sync {
    /// Handles one event.
    async fn handle(&self, event: &Event) -> bool;
}

struct FnHandler<Function>(Function);

#[async_trait]
impl<Function: Fn(&Event) + Send + Sync> EventHandler for FnHandler<Function> {
    async fn handle(&self, event: &Event) -> bool {
        (self.0)(event);
        true
    }
}

/// `PrePairCallback`: called with the JID, platform and business name before
/// pairing completes; returning `false` cancels the pairing.
pub type PrePairCallback = Arc<dyn Fn(&Jid, &str, &str) -> bool + Send + Sync>;

/// `AutoReconnectHook`: called when an automatic reconnect fails; returning
/// `false` stops reconnecting.
pub type AutoReconnectHook = Arc<dyn Fn(&ClientError) -> bool + Send + Sync>;

/// `GetMessageForRetry`: the requester, the chat and the message ID.
pub type GetMessageForRetry =
    Arc<dyn Fn(&Jid, &Jid, &str) -> Option<crate::proto::wa_e2e::Message> + Send + Sync>;

/// `PreRetryCallback`: the receipt, message ID, retry count and message.
pub type PreRetryCallback = Arc<
    dyn Fn(&crate::types::events::Receipt, &str, i64, &crate::proto::wa_e2e::Message) -> bool
        + Send
        + Sync,
>;

/// The settings Go keeps as public fields on `Client`.
#[derive(Clone)]
pub struct ClientConfig {
    /// Opens the websocket.
    pub dialer: Arc<dyn Dialer>,
    /// Reconnect automatically after unexpected disconnects (default true).
    pub enable_auto_reconnect: bool,
    /// Retry in the background when the first connection attempt fails.
    pub initial_auto_reconnect: bool,
    /// See [`AutoReconnectHook`].
    pub auto_reconnect_hook: Option<AutoReconnectHook>,
    /// Only ack nodes after every event handler returned successfully.
    pub synchronous_ack: bool,
    /// Don't reconnect after the server's post-login 515 stream error; emit
    /// [`Event::ManualLoginReconnect`] instead.
    pub disable_login_auto_reconnect: bool,
    /// Emit app state events even when re-syncing the whole state.
    pub emit_app_state_events_on_full_sync: bool,
    /// Ask the phone for messages that fail to decrypt.
    pub automatic_message_rerequest_from_phone: bool,
    /// Don't download history syncs automatically.
    pub manual_history_sync_download: bool,
    /// Don't send the history sync receipt when downloading manually.
    pub disable_manual_history_sync_receipt: bool,
    /// Delete the stored identity and sessions on untrusted identity errors
    /// (default true).
    pub auto_trust_identity: bool,
    /// Keep sent messages in the store so retry receipts work across restarts.
    pub use_retry_message_store: bool,
    /// See [`PrePairCallback`].
    pub pre_pair_callback: Option<PrePairCallback>,
    /// Overrides the client type shown on the phone while pairing.
    pub qr_client_type: Option<PairClientType>,
    /// The HTTP client for media downloads and uploads (Go's `mediaHTTP`).
    pub media_http: reqwest::Client,
    /// Fail [`Client::subscribe_presence`] when there's no privacy token for
    /// the user instead of subscribing without one.
    pub error_on_subscribe_presence_without_token: bool,
    /// Finds a sent message for a retry receipt when it isn't in the recent
    /// message cache, given the requester, chat and message ID
    /// (`GetMessageForRetry`).
    pub get_message_for_retry: Option<GetMessageForRetry>,
    /// Called before accepting a retry receipt; returning `false` ignores it
    /// (`PreRetryCallback`).
    pub pre_retry_callback: Option<PreRetryCallback>,
    /// Sends media uploads, downloads and deletes to this base URL
    /// (`scheme://host[:port]`) instead of the hosts the media connection
    /// names, e.g. a local fake media server in tests. `None` (default) uses
    /// WhatsApp's hosts. Not in whatsmeow.
    pub media_base_url: Option<String>,
    /// Buffer decrypted events in the store so a redelivered ciphertext
    /// isn't decrypted twice (Go's `EnableDecryptedEventBuffer`).
    pub enable_decrypted_event_buffer: bool,
}

impl Default for ClientConfig {
    fn default() -> Self {
        ClientConfig {
            dialer: Arc::new(WebSocketDialer::default()),
            enable_auto_reconnect: true,
            initial_auto_reconnect: false,
            auto_reconnect_hook: None,
            synchronous_ack: false,
            disable_login_auto_reconnect: false,
            emit_app_state_events_on_full_sync: false,
            automatic_message_rerequest_from_phone: false,
            manual_history_sync_download: false,
            disable_manual_history_sync_receipt: false,
            auto_trust_identity: true,
            use_retry_message_store: false,
            pre_pair_callback: None,
            qr_client_type: None,
            media_http: reqwest::Client::new(),
            error_on_subscribe_presence_without_token: false,
            enable_decrypted_event_buffer: false,
            media_base_url: None,
            get_message_for_retry: None,
            pre_retry_callback: None,
        }
    }
}

/// exsync.Event: a flag tasks can wait on.
pub(crate) struct EventFlag(watch::Sender<bool>);

impl EventFlag {
    pub(crate) fn new() -> Self {
        EventFlag(watch::Sender::new(false))
    }

    pub(crate) fn set(&self) {
        self.0.send_replace(true);
    }

    pub(crate) fn clear(&self) {
        self.0.send_replace(false);
    }

    pub(crate) fn is_set(&self) -> bool {
        *self.0.borrow()
    }

    /// Waits until the flag is set.
    pub(crate) async fn wait(&self) {
        let mut receiver = self.0.subscribe();
        // The sender lives as long as `self`, so this only returns once set.
        let _ = receiver.wait_for(|set| *set).await;
    }
}

/// The socket and its connection, guarded by Go's `socketLock`.
#[derive(Default)]
pub(crate) struct SocketState {
    pub(crate) socket: Option<Arc<NoiseSocket>>,
    /// Cancelled when the connection ends (Go's `fs.Context()`).
    connection: Option<CancellationToken>,
    /// Resolves when the handler queue loop exits.
    handler_queue_wait: Option<oneshot::Receiver<()>>,
}

/// Size of the queue that all incoming XML nodes go through.
const HANDLER_QUEUE_SIZE: usize = 2048;

/// The tags of the nodes the client handles (Go's `nodeHandlers` keys).
const NODE_HANDLER_TAGS: &[&str] = &[
    "message",
    "status",
    "appdata",
    "receipt",
    "call",
    "chatstate",
    "presence",
    "notification",
    "success",
    "failure",
    "stream:error",
    "iq",
    "ib",
];

/// A user's devices and the hash of the list.
#[derive(Clone, Debug, Default)]
pub(crate) struct DeviceCache {
    pub(crate) devices: Vec<Jid>,
    #[cfg_attr(
        not(test),
        expect(dead_code, reason = "Go keeps it but never reads it either")
    )]
    pub(crate) dhash: String,
}

/// What the send path needs to know about a group (Go's `groupMetaCache`).
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub(crate) struct GroupMetaCache {
    pub(crate) addressing_mode: AddressingMode,
    pub(crate) community_announcement_group: bool,
    pub(crate) read_only: bool,
    pub(crate) members: Vec<Jid>,
    pub(crate) admins: Vec<Jid>,
}

impl GroupMetaCache {
    /// Whether the sender may send the message: anyone may send in a group
    /// that isn't read only, and only admins may send anything but
    /// reactions, poll votes and the like in one that is (`CanSend`; a nil
    /// cache in Go is `None` at the call site).
    pub(crate) fn can_send(&self, sender: &Jid, message: &crate::proto::wa_e2e::Message) -> bool {
        !self.read_only
            || message.poll_update_message.is_some()
            || message.reaction_message.is_some()
            || message.enc_reaction_message.is_some()
            || message.enc_event_response_message.is_some()
            || message.question_response_message.is_some()
            || message.comment_message.is_some()
            || message.enc_comment_message.is_some()
            || self.admins.contains(&sender.to_non_ad())
    }
}

/// Everything necessary to connect to and interact with the WhatsApp web API.
pub struct Client {
    /// The device: keys, identity and stores (Go's `Store`).
    pub store: RwLock<Device>,
    pub(crate) signal: Arc<dyn Signal>,
    pub(crate) config: ClientConfig,

    pub(crate) socket: RwLock<SocketState>,
    socket_wait: watch::Sender<u64>,

    is_logged_in: AtomicBool,
    pub(crate) paired: AtomicBool,
    pub(crate) expected_disconnect: EventFlag,
    force_auto_reconnect: AtomicBool,
    last_successful_connect: Mutex<Option<DateTime<Utc>>>,
    auto_reconnect_errors: AtomicU32,

    pub(crate) send_active_receipts: AtomicU32,

    /// Prekey upload lock with the time of the last upload.
    pub(crate) upload_pre_keys_lock: tokio::sync::Mutex<Option<tokio::time::Instant>>,
    /// Set once prekeys were uploaded (Go's `PreKeysUploaded`).
    pub(crate) pre_keys_uploaded: EventFlag,

    response_waiters: Mutex<HashMap<String, oneshot::Sender<Node>>>,

    event_handlers: std::sync::RwLock<Vec<(u32, Arc<dyn EventHandler>)>>,
    next_handler_id: AtomicU32,

    /// Go's `groupCache`; held across the group info query when filling it.
    pub(crate) group_cache: tokio::sync::Mutex<HashMap<Jid, GroupMetaCache>>,
    pub(crate) user_devices_cache: tokio::sync::Mutex<HashMap<Jid, DeviceCache>>,

    pub(crate) tc_token_sender_ts: Mutex<crate::tctoken::TcTokenSenderTimestamps>,
    /// The prune lock with the time of the last prune.
    pub(crate) tc_token_db_prune: tokio::sync::Mutex<Option<tokio::time::Instant>>,

    pub(crate) media_conn_cache: tokio::sync::Mutex<Option<crate::mediaconn::MediaConn>>,
    pub(crate) phone_linking_cache: Mutex<Option<crate::pair_code::PhoneLinkingCache>>,
    pub(crate) passkey_state: Mutex<crate::pair_passkey::PasskeyState>,
    pub(crate) privacy_settings_cache: Mutex<Option<crate::types::PrivacySettings>>,

    /// Built from the device's stores in [`Client::new`] (Go's
    /// `appStateProc`).
    pub(crate) app_state_proc: Mutex<Arc<crate::appstate::Processor>>,
    /// Serializes app state fetches (Go's `appStateSyncLock`).
    pub(crate) app_state_sync_lock: tokio::sync::Mutex<()>,
    /// When each missing app state key was last requested, by hex key ID.
    pub(crate) app_state_key_requests: Mutex<HashMap<String, tokio::time::Instant>>,
    pub(crate) last_decrypted_buffer_clear: Mutex<Option<tokio::time::Instant>>,
    pub(crate) history_sync_notifications:
        mpsc::UnboundedSender<crate::proto::wa_e2e::HistorySyncNotification>,
    pub(crate) history_sync_notifications_receiver:
        tokio::sync::Mutex<mpsc::UnboundedReceiver<crate::proto::wa_e2e::HistorySyncNotification>>,
    pub(crate) history_sync_handler_started: AtomicBool,
    /// Retry receipts sent per incoming message ID.
    pub(crate) message_retries: Mutex<HashMap<String, i64>>,
    /// Pending delayed requests to the phone per message ID.
    pub(crate) pending_phone_rerequests: Mutex<HashMap<String, CancellationToken>>,
    pub(crate) recent_messages: Mutex<crate::retry::RecentMessages>,
    pub(crate) retry_state: Mutex<crate::retry::RetryState>,
    /// Serializes sends (Go's `messageSendLock`).
    pub(crate) message_send_lock: tokio::sync::Mutex<()>,

    unique_id: String,
    id_counter: AtomicU64,

    pub(crate) server_time_offset: AtomicI64,

    pub(crate) tasks: TaskTracker,
    /// Cancelled when the client is dropped or shut down (Go's
    /// `BackgroundEventCtx`).
    pub(crate) background: CancellationToken,

    /// Macro addition: the span that was current when [`Client::connect`]
    /// was called. Connection spans, reconnects and received nodes nest
    /// under it.
    pub(crate) connection_parent: Mutex<tracing::Span>,
    /// Macro addition: the `whatsmeow.connect.login` span between the
    /// handshake and the server's `success` or `failure`.
    pub(crate) pending_login: Mutex<Option<tracing::Span>>,
}

/// Locks a std mutex, ignoring poisoning: every guarded value is replaced
/// in one step, so a panic can't leave it half-written.
pub(crate) fn lock<Value>(mutex: &Mutex<Value>) -> MutexGuard<'_, Value> {
    mutex.lock().unwrap_or_else(PoisonError::into_inner)
}

impl Client {
    /// Creates a client for the device (`NewClient`).
    pub fn new(device: Device, signal: Arc<dyn Signal>, config: ClientConfig) -> Arc<Client> {
        let unique_id_prefix: [u8; 2] = rand::random();
        let paired = device.id.is_some();
        let app_state_proc = Mutex::new(Arc::new(crate::appstate::Processor::new(&device)));
        let (history_sync_notifications, history_sync_notifications_receiver) =
            mpsc::unbounded_channel();
        Arc::new(Client {
            store: RwLock::new(device),
            signal,
            config,
            socket: RwLock::new(SocketState::default()),
            socket_wait: watch::Sender::new(0),
            is_logged_in: AtomicBool::new(false),
            paired: AtomicBool::new(paired),
            expected_disconnect: EventFlag::new(),
            force_auto_reconnect: AtomicBool::new(false),
            last_successful_connect: Mutex::new(None),
            auto_reconnect_errors: AtomicU32::new(0),
            send_active_receipts: AtomicU32::new(0),
            upload_pre_keys_lock: tokio::sync::Mutex::new(None),
            pre_keys_uploaded: EventFlag::new(),
            response_waiters: Mutex::new(HashMap::new()),
            event_handlers: std::sync::RwLock::new(Vec::new()),
            next_handler_id: AtomicU32::new(0),
            group_cache: tokio::sync::Mutex::new(HashMap::new()),
            user_devices_cache: tokio::sync::Mutex::new(HashMap::new()),
            tc_token_sender_ts: Mutex::new(Default::default()),
            tc_token_db_prune: tokio::sync::Mutex::new(None),
            media_conn_cache: tokio::sync::Mutex::new(None),
            phone_linking_cache: Mutex::new(None),
            passkey_state: Mutex::new(Default::default()),
            privacy_settings_cache: Mutex::new(None),
            app_state_proc,
            app_state_sync_lock: tokio::sync::Mutex::new(()),
            app_state_key_requests: Mutex::new(HashMap::new()),
            last_decrypted_buffer_clear: Mutex::new(None),
            history_sync_notifications,
            history_sync_notifications_receiver: tokio::sync::Mutex::new(
                history_sync_notifications_receiver,
            ),
            history_sync_handler_started: AtomicBool::new(false),
            message_retries: Mutex::new(HashMap::new()),
            pending_phone_rerequests: Mutex::new(HashMap::new()),
            recent_messages: Mutex::new(Default::default()),
            retry_state: Mutex::new(Default::default()),
            message_send_lock: tokio::sync::Mutex::new(()),
            unique_id: format!("{}.{}-", unique_id_prefix[0], unique_id_prefix[1]),
            id_counter: AtomicU64::new(0),
            server_time_offset: AtomicI64::new(0),
            tasks: TaskTracker::new(),
            background: CancellationToken::new(),
            connection_parent: Mutex::new(tracing::Span::none()),
            pending_login: Mutex::new(None),
        })
    }

    /// The XEdDSA implementation.
    pub(crate) fn signatures(&self) -> &dyn CurveSignatures {
        self.signal.as_ref()
    }

    /// Spawns a background task on the client's tracker.
    pub(crate) fn spawn<Task>(&self, task: Task)
    where
        Task: Future<Output = ()> + Send + 'static,
    {
        // Macro addition: background work stays in the caller's trace.
        self.tasks.spawn(task.in_current_span());
    }

    /// Macro addition: the span connection work nests under.
    pub(crate) fn connection_parent(&self) -> tracing::Span {
        lock(&self.connection_parent).clone()
    }

    /// Macro addition: a `whatsmeow.connect` span under the connection's
    /// parent span.
    fn connect_span(&self, reason: ConnectReason, attempt: u32) -> tracing::Span {
        tracing::info_span!(
            parent: &self.connection_parent(),
            "whatsmeow.connect",
            reason = reason.as_str(),
            attempt,
            outcome = tracing::field::Empty,
            otel.status_code = tracing::field::Empty,
        )
    }

    /// Macro addition: ends the pending login span with an outcome.
    pub(crate) fn finish_login_span(
        &self,
        outcome: &'static str,
        failed: bool,
    ) -> Option<tracing::Span> {
        let span = lock(&self.pending_login).take()?;
        span.record("outcome", outcome);
        if failed {
            crate::telemetry::mark_error(&span);
        }
        Some(span)
    }

    /// Spawns `dispatch_event` in the background (Go's `go cli.dispatchEvent`).
    pub(crate) fn spawn_dispatch(self: &Arc<Self>, event: Event) {
        let client = Arc::clone(self);
        self.spawn(async move {
            client.dispatch_event(event).await;
        });
    }

    fn notify_socket_waiters(&self) {
        self.socket_wait.send_modify(|generation| *generation += 1);
    }

    /// The device's JID, or the empty JID before pairing.
    pub async fn get_own_id(&self) -> Jid {
        self.store.read().await.get_jid()
    }

    /// The device's LID, or the empty JID when unknown.
    pub async fn get_own_lid(&self) -> Jid {
        self.store.read().await.get_lid()
    }

    /// Waits until the client is connected and logged in, the timeout passes,
    /// or a disconnect is expected.
    pub async fn wait_for_connection(&self, timeout: Duration) -> bool {
        let deadline = tokio::time::Instant::now() + timeout;
        loop {
            let mut waiter = self.socket_wait.subscribe();
            {
                let state = self.socket.read().await;
                if state
                    .socket
                    .as_ref()
                    .is_some_and(|socket| socket.is_connected())
                    && self.is_logged_in()
                {
                    return true;
                }
            }
            tokio::select! {
                _ = waiter.changed() => {}
                () = tokio::time::sleep_until(deadline) => return false,
                () = self.expected_disconnect.wait() => return false,
            }
        }
    }

    /// Connects to the WhatsApp web websocket. After connecting, the client
    /// either logs in with the stored device or emits [`Event::Qr`] to pair a
    /// new one.
    pub async fn connect(self: &Arc<Self>) -> Result<(), ClientError> {
        *lock(&self.connection_parent) = tracing::Span::current();
        self.connect_with_reason(ConnectReason::Initial).await
    }

    /// Macro addition: [`Client::connect`] in a `whatsmeow.connect` span
    /// recording why it connects.
    pub(crate) async fn connect_with_reason(
        self: &Arc<Self>,
        reason: ConnectReason,
    ) -> Result<(), ClientError> {
        let span = self.connect_span(reason, 0);
        let result = self.connect_untraced().instrument(span.clone()).await;
        if let Err(error) = &result {
            tracing::warn!(parent: &span, error = %error, "connect failed");
        }
        crate::telemetry::record_result(&span, &result);
        result
    }

    async fn connect_untraced(self: &Arc<Self>) -> Result<(), ClientError> {
        let mut state = self.socket.write().await;
        let result = self.unlocked_connect(&mut state).await;
        drop(state);
        if let Err(error) = &result
            && is_retryable_connect_error(error)
            && self.config.initial_auto_reconnect
            && self.config.enable_auto_reconnect
        {
            tracing::error!(error = %error, "initial connection failed but reconnecting in background");
            self.spawn_dispatch(Event::Disconnected(Disconnected));
            let client = Arc::clone(self);
            self.spawn(async move { client.auto_reconnect(ConnectReason::ConnectFailed).await });
            return Ok(());
        }
        result
    }

    async fn connect_inner(self: &Arc<Self>) -> Result<(), ClientError> {
        let mut state = self.socket.write().await;
        self.unlocked_connect(&mut state).await
    }

    /// Boxed with an explicit `Send` bound to break the inference cycle
    /// through handlers that reconnect (see [`Client::auto_reconnect`]).
    fn unlocked_connect<'call>(
        self: &'call Arc<Self>,
        state: &'call mut SocketState,
    ) -> BoxFuture<'call, Result<(), ClientError>> {
        Box::pin(self.unlocked_connect_inner(state))
    }

    async fn unlocked_connect_inner(
        self: &Arc<Self>,
        state: &mut SocketState,
    ) -> Result<(), ClientError> {
        if self.store.read().await.deleted {
            return Err(StoreError::DeviceDeleted.into());
        }
        if let Some(socket) = &state.socket {
            if !socket.is_connected() {
                self.unlocked_disconnect(state).await;
            } else {
                return Err(ClientError::AlreadyConnected);
            }
        }

        self.reset_expected_disconnect();
        let dial_span = tracing::info_span!(
            "whatsmeow.connect.dial",
            outcome = tracing::field::Empty,
            otel.status_code = tracing::field::Empty,
        );
        let dialed = self
            .config
            .dialer
            .dial()
            .instrument(dial_span.clone())
            .await;
        crate::telemetry::record_result(&dial_span, &dialed);
        let (frame_socket, frames) = dialed?;
        let (noise_key, client_payload) = {
            let store = self.store.read().await;
            let payload = store.get_client_payload().map_err(|error| {
                ClientError::Other(format!("got invalid client payload: {error}"))
            });
            (store.noise_key.clone(), payload)
        };
        let client_payload = match client_payload {
            Ok(payload) => payload,
            Err(error) => {
                frame_socket.close(None).await;
                return Err(error);
            }
        };
        let handshake_span = tracing::info_span!(
            "whatsmeow.connect.handshake",
            outcome = tracing::field::Empty,
            otel.status_code = tracing::field::Empty,
        );
        let handshake = do_handshake(
            frame_socket.clone(),
            frames,
            &new_key_pair(),
            &noise_key,
            &client_payload,
            self.signatures(),
        )
        .instrument(handshake_span.clone())
        .await;
        crate::telemetry::record_result(&handshake_span, &handshake);
        let (noise_socket, noise_events) = match handshake {
            Ok(result) => result,
            Err(error) => {
                frame_socket.close(None).await;
                return Err(error.into());
            }
        };
        // Ended by the server's `success` or `failure` node, or a disconnect.
        *lock(&self.pending_login) = Some(tracing::info_span!(
            "whatsmeow.connect.login",
            outcome = tracing::field::Empty,
            failure_reason = tracing::field::Empty,
            otel.status_code = tracing::field::Empty,
        ));
        let noise_socket = Arc::new(noise_socket);
        let connection = CancellationToken::new();
        let (queue_sender, queue_receiver) = mpsc::channel(HANDLER_QUEUE_SIZE);
        let (close_wait_sender, close_wait_receiver) = oneshot::channel();
        state.socket = Some(Arc::clone(&noise_socket));
        state.connection = Some(connection.clone());
        state.handler_queue_wait = Some(close_wait_receiver);

        // Macro addition: the connection's loops run under the caller's span,
        // not the connect span, so received nodes nest under the caller.
        let parent = self.connection_parent();
        let client = Arc::clone(self);
        let reader_connection = connection.clone();
        self.spawn(
            async move {
                client
                    .read_loop(noise_socket, noise_events, queue_sender, reader_connection)
                    .await;
            }
            .instrument(parent.clone()),
        );
        let client = Arc::clone(self);
        let keepalive_connection = connection.clone();
        self.spawn(
            async move { client.keep_alive_loop(keepalive_connection).await }
                .instrument(parent.clone()),
        );
        let client = Arc::clone(self);
        self.spawn(
            async move {
                client
                    .handler_queue_loop(connection, queue_receiver, close_wait_sender)
                    .await;
            }
            .instrument(parent),
        );
        Ok(())
    }

    /// Feeds decrypted frames into the node queue and reports the
    /// disconnect (Go wires these as noise socket callbacks).
    async fn read_loop(
        self: Arc<Self>,
        noise_socket: Arc<NoiseSocket>,
        mut events: mpsc::Receiver<NoiseEvent>,
        queue: mpsc::Sender<Node>,
        connection: CancellationToken,
    ) {
        while let Some(event) = events.recv().await {
            match event {
                NoiseEvent::Frame(data) => self.handle_frame(&data, &queue),
                NoiseEvent::Disconnected { remote } => {
                    connection.cancel();
                    self.on_disconnect(&noise_socket, remote).await;
                    return;
                }
            }
        }
        connection.cancel();
    }

    /// Whether the client is connected and authenticated.
    pub fn is_logged_in(&self) -> bool {
        self.is_logged_in.load(Ordering::SeqCst)
    }

    pub(crate) fn set_logged_in(&self, logged_in: bool) {
        self.is_logged_in.store(logged_in, Ordering::SeqCst);
    }

    async fn on_disconnect(self: &Arc<Self>, noise_socket: &Arc<NoiseSocket>, remote: bool) {
        noise_socket.stop(false, false).await;
        let mut state = self.socket.write().await;
        if state
            .socket
            .as_ref()
            .is_some_and(|current| Arc::ptr_eq(current, noise_socket))
        {
            state.socket = None;
            self.clear_response_waiters(&xml_stream_end_node());
            self.finish_login_span("disconnected", true);
            if !self.is_expected_disconnect()
                && (self.force_auto_reconnect.swap(false, Ordering::SeqCst) || remote)
            {
                tracing::debug!("emitting Disconnected event");
                self.spawn_dispatch(Event::Disconnected(Disconnected));
                let reason = if remote {
                    ConnectReason::NetworkDrop
                } else {
                    ConnectReason::ForcedReset
                };
                let client = Arc::clone(self);
                self.spawn(async move { client.auto_reconnect(reason).await });
            } else if remote {
                tracing::debug!("on_disconnect called, but it was expected, so not emitting event");
            } else {
                tracing::debug!("on_disconnect called after manual disconnection");
            }
        } else {
            tracing::debug!("ignoring on_disconnect on different socket");
        }
    }

    pub(crate) fn expect_disconnect(&self) {
        self.force_auto_reconnect.store(false, Ordering::SeqCst);
        self.expected_disconnect.set();
    }

    pub(crate) fn reset_expected_disconnect(&self) {
        self.force_auto_reconnect.store(false, Ordering::SeqCst);
        self.expected_disconnect.clear();
    }

    pub(crate) fn is_expected_disconnect(&self) -> bool {
        self.expected_disconnect.is_set()
    }

    /// Boxed with an explicit `Send` bound: reconnecting calls back into
    /// `connect`, whose tasks can start another reconnect, and the compiler
    /// can't infer `Send` through that cycle.
    /// `reason` (a Macro addition) labels the reconnect's spans.
    pub(crate) fn auto_reconnect(self: Arc<Self>, reason: ConnectReason) -> BoxFuture<'static, ()> {
        Box::pin(self.auto_reconnect_inner(reason))
    }

    async fn auto_reconnect_inner(self: Arc<Self>, reason: ConnectReason) {
        if !self.config.enable_auto_reconnect || self.store.read().await.id.is_none() {
            return;
        }
        tracing::info!(parent: &self.connection_parent(), reason = reason.as_str(), "connection lost, reconnecting");
        loop {
            let errors = self.auto_reconnect_errors.fetch_add(1, Ordering::SeqCst);
            let delay = Duration::from_secs(u64::from(errors) * 2);
            tracing::debug!(delay = ?delay, "automatically reconnecting");
            tokio::select! {
                () = self.expected_disconnect.wait() => {
                    tracing::debug!("cancelling automatic reconnect due to expected disconnect");
                    return;
                }
                () = self.background.cancelled() => {
                    tracing::debug!("cancelling automatic reconnect due to client shutdown");
                    return;
                }
                () = tokio::time::sleep(delay) => {}
            }
            let span = self.connect_span(reason, errors + 1);
            let result = self.connect_inner().instrument(span.clone()).await;
            if !matches!(result, Err(ClientError::AlreadyConnected)) {
                crate::telemetry::record_result(&span, &result);
            }
            match result {
                Err(ClientError::AlreadyConnected) => {
                    tracing::debug!(
                        "connect said we're already connected after autoreconnect sleep"
                    );
                    return;
                }
                Err(error) => {
                    if self.expected_disconnect.is_set() {
                        tracing::debug!(
                            "autoreconnect failed, but disconnect was expected, not reconnecting"
                        );
                        return;
                    }
                    tracing::error!(error = %error, "error reconnecting after autoreconnect sleep");
                    if let Some(hook) = &self.config.auto_reconnect_hook
                        && !hook(&error)
                    {
                        tracing::debug!("auto reconnect hook returned false, not reconnecting");
                        return;
                    }
                }
                Ok(()) => return,
            }
        }
    }

    /// Whether the websocket is connected (not necessarily authenticated).
    pub async fn is_connected(&self) -> bool {
        self.socket
            .read()
            .await
            .socket
            .as_ref()
            .is_some_and(|socket| socket.is_connected())
    }

    /// Disconnects from the websocket. Emits no event: [`Event::Disconnected`]
    /// is only for disconnects caused by the server or the network.
    pub async fn disconnect(&self) {
        let mut state = self.socket.write().await;
        self.expect_disconnect();
        self.unlocked_disconnect(&mut state).await;
        drop(state);
        self.clear_delayed_message_requests();
    }

    /// Disconnects and forces an automatic reconnect. Does nothing when the
    /// socket is already disconnected or auto-reconnect is off.
    pub async fn reset_connection(&self) {
        let state = self.socket.write().await;
        self.force_auto_reconnect.store(true, Ordering::SeqCst);
        if let Some(socket) = &state.socket {
            socket.stop(true, true).await;
            self.clear_response_waiters(&xml_stream_end_node());
        }
    }

    async fn unlocked_disconnect(&self, state: &mut SocketState) {
        if let Some(socket) = state.socket.take() {
            socket.stop(true, false).await;
            self.clear_response_waiters(&xml_stream_end_node());
        }
        if let Some(connection) = state.connection.take() {
            connection.cancel();
        }
        if let Some(wait) = state.handler_queue_wait.take()
            && tokio::time::timeout(Duration::from_secs(5), wait)
                .await
                .is_err()
        {
            tracing::warn!("handler queue wait channel not closed after 5 seconds");
        }
    }

    /// Asks the server to unlink this device, then disconnects and deletes
    /// the local device. Emits no event: [`Event::LoggedOut`] is only for
    /// logouts triggered elsewhere.
    pub async fn logout(&self) -> Result<(), ClientError> {
        let own_id = self.get_own_id().await;
        if own_id.is_empty() {
            return Err(ClientError::NotLoggedIn);
        }
        self.send_iq(crate::request::InfoQuery {
            namespace: "md",
            r#type: crate::request::IqType::Set,
            to: crate::types::SERVER_JID.clone(),
            content: Some(NodeContent::Nodes(vec![Node {
                tag: "remove-companion-device".to_owned(),
                attrs: Attrs::from([
                    ("jid".to_owned(), own_id.into()),
                    ("reason".to_owned(), "user_initiated".into()),
                ]),
                content: None,
            }])),
            ..Default::default()
        })
        .await
        .map_err(|error| error.wrap("error sending logout request"))?;
        self.disconnect().await;
        self.delete_device()
            .await
            .map_err(|error| ClientError::from(error).wrap("error deleting data from store"))
    }

    /// Registers an event handler; returns its ID for
    /// [`Client::remove_event_handler`].
    pub fn add_event_handler(&self, handler: Arc<dyn EventHandler>) -> u32 {
        let id = self.next_handler_id.fetch_add(1, Ordering::SeqCst) + 1;
        self.event_handlers
            .write()
            .unwrap_or_else(PoisonError::into_inner)
            .push((id, handler));
        id
    }

    /// Registers a synchronous event handler function that always succeeds.
    pub fn add_event_fn<Function>(&self, handler: Function) -> u32
    where
        Function: Fn(&Event) + Send + Sync + 'static,
    {
        self.add_event_handler(Arc::new(FnHandler(handler)))
    }

    /// A channel that receives every event from now on.
    pub fn subscribe(&self) -> mpsc::UnboundedReceiver<Event> {
        let (sender, receiver) = mpsc::unbounded_channel();
        self.add_event_fn(move |event| {
            let _ = sender.send(event.clone());
        });
        receiver
    }

    /// Removes an event handler; returns whether it was found.
    pub fn remove_event_handler(&self, id: u32) -> bool {
        let mut handlers = self
            .event_handlers
            .write()
            .unwrap_or_else(PoisonError::into_inner);
        let before = handlers.len();
        handlers.retain(|(handler_id, _)| *handler_id != id);
        handlers.len() != before
    }

    /// Removes every event handler.
    pub fn remove_event_handlers(&self) {
        self.event_handlers
            .write()
            .unwrap_or_else(PoisonError::into_inner)
            .clear();
    }

    fn handle_frame(self: &Arc<Self>, data: &[u8], queue: &mpsc::Sender<Node>) {
        let decompressed = match unpack(data) {
            Ok(decompressed) => decompressed,
            Err(error) => {
                tracing::warn!(error = %error, "failed to decompress frame");
                return;
            }
        };
        let node = match unmarshal(&decompressed) {
            Ok(node) => node,
            Err(error) => {
                tracing::warn!(error = %error, "failed to decode node in frame");
                return;
            }
        };
        tracing::trace!(tag = %node.tag, "received node");
        if node.tag == "xmlstreamend" {
            if !self.is_expected_disconnect() {
                tracing::warn!("received stream end frame");
            }
        } else if self.receive_response(&node) {
            // handled
        } else if NODE_HANDLER_TAGS.contains(&node.tag.as_str()) {
            match queue.try_send(node) {
                Ok(()) => {}
                Err(mpsc::error::TrySendError::Full(node)) => {
                    tracing::warn!(
                        "handler queue is full, message ordering is no longer guaranteed"
                    );
                    let queue = queue.clone();
                    self.spawn(async move {
                        let _ = queue.send(node).await;
                    });
                }
                Err(mpsc::error::TrySendError::Closed(_)) => {}
            }
        } else if node.tag != "ack" {
            tracing::debug!(tag = %node.tag, "didn't handle WhatsApp node");
        }
    }

    async fn handler_queue_loop(
        self: Arc<Self>,
        connection: CancellationToken,
        mut queue: mpsc::Receiver<Node>,
        close_wait: oneshot::Sender<()>,
    ) {
        const SLOW_HANDLER_WARNING: Duration = Duration::from_secs(30);
        tracing::debug!("starting handler queue loop");
        'nodes: loop {
            let node = tokio::select! {
                node = queue.recv() => node,
                () = connection.cancelled() => {
                    tracing::debug!("closing handler queue loop");
                    break;
                }
            };
            let Some(node) = node else { break };
            if connection.is_cancelled() {
                // Deviation from Go: the node is already dequeued, so the
                // drain below wouldn't see it. A stream error (the 515
                // after pairing) must still be handled or the reconnect
                // is lost.
                if node.tag == "stream:error" {
                    tracing::debug!(
                        "handling stream:error node dequeued after the connection ended"
                    );
                    self.handle_stream_error(&node).await;
                }
                tracing::debug!("closing handler queue loop before node handling");
                break;
            }
            let tag = node.tag.clone();
            let client = Arc::clone(&self);
            let start = tokio::time::Instant::now();
            let mut handler = self.tasks.spawn(
                async move {
                    client.handle_node(node).await;
                    let duration = start.elapsed();
                    if duration > Duration::from_secs(5) {
                        tracing::warn!(duration = ?duration, "node handling took long");
                    }
                }
                .in_current_span(),
            );
            for _ in 0..10 {
                tokio::select! {
                    _ = &mut handler => continue 'nodes,
                    () = connection.cancelled() => {
                        tracing::warn!(tag = %tag, "closing handler queue loop in the middle of handling a node");
                        break 'nodes;
                    }
                    () = tokio::time::sleep(SLOW_HANDLER_WARNING) => {
                        tracing::warn!(tag = %tag, elapsed = ?start.elapsed(), "node handling is taking long");
                    }
                }
            }
            tracing::warn!(tag = %tag, "continuing handling of node in background as it's taking too long");
        }
        // Stream errors are handled even after disconnection so the
        // appropriate auto-reconnect is done.
        while let Ok(node) = queue.try_recv() {
            if node.tag == "stream:error" {
                tracing::debug!(
                    "handling stream:error node in handler queue loop after context cancellation"
                );
                self.handle_stream_error(&node).await;
            }
        }
        let _ = close_wait.send(());
    }

    /// Dispatches a node to its handler (Go's `nodeHandlers` map).
    /// Boxed with an explicit `Send` bound to break the inference cycle
    /// through handlers that reconnect (see [`Client::auto_reconnect`]).
    fn handle_node(self: Arc<Self>, node: Node) -> BoxFuture<'static, ()> {
        let span = tracing::info_span!("whatsmeow.handle_node", tag = %node.tag);
        Box::pin(self.handle_node_inner(node).instrument(span))
    }

    async fn handle_node_inner(self: Arc<Self>, node: Node) {
        match node.tag.as_str() {
            "success" => self.handle_connect_success(&node).await,
            "failure" => self.handle_connect_failure(&node).await,
            "stream:error" => self.handle_stream_error(&node).await,
            "iq" => self.handle_iq(&node).await,
            "ib" => self.handle_ib(&node).await,
            "notification" => self.handle_notification(&node).await,
            "chatstate" => self.handle_chat_state(&node).await,
            "presence" => self.handle_presence(&node).await,
            "message" | "appdata" => self.handle_encrypted_message(&node).await,
            "status" => self.handle_unencrypted_message(&node).await,
            "receipt" => self.handle_receipt(&node).await,
            other => self.handle_unported_node(other, &node).await,
        }
    }

    /// Calls aren't ported; call nodes are acked so the server doesn't
    /// redeliver them forever.
    async fn handle_unported_node(self: &Arc<Self>, tag: &str, node: &Node) {
        tracing::debug!(tag, "no handler for node yet, acking it");
        if tag == "call" {
            self.send_ack(node, 0).await;
        }
    }

    /// Marshals and sends a node; returns the marshaled bytes.
    pub(crate) async fn send_node_and_get_data(&self, node: &Node) -> Result<Vec<u8>, ClientError> {
        let socket = self.socket.read().await.socket.clone();
        let Some(socket) = socket else {
            return Err(ClientError::NotConnected);
        };
        let payload = marshal(node)?;
        tracing::trace!(tag = %node.tag, "sending node");
        socket.send_frame(&payload).await?;
        Ok(payload)
    }

    /// Marshals and sends a node.
    pub(crate) async fn send_node(&self, node: &Node) -> Result<(), ClientError> {
        self.send_node_and_get_data(node).await.map(|_| ())
    }

    /// Sends an event to every handler; returns whether a handler failed.
    pub(crate) async fn dispatch_event(&self, event: Event) -> bool {
        let handlers: Vec<Arc<dyn EventHandler>> = self
            .event_handlers
            .read()
            .unwrap_or_else(PoisonError::into_inner)
            .iter()
            .map(|(_, handler)| Arc::clone(handler))
            .collect();
        for handler in handlers {
            match AssertUnwindSafe(handler.handle(&event))
                .catch_unwind()
                .await
            {
                Ok(true) => {}
                Ok(false) => return true,
                Err(_) => {
                    tracing::error!("event handler panicked");
                    return false;
                }
            }
        }
        false
    }

    /// Parses a history sync `WebMessageInfo` into the [`Event::Message`]
    /// real-time messages produce (`ParseWebMessage`). An empty `chat_jid`
    /// is taken from the message key.
    pub async fn parse_web_message(
        &self,
        chat_jid: &Jid,
        web_message: crate::proto::wa_web::WebMessageInfo,
    ) -> Result<crate::types::events::Message, ClientError> {
        use crate::types::{
            GROUP_SERVER, MessageInfo, MessageSource, NEWSLETTER_SERVER, parse_jid,
        };
        let key = web_message.key.clone();
        let chat_jid = if chat_jid.is_empty() {
            parse_jid(key.remote_jid.as_deref().unwrap_or_default()).map_err(|error| {
                ClientError::Other(format!(
                    "no chat JID provided and failed to parse remote JID: {error}"
                ))
            })?
        } else {
            chat_jid.clone()
        };
        let mut info = MessageInfo {
            source: MessageSource {
                is_from_me: key.from_me.unwrap_or_default(),
                is_group: chat_jid.server == GROUP_SERVER,
                chat: chat_jid.clone(),
                ..MessageSource::default()
            },
            id: key.id.clone().unwrap_or_default(),
            push_name: web_message.push_name.clone().unwrap_or_default(),
            timestamp: DateTime::from_timestamp(
                i64::try_from(web_message.message_timestamp.unwrap_or_default())
                    .unwrap_or_default(),
                0,
            ),
            ..MessageInfo::default()
        };
        let parse_sender = |jid: &str| {
            parse_jid(jid).map_err(|error| {
                ClientError::Other(format!(
                    "failed to parse sender of message {}: {error}",
                    info.id
                ))
            })
        };
        let sender = if info.is_from_me {
            match web_message
                .original_self_author_user_jid_string
                .as_deref()
                .filter(|jid| !jid.is_empty())
            {
                Some(author) => parse_sender(author)?,
                None => {
                    let own = if info.chat.server == HIDDEN_USER_SERVER {
                        self.get_own_lid().await
                    } else {
                        self.get_own_id().await
                    }
                    .to_non_ad();
                    if own.is_empty() {
                        return Err(ClientError::NotLoggedIn);
                    }
                    own
                }
            }
        } else if chat_jid.server == DEFAULT_USER_SERVER
            || chat_jid.server == HIDDEN_USER_SERVER
            || chat_jid.server == NEWSLETTER_SERVER
        {
            chat_jid.clone()
        } else if let Some(participant) =
            web_message.participant.as_deref().filter(|p| !p.is_empty())
        {
            parse_sender(participant)?
        } else if let Some(participant) = key.participant.as_deref().filter(|p| !p.is_empty()) {
            parse_sender(participant)?
        } else {
            return Err(ClientError::Other(format!(
                "couldn't find sender of message {}",
                info.id
            )));
        };
        info.sender = sender;
        if let Some(parent_key) = web_message
            .comment_metadata
            .as_ref()
            .and_then(|metadata| metadata.comment_parent_key.as_ref())
        {
            info.msg_meta_info.thread_message_id = parent_key.id.clone().unwrap_or_default();
            info.msg_meta_info.thread_message_sender_jid =
                parse_jid(parent_key.participant.as_deref().unwrap_or_default())
                    .unwrap_or_default();
        }
        let mut event = crate::types::events::Message {
            info,
            raw_message: web_message.message.clone(),
            source_web_msg: Some(web_message),
            ..Default::default()
        };
        event.unwrap_raw();
        if let Some(protocol_message) = event
            .message
            .as_ref()
            .and_then(|message| message.protocol_message.as_ref())
            && protocol_message.r#type
                == Some(crate::proto::wa_e2e::protocol_message::Type::MessageEdit as i32)
        {
            let edited_id = protocol_message
                .key
                .as_ref()
                .and_then(|key| key.id.clone())
                .unwrap_or_default();
            let edited = protocol_message.edited_message.as_deref().cloned();
            event.info.id = edited_id;
            event.message = edited;
        }
        Ok(event)
    }

    /// Stores a LID ↔ phone number mapping, in either order.
    pub async fn store_lid_pn_mapping(&self, first: &Jid, second: &Jid) {
        let (lid, pn) =
            if first.server == HIDDEN_USER_SERVER && second.server == DEFAULT_USER_SERVER {
                (first, second)
            } else if first.server == DEFAULT_USER_SERVER && second.server == HIDDEN_USER_SERVER {
                (second, first)
            } else {
                return;
            };
        let lids = Arc::clone(&self.store.read().await.lids);
        if let Err(error) = lids.put_lid_mapping(lid, pn).await {
            tracing::error!(error = %error, "failed to store LID-PN mapping");
        }
    }

    fn get_unified_session_id(&self) -> String {
        const UNIFIED_OFFSET_MILLIS: i64 = 3 * 24 * 60 * 60 * 1000;
        const WEEK_MILLIS: i64 = 7 * 24 * 60 * 60 * 1000;
        let offset_millis = self.server_time_offset.load(Ordering::SeqCst) / 1_000_000;
        let unified = Utc::now().timestamp_millis() + offset_millis + UNIFIED_OFFSET_MILLIS;
        (unified % WEEK_MILLIS).to_string()
    }

    pub(crate) async fn send_unified_session(&self) {
        let node = Node {
            tag: "ib".to_owned(),
            attrs: Attrs::new(),
            content: Some(NodeContent::Nodes(vec![Node {
                tag: "unified_session".to_owned(),
                attrs: Attrs::from([("id".to_owned(), self.get_unified_session_id().into())]),
                content: None,
            }])),
        };
        if let Err(error) = self.send_node(&node).await {
            tracing::debug!(error = %error, "failed to send unified_session telemetry");
        }
    }

    /// Records a successful login.
    pub(crate) fn mark_connect_success(&self) {
        *lock(&self.last_successful_connect) = Some(Utc::now());
        self.auto_reconnect_errors.store(0, Ordering::SeqCst);
        self.set_logged_in(true);
    }

    /// When the client last logged in successfully.
    pub fn last_successful_connect(&self) -> Option<DateTime<Utc>> {
        *lock(&self.last_successful_connect)
    }

    /// Wakes [`Client::wait_for_connection`] (Go's `closeSocketWaitChan`).
    pub(crate) fn close_socket_wait_chan(&self) {
        self.notify_socket_waiters();
    }

    /// Generates a request ID (`generateRequestID`).
    pub(crate) fn generate_request_id(&self) -> String {
        format!(
            "{}{}",
            self.unique_id,
            self.id_counter.fetch_add(1, Ordering::SeqCst) + 1
        )
    }

    pub(crate) fn response_waiters(
        &self,
    ) -> MutexGuard<'_, HashMap<String, oneshot::Sender<Node>>> {
        lock(&self.response_waiters)
    }

    /// Waits until prekeys were uploaded after pairing (Go's
    /// `PreKeysUploaded.Wait`).
    pub async fn wait_pre_keys_uploaded(&self) {
        self.pre_keys_uploaded.wait().await;
    }

    /// The app state processor for the device's current stores.
    pub(crate) fn app_state_processor(&self) -> Arc<crate::appstate::Processor> {
        Arc::clone(&lock(&self.app_state_proc))
    }

    /// Deletes the device from its container and points the app state
    /// processor at the (now failing) stores, so it doesn't keep using the
    /// deleted device's stores. Go builds the processor once and keeps it.
    pub(crate) async fn delete_device(&self) -> Result<(), StoreError> {
        let mut store = self.store.write().await;
        let result = store.delete().await;
        *lock(&self.app_state_proc) = Arc::new(crate::appstate::Processor::new(&store));
        result
    }

    /// Stops background work: disconnects and waits for the client's tasks.
    pub async fn shutdown(&self) {
        self.disconnect().await;
        self.background.cancel();
        self.tasks.close();
        self.tasks.wait().await;
    }
}

impl Drop for Client {
    fn drop(&mut self) {
        self.background.cancel();
    }
}

/// The node waiters receive when the websocket disconnects.
pub(crate) fn xml_stream_end_node() -> Node {
    Node {
        tag: "xmlstreamend".to_owned(),
        ..Node::default()
    }
}

/// Network errors and some HTTP statuses are worth retrying.
fn is_retryable_connect_error(error: &ClientError) -> bool {
    match error {
        ClientError::Socket(SocketError::DialFailed { status_code, .. }) => match status_code {
            Some(code) => matches!(code, 408 | 500 | 501 | 502 | 503 | 504),
            None => true,
        },
        ClientError::Socket(_) => true,
        _ => false,
    }
}

#[cfg(test)]
pub(crate) mod test;