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.

23.9 KB
Raw Blame
//! In-process API for the WhatsApp session service. The replica that holds an
//! account's advisory lock calls these with the [`SessionScope`] it received from
//! [`SessionService::begin_lease`]; every write is fenced by that epoch, and a
//! `Fenced` error means the replica must stop the account immediately.

use super::{
    events::*,
    jid::{Jid, JidKind, is_group_jid, is_person_jid},
    models::*,
    ports::*,
};
use external_chat::domain::{models::*, ports::ExternalChatResult, rich::RichContent};
use std::sync::Arc;
use uuid::Uuid;

#[cfg(test)]
mod test;

/// Largest inbound text Macro stores, in UTF-8 bytes.
const INBOUND_TEXT_LIMIT_BYTES: usize = 64 * 1024;

/// Session-service use cases.
#[derive(Clone)]
pub struct SessionService {
    repository: Arc<dyn SessionRepository>,
}

impl SessionService {
    /// Wire the repository at the session service's composition root.
    pub fn new(repository: Arc<dyn SessionRepository>) -> Self {
        Self { repository }
    }

    /// Take over an account after acquiring its advisory lock. Bumps the lease
    /// epoch, which fences every older replica, and records the previous
    /// replica's in-flight sends as `unknown`.
    #[tracing::instrument(name = "whatsapp.session.begin_lease", skip_all, err, fields(account_id = %account, lease_epoch))]
    pub async fn begin_lease(&self, account: Uuid) -> ExternalChatResult<Lease> {
        let lease = self.repository.begin_lease(account).await?;
        tracing::Span::current().record("lease_epoch", lease.scope.lease_epoch);
        if lease.sends_marked_unknown > 0 {
            tracing::warn!(
                count = lease.sends_marked_unknown,
                "Sends left in flight by the previous replica are unknown"
            );
        }
        Ok(lease)
    }

    /// Hand the account over: undispatched claims return to `pending`. Call after
    /// in-flight sends have recorded their outcome and before unlocking.
    #[tracing::instrument(name = "whatsapp.session.release_lease", skip_all, err, fields(account_id = %scope.account_id, lease_epoch = scope.lease_epoch))]
    pub async fn release_lease(&self, scope: SessionScope) -> ExternalChatResult<()> {
        self.repository.release_lease(scope).await
    }

    /// Tell other replicas an unlocked account still needs a session. Call
    /// after unlocking, or the next replica's lock attempt loses the race.
    pub async fn announce_released(&self, account: Uuid) -> ExternalChatResult<()> {
        self.repository.announce_released(account).await
    }

    /// Lifecycle of an account, for discovery and stop decisions.
    pub async fn account_state(&self, account: Uuid) -> ExternalChatResult<Option<AccountState>> {
        self.repository.account_state(account).await
    }

    /// Accounts that need a replica (connected, or pairing with a live
    /// transaction) and whose advisory lock nobody holds, least recently updated first.
    pub async fn discoverable_accounts(&self, limit: i64) -> ExternalChatResult<Vec<Uuid>> {
        self.repository
            .discoverable_accounts(limit.clamp(1, 1000))
            .await
    }

    /// Fleet-wide counts for health checks and monitors.
    pub async fn fleet_health(&self) -> ExternalChatResult<FleetHealth> {
        self.repository.fleet_health().await
    }

    /// Resolve a `whatsapp_pairing_requested` payload. Terminal states mean the
    /// replica should stop pairing (and log out a cancelled device).
    pub async fn pairing_work(&self, pairing: Uuid) -> ExternalChatResult<Option<PairingWork>> {
        self.repository.pairing_work(pairing).await
    }

    /// The account's live pairing transaction, checked after taking a lease.
    pub async fn live_pairing(
        &self,
        scope: SessionScope,
    ) -> ExternalChatResult<Option<PairingWork>> {
        self.repository.live_pairing(scope).await
    }

    /// Report pairing progress. Returns the transaction afterwards so the replica
    /// sees cancellation. A `Success` whose identity does not match a reconnect,
    /// or belongs to another person, fails the transaction with an error; the
    /// replica must then log the device out.
    #[tracing::instrument(name = "whatsapp.session.update_pairing", skip_all, err, fields(account_id = %scope.account_id, pairing_id = %pairing, update))]
    pub async fn update_pairing(
        &self,
        scope: SessionScope,
        pairing: Uuid,
        update: PairingUpdate,
    ) -> ExternalChatResult<PairingWork> {
        let (name, valid) = match &update {
            PairingUpdate::Qr(code) => ("qr", !code.is_empty() && code.len() <= 4096),
            PairingUpdate::PairCode(code) => ("pair_code", !code.is_empty() && code.len() <= 64),
            PairingUpdate::Passkey { challenge } => (
                "passkey",
                challenge.is_object() && challenge.to_string().len() <= PASSKEY_LIMIT_BYTES,
            ),
            PairingUpdate::Success { identity_jid } => (
                "success",
                Jid::parse(identity_jid).is_some_and(|jid| jid.kind == JidKind::Phone),
            ),
            PairingUpdate::Expired => ("expired", true),
            PairingUpdate::Failed => ("failed", true),
        };
        tracing::Span::current().record("update", name);
        if !valid {
            return Err(ExternalChatError::Invalid("invalid pairing update").into());
        }
        self.repository
            .update_pairing(scope, pairing, &update)
            .await
    }

    /// Take the owner's passkey assertion, once, to forward to WhatsApp.
    pub async fn take_passkey_response(
        &self,
        scope: SessionScope,
        pairing: Uuid,
    ) -> ExternalChatResult<Option<serde_json::Value>> {
        self.repository.take_passkey_response(scope, pairing).await
    }

    /// Attachments this account observed and should download now. Each claim
    /// lasts five minutes; call again to retry the unfinished ones later.
    #[tracing::instrument(name = "whatsapp.session.claim_media", skip_all, err, fields(account_id = %scope.account_id, count))]
    pub async fn claim_media_imports(
        &self,
        scope: SessionScope,
        limit: i64,
    ) -> ExternalChatResult<Vec<MediaImport>> {
        let claimed = self
            .repository
            .claim_media_imports(scope, limit.clamp(1, 16))
            .await?;
        tracing::Span::current().record("count", claimed.len());
        Ok(claimed)
    }

    /// Hand over decrypted bytes for an import. DSS stores them as a static
    /// file.
    #[tracing::instrument(name = "whatsapp.session.complete_media", skip_all, err, fields(account_id = %scope.account_id, size = bytes.len()))]
    pub async fn complete_media_import(
        &self,
        scope: SessionScope,
        attachment: &AttachmentRef,
        bytes: &[u8],
    ) -> ExternalChatResult<()> {
        if bytes.is_empty() || bytes.len() > MEDIA_LIMIT_BYTES {
            return Err(ExternalChatError::Invalid("attachment is empty or too large").into());
        }
        self.repository
            .complete_media_import(scope, attachment, bytes)
            .await
    }

    /// Report a failed download.
    #[tracing::instrument(name = "whatsapp.session.fail_media", skip_all, err, fields(account_id = %scope.account_id, failure = ?failure))]
    pub async fn fail_media_import(
        &self,
        scope: SessionScope,
        attachment: &AttachmentRef,
        failure: MediaFailure,
    ) -> ExternalChatResult<()> {
        self.repository
            .fail_media_import(scope, attachment, failure)
            .await
    }

    /// Bytes to upload for a claimed media send, before `begin_dispatch`.
    #[tracing::instrument(name = "whatsapp.session.outbound_media", skip_all, err, fields(account_id = %scope.account_id, send_id = %send))]
    pub async fn outbound_media(
        &self,
        scope: SessionScope,
        send: Uuid,
    ) -> ExternalChatResult<OutboundMedia> {
        self.repository.outbound_media(scope, send).await
    }

    /// WhatsApp logged the device out or rejected its credentials. Consent ends;
    /// the owner must reconnect explicitly.
    #[tracing::instrument(name = "whatsapp.session.logged_out", skip_all, err, fields(account_id = %scope.account_id))]
    pub async fn logged_out(&self, scope: SessionScope) -> ExternalChatResult<()> {
        self.repository.logged_out(scope).await
    }

    /// Report full metadata for the account's groups. With `complete`, the list
    /// is every group the account is in, and missing groups count as left.
    #[tracing::instrument(name = "whatsapp.session.update_groups", skip_all, err, fields(account_id = %scope.account_id, count = groups.len(), complete = complete))]
    pub async fn update_groups(
        &self,
        scope: SessionScope,
        groups: &[GroupInfo],
        complete: bool,
    ) -> ExternalChatResult<()> {
        if groups.len() > 10_000
            || groups.iter().any(|g| {
                !is_group_jid(&g.jid) || g.name.len() > 1024 || g.participants.len() > 5_000
            })
        {
            return Err(ExternalChatError::Invalid("invalid group metadata").into());
        }
        self.repository.update_groups(scope, groups, complete).await
    }

    /// Report the current metadata of one group after a live group event (joined,
    /// renamed, participants changed). Signals pages only when something changed.
    #[tracing::instrument(name = "whatsapp.session.update_group", skip_all, err, fields(account_id = %scope.account_id))]
    pub async fn update_group(
        &self,
        scope: SessionScope,
        group: &GroupInfo,
    ) -> ExternalChatResult<()> {
        self.update_groups(scope, std::slice::from_ref(group), false)
            .await
    }

    /// The account is no longer in this group, as a live group event or a
    /// refused metadata read showed.
    #[tracing::instrument(name = "whatsapp.session.group_left", skip_all, err, fields(account_id = %scope.account_id))]
    pub async fn group_left(
        &self,
        scope: SessionScope,
        group: &str,
        observed_at: chrono::DateTime<chrono::Utc>,
    ) -> ExternalChatResult<()> {
        if !is_group_jid(group) {
            return Err(ExternalChatError::Invalid("invalid group").into());
        }
        self.repository.group_left(scope, group, observed_at).await
    }

    /// Groups to keep: events from any other group are dropped before storage.
    pub async fn observed_groups(&self, scope: SessionScope) -> ExternalChatResult<Vec<String>> {
        self.repository.observed_groups(scope).await
    }

    /// Record what the account learned about chats in its WhatsApp chat list
    /// (history sync, live messages, contact and chat-setting updates). A
    /// batch is a whole history sync, so a chat whose JID or kind is invalid
    /// is skipped (counted on the span) rather than refusing the rest.
    #[tracing::instrument(name = "whatsapp.session.update_chats", skip_all, err, fields(account_id = %scope.account_id, count = chats.len(), skipped))]
    pub async fn update_chats(
        &self,
        scope: SessionScope,
        chats: &[ChatUpdate],
    ) -> ExternalChatResult<()> {
        let valid: Vec<ChatUpdate> = chats
            .iter()
            .filter(|chat| match chat.kind {
                ExternalChatKind::Group => is_group_jid(&chat.jid),
                ExternalChatKind::Direct => is_person_jid(&chat.jid),
            })
            .cloned()
            .collect();
        let skipped = chats.len() - valid.len();
        tracing::Span::current().record("skipped", skipped);
        if skipped > 0 {
            tracing::debug!(
                account_id = %scope.account_id,
                skipped,
                reason = "invalid_chat_jid",
                "Skipped WhatsApp chats with an invalid JID"
            );
        }
        if valid.is_empty() {
            return Ok(());
        }
        self.repository.update_chats(scope, &valid).await
    }

    /// The owner's groups still importing earlier messages from the phone.
    #[tracing::instrument(name = "whatsapp.session.backfill_work", skip_all, err, fields(account_id = %scope.account_id, count))]
    pub async fn backfill_work(
        &self,
        scope: SessionScope,
    ) -> ExternalChatResult<Vec<BackfillWork>> {
        let work = self.repository.backfill_work(scope).await?;
        tracing::Span::current().record("count", work.len());
        Ok(work)
    }

    /// Phone-number lookups the account's session should answer now.
    pub async fn pending_lookups(
        &self,
        scope: SessionScope,
    ) -> ExternalChatResult<Vec<LookupWork>> {
        self.repository.pending_lookups(scope).await
    }

    /// Record what WhatsApp answered about a looked-up number; a registered
    /// number's direct chat joins the chat list, ready to add.
    #[tracing::instrument(name = "whatsapp.session.complete_lookup", skip_all, err, fields(account_id = %scope.account_id, lookup_id = %lookup))]
    pub async fn complete_lookup(
        &self,
        scope: SessionScope,
        lookup: Uuid,
        answer: &LookupAnswer,
    ) -> ExternalChatResult<()> {
        if let LookupAnswer::Found { jid, .. } = answer
            && Jid::parse(jid).is_none_or(|jid| jid.kind != JidKind::Phone)
        {
            return Err(ExternalChatError::Invalid("a lookup found no phone-number JID").into());
        }
        self.repository.complete_lookup(scope, lookup, answer).await
    }

    /// No message of an added chat is known to start importing from.
    #[tracing::instrument(name = "whatsapp.session.backfill_waiting_for_message", skip_all, err, fields(account_id = %scope.account_id, chat_id = %group))]
    pub async fn backfill_waiting_for_message(
        &self,
        scope: SessionScope,
        group: Uuid,
    ) -> ExternalChatResult<()> {
        self.repository
            .backfill_waiting_for_message(scope, group)
            .await
    }

    /// A page of earlier messages was requested from the phone just now.
    #[tracing::instrument(name = "whatsapp.session.backfill_requested", skip_all, err, fields(account_id = %scope.account_id, chat_id = %group))]
    pub async fn backfill_requested(
        &self,
        scope: SessionScope,
        group: Uuid,
    ) -> ExternalChatResult<()> {
        self.repository.backfill_requested(scope, group).await
    }

    /// The phone did not answer; the import waits for it.
    #[tracing::instrument(name = "whatsapp.session.backfill_unanswered", skip_all, err, fields(account_id = %scope.account_id, chat_id = %group))]
    pub async fn backfill_unanswered(
        &self,
        scope: SessionScope,
        group: Uuid,
    ) -> ExternalChatResult<()> {
        self.repository.backfill_unanswered(scope, group).await
    }

    /// The phone sent a page of a chat's earlier messages (the messages
    /// themselves are ingested as history events).
    #[tracing::instrument(name = "whatsapp.session.backfill_page", skip_all, err, fields(account_id = %scope.account_id, messages = page.messages, complete = page.complete))]
    pub async fn backfill_page(
        &self,
        scope: SessionScope,
        page: &HistoryPage,
    ) -> ExternalChatResult<Vec<(Uuid, BackfillState)>> {
        if !is_group_jid(&page.chat_jid) && !is_person_jid(&page.chat_jid) {
            return Err(ExternalChatError::Invalid("a history page names no WhatsApp chat").into());
        }
        self.repository.backfill_page(scope, page).await
    }

    /// Persist one event from an observed group. Safe to repeat: every observing
    /// account converges on one group message per (binding, sender, source id).
    #[tracing::instrument(
        name = "whatsapp.session.ingest",
        skip_all, err,
        fields(account_id = %scope.account_id, event_id = %event.event_id, outcome, code)
    )]
    pub async fn ingest_event(
        &self,
        scope: SessionScope,
        event: &InboundEvent,
    ) -> ExternalChatResult<IngestOutcome> {
        let result = match validate_event(event) {
            Ok(()) => self.repository.ingest(scope, event).await,
            Err(error) => Err(error),
        };
        let span = tracing::Span::current();
        match &result {
            Ok(outcome) => span.record("outcome", tracing::field::debug(outcome)),
            Err(error) => span.record("code", error.current_context().code()),
        };
        result
    }

    /// Persist an event durably without notification or document work, so the protocol event can
    /// be acknowledged right after; `replay_deferred` ingests it. Idempotent on
    /// `event_id`. `Backlogged` when the account's backlog is full: do not ack.
    #[tracing::instrument(name = "whatsapp.session.enqueue_inbound", skip_all, err, fields(account_id = %scope.account_id, event_id = %event.event_id))]
    pub async fn enqueue_inbound(
        &self,
        scope: SessionScope,
        event: &InboundEvent,
    ) -> ExternalChatResult<()> {
        validate_event(event)?;
        self.repository.enqueue_inbound(scope, event).await
    }

    /// Ingest enqueued events and retry deferred ones whose time has come.
    /// Returns how many applied. Call after `enqueue_inbound` and periodically.
    #[tracing::instrument(name = "whatsapp.session.replay_deferred", skip_all, err, fields(account_id = %scope.account_id, due, applied))]
    pub async fn replay_deferred(&self, scope: SessionScope) -> ExternalChatResult<usize> {
        let due = self.repository.due_events(scope, 64).await?;
        tracing::Span::current().record("due", due.len());
        let mut applied = 0;
        for event in &due {
            match self.repository.ingest(scope, event).await {
                Ok(IngestOutcome::Applied) => applied += 1,
                Ok(_) => {}
                Err(error) if matches!(error.current_context(), ExternalChatError::Fenced) => {
                    return Err(error);
                }
                // One bad event never blocks the others; it stays deferred.
                Err(error) => tracing::warn!(
                    event_id = %event.event_id,
                    code = error.current_context().code(),
                    error = %error,
                    "Deferred WhatsApp event will retry"
                ),
            }
        }
        tracing::Span::current().record("applied", applied);
        Ok(applied)
    }

    /// Claim pending sends in group order. Answer `whatsapp_send_requested`.
    #[tracing::instrument(name = "whatsapp.session.claim_sends", skip_all, err, fields(account_id = %scope.account_id, count))]
    pub async fn claim_sends(
        &self,
        scope: SessionScope,
        limit: i64,
    ) -> ExternalChatResult<Vec<ClaimedSend>> {
        let claimed = self
            .repository
            .claim_sends(scope, limit.clamp(1, 64))
            .await?;
        tracing::Span::current().record("count", claimed.len());
        Ok(claimed)
    }

    /// Record that this send is about to be submitted with this WhatsApp message
    /// id. Only submit after this succeeds; afterwards the send is never retried.
    #[tracing::instrument(name = "whatsapp.session.begin_dispatch", skip_all, err, fields(account_id = %scope.account_id, send_id = %send))]
    pub async fn begin_dispatch(
        &self,
        scope: SessionScope,
        send: Uuid,
        source_id: &str,
    ) -> ExternalChatResult<()> {
        if source_id.is_empty() || source_id.len() > 256 {
            return Err(ExternalChatError::Invalid("invalid message id").into());
        }
        self.repository.begin_dispatch(scope, send, source_id).await
    }

    /// Record the outcome of a dispatched send.
    #[tracing::instrument(name = "whatsapp.session.send_outcome", skip_all, err, fields(account_id = %scope.account_id, send_id = %send, outcome))]
    pub async fn record_send_outcome(
        &self,
        scope: SessionScope,
        send: Uuid,
        outcome: SendOutcome,
    ) -> ExternalChatResult<()> {
        let name = match &outcome {
            SendOutcome::Accepted { .. } => "accepted",
            SendOutcome::Rejected { .. } => "rejected",
            SendOutcome::Unknown => "unknown",
        };
        tracing::Span::current().record("outcome", name);
        self.repository
            .record_send_outcome(scope, send, &outcome)
            .await
    }
}

pub(crate) fn validate_event(event: &InboundEvent) -> ExternalChatResult<()> {
    let direct = is_person_jid(&event.group_jid);
    if !is_group_jid(&event.group_jid) && !direct {
        return Err(ExternalChatError::Invalid("invalid chat").into());
    }
    if event
        .chat_alternate_jid
        .as_deref()
        .is_some_and(|alternate| !direct || !is_person_jid(alternate))
    {
        return Err(ExternalChatError::Invalid("invalid chat").into());
    }
    match &event.kind {
        InboundKind::Left => Ok(()),
        InboundKind::Receipt(receipt) => {
            if receipt.source_ids.is_empty()
                || receipt.source_ids.len() > 256
                || receipt
                    .source_ids
                    .iter()
                    .any(|id| id.is_empty() || id.len() > 256)
                || !is_person_jid(&receipt.participant_jid)
            {
                return Err(ExternalChatError::Invalid("invalid receipt").into());
            }
            Ok(())
        }
        InboundKind::Message(message) => {
            let sender = &message.sender;
            // A group change WhatsApp made without naming who did it is the
            // group's own.
            let group_itself = message.kind == MessageKind::System
                && sender.jid == event.group_jid
                && sender.alternate_jid.is_none();
            if message.source_id.is_empty()
                || message.source_id.len() > 256
                || !(is_person_jid(&sender.jid) || group_itself)
                || sender
                    .alternate_jid
                    .as_deref()
                    .is_some_and(|jid| !is_person_jid(jid))
                || sender
                    .display_name
                    .as_deref()
                    .is_some_and(|name| name.len() > 512)
                || message.text.len() > INBOUND_TEXT_LIMIT_BYTES
                || message.revision < 0
                || message.media.len() > 10
            {
                return Err(ExternalChatError::Invalid("invalid message").into());
            }
            let needs_target = matches!(
                message.kind,
                MessageKind::Reaction
                    | MessageKind::Edit
                    | MessageKind::Delete
                    | MessageKind::PollVote
            );
            if needs_target && message.target.is_none() {
                return Err(
                    ExternalChatError::Invalid("message operation without a target").into(),
                );
            }
            let rich_fits = match (message.kind, &message.rich) {
                (MessageKind::System, Some(RichContent::System(_)))
                | (MessageKind::PollVote, Some(RichContent::PollVote(_)))
                | (
                    MessageKind::Rich,
                    Some(
                        RichContent::Poll(_)
                        | RichContent::Location(_)
                        | RichContent::Contacts(_)
                        | RichContent::Event(_),
                    ),
                ) => true,
                (MessageKind::System | MessageKind::PollVote | MessageKind::Rich, _) => false,
                (_, rich) => rich.is_none(),
            };
            if !rich_fits || message.mentions.len() > 256 {
                return Err(ExternalChatError::Invalid("invalid message content").into());
            }
            // Only the verified author edits or deletes. Admin deletions need
            // separate role evidence and are not imported.
            if matches!(message.kind, MessageKind::Edit | MessageKind::Delete)
                && message.target.as_ref().is_some_and(|target| {
                    target.sender_jid != sender.jid
                        && sender.alternate_jid.as_deref() != Some(target.sender_jid.as_str())
                })
            {
                return Err(ExternalChatError::Forbidden.into());
            }
            Ok(())
        }
    }
}