forge_primitives/

slack.rs

//! Slack connector shapes that cross a crate boundary: the `[[slack]]`
//! config entry an operator writes, the conversation shape
//! `users.conversations` reports, and the subscription record a session
//! creates.

use std::collections::HashMap;
use std::time::SystemTime;

use serde::{Deserialize, Serialize};
use uuid::Uuid;

/// One `[[slack]]` entry. The token is a credential, so it lives in
/// `forge.toml` rather than in the state DB beside the subscriptions.
#[derive(Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SlackConfig {
    /// Tells workspaces apart in the MCP tools and the Inspector.
    pub workspace: String,
    /// User token, `xoxp-...`.
    pub token: String,
    /// Sweep interval for this workspace, in seconds.
    #[serde(default = "default_poll_seconds")]
    pub poll_seconds: u64,
    /// Sweep interval for the DM class, in seconds. It covers every DM in the
    /// workspace rather than a list, so it costs one history read per DM per
    /// pass whatever the subscription count - which is why it runs on its own,
    /// slower clock beside `poll_seconds`.
    #[serde(default = "default_dm_poll_seconds")]
    pub dm_poll_seconds: u64,
    /// A followed thread with nothing new for this many days is dropped:
    /// one that quiet is resolved in practice, whatever its parent's age.
    #[serde(default = "default_thread_idle_days")]
    pub thread_idle_days: u64,
    /// A block whose newest message is at or past this many hours old carries
    /// its age in its header. Zero turns the mark off; nothing is dropped.
    #[serde(default = "default_stale_after_hours")]
    pub stale_after_hours: u64,
}

/// Sweep interval a workspace gets when it names none. Slack's API
/// allowance is per workspace, and the DM class costs one history call per
/// DM conversation it covers, so a workspace with a large inbox wants its
/// own `poll_seconds`.
pub const DEFAULT_POLL_SECONDS: u64 = 5;

/// Idle window a workspace gets when it names none.
pub const DEFAULT_THREAD_IDLE_DAYS: u64 = 14;

/// Age a delivered block may reach before its header says so.
pub const DEFAULT_STALE_AFTER_HOURS: u64 = 24;

/// DM-class sweep interval a workspace gets when it names none.
///
/// The two clocks spend one token's allowance for the same method, so the DM
/// class has to fit beside the conversation pass rather than alone: at
/// `poll_seconds` 5 that pass costs about 36 calls a minute (a directory list
/// plus one history read per named conversation, and thread walks on top),
/// against a measured 77. The largest inbox measured is 91 DMs, one history
/// call each, so it needs at least 135 seconds and 150 is that with margin. The
/// smaller inbox is comfortable either way: 48 DMs lands near 20 calls a minute.
///
/// The floor is real rather than tidy: at 77 calls a minute the token was
/// measured clean - 30 back-to-back `conversations.history` calls, no 429 at
/// all - and deliberately paced runs at 45 to 57 were comfortable, so 77 is the
/// highest rate observed rather than a projection.
pub const DEFAULT_DM_POLL_SECONDS: u64 = 150;

/// The slowest a workspace may set the DM clock to. Below this the class
/// outruns the allowance it shares with the conversation pass, which is the
/// overrun the key exists to prevent.
pub const MIN_DM_POLL_SECONDS: u64 = 10;

fn default_poll_seconds() -> u64 {
    DEFAULT_POLL_SECONDS
}

fn default_dm_poll_seconds() -> u64 {
    DEFAULT_DM_POLL_SECONDS
}

fn default_thread_idle_days() -> u64 {
    DEFAULT_THREAD_IDLE_DAYS
}

fn default_stale_after_hours() -> u64 {
    DEFAULT_STALE_AFTER_HOURS
}

/// Hand-written because the token must never be printed, the same reason
/// `SlackClient` writes its own.
impl std::fmt::Debug for SlackConfig {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SlackConfig")
            .field("workspace", &self.workspace)
            .field("token", &"[redacted]")
            .field("poll_seconds", &self.poll_seconds)
            .field("dm_poll_seconds", &self.dm_poll_seconds)
            .field("thread_idle_days", &self.thread_idle_days)
            .field("stale_after_hours", &self.stale_after_hours)
            .finish()
    }
}

/// Slack sends `purpose` and `topic` as objects carrying their text in
/// `value`, and omits both on a DM.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
pub struct SlackConversationText {
    #[serde(default)]
    pub value: String,
}

/// A conversation as `users.conversations` reports it. Fields Slack omits
/// per conversation type default rather than failing the whole decode.
#[derive(Debug, Clone, Deserialize)]
pub struct SlackConversation {
    pub id: String,
    #[serde(default)]
    pub name: Option<String>,
    #[serde(default)]
    pub is_channel: bool,
    #[serde(default)]
    pub is_private: bool,
    #[serde(default)]
    pub is_im: bool,
    #[serde(default)]
    pub is_mpim: bool,
    #[serde(default)]
    pub is_archived: bool,
    /// The other member's user id, present on a DM.
    #[serde(default)]
    pub user: Option<String>,
    #[serde(default)]
    pub purpose: Option<SlackConversationText>,
    #[serde(default)]
    pub topic: Option<SlackConversationText>,
}

/// What one subscription watches inside a workspace.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum SlackSubscriptionTarget {
    /// Every DM in the workspace, group DMs included - the DM class the
    /// design settled on, so a new DM needs no new subscription.
    DirectMessages,
    /// One conversation, with the mode that decides what reaches the session.
    /// `name` is the display name, which may arrive after the record is
    /// written: the sweep backfills it from its directory, and a record
    /// still without one renders the raw id.
    Conversation {
        id: String,
        #[serde(default)]
        name: Option<String>,
        mode: SlackWatchMode,
    },
    /// Every message in this workspace that mentions the user, including
    /// public channels they are not in. Not private channels they are not
    /// in, which they could not read anyway.
    ///
    /// Swept by one search per workspace rather than by conversation, so
    /// the per-conversation matching path never claims it - letting both
    /// claim a mention would deliver it twice.
    Mentions,
}

/// What a conversation subscription lets through.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum SlackWatchMode {
    /// Every message.
    All,
    /// Only messages that mention the user.
    MentionsOnly,
}

/// One watched target, owned by one session.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SlackSubscription {
    pub id: Uuid,
    /// The `[[slack]]` label this watches.
    pub workspace: String,
    /// Owning project. Named `project` and `team_role` to match
    /// `GotifySubscription`; a rename would decode to `None` and silently
    /// reroute every worker's subscription to the lead.
    pub project: String,
    pub team_role: Option<String>,
    pub target: SlackSubscriptionTarget,
    pub created_at: SystemTime,
}

/// A file as `files.info` reports it. `url_private` is a bearer fetch, not
/// a URL, and `name` is whatever the uploader chose to call it - untrusted
/// input as far as this code is concerned.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackFile {
    pub id: String,
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub url_private: String,
    /// Where the file was shared. The upload call answers no message `ts`,
    /// so this is the only place a posted file's message is named.
    #[serde(default, deserialize_with = "shares_or_null")]
    pub shares: SlackFileShares,
}

/// Slack sends `shares: null` on a file it has not shared; that is not an
/// object, and it reads as no shares rather than failing the whole file.
fn shares_or_null<'de, D>(deserializer: D) -> Result<SlackFileShares, D::Error>
where
    D: serde::Deserializer<'de>,
{
    Option::<SlackFileShares>::deserialize(deserializer).map(Option::unwrap_or_default)
}

/// A file's shares, keyed by visibility and then by conversation id.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
pub struct SlackFileShares {
    #[serde(default)]
    pub public: HashMap<String, Vec<SlackFileShare>>,
    #[serde(default)]
    pub private: HashMap<String, Vec<SlackFileShare>>,
}

/// One message a file was shared as, in one conversation.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackFileShare {
    pub ts: String,
}

/// One hit from `search.messages`. `conversation_name` is absent on a DM,
/// which has no name rather than an empty one. `user` is the author's id,
/// which the delivered block carries - `username` is only a handle. A
/// file-share with no text is a real hit, so the files ride along for
/// delivery and `slack__attachment`.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackSearchMatch {
    pub ts: String,
    #[serde(default)]
    pub text: String,
    pub conversation_id: String,
    #[serde(default)]
    pub conversation_name: Option<String>,
    #[serde(default)]
    pub username: Option<String>,
    #[serde(default)]
    pub user: Option<String>,
    #[serde(default)]
    pub thread_ts: Option<String>,
    #[serde(default)]
    pub files: Vec<SlackFile>,
}

/// One user as `users.info` and `users.list` report them. Every optional
/// field is optional because Slack omits fields per user type rather than
/// sending nulls.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackUser {
    pub id: String,
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub real_name: Option<String>,
    #[serde(default)]
    pub tz: Option<String>,
    /// A deactivated member keeps their row; they cannot be notified.
    #[serde(default)]
    pub deleted: bool,
    #[serde(default)]
    pub profile: Option<SlackUserProfile>,
}

/// The part of a user's profile a name lookup needs. `display_name` is what
/// people call themselves, which is often neither the handle nor the legal
/// name.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
pub struct SlackUserProfile {
    #[serde(default)]
    pub display_name: Option<String>,
}

/// One pinned message as `pins.list` reports it. Pins are messages, and
/// Slack omits the message object on any other row, which carries nothing
/// readable.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackPin {
    #[serde(default)]
    pub created: u64,
    #[serde(default)]
    pub created_by: Option<String>,
    #[serde(default)]
    pub message: Option<SlackPinMessage>,
}

/// The message body of a pinned row.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackPinMessage {
    pub ts: String,
    #[serde(default)]
    pub user: Option<String>,
    #[serde(default)]
    pub text: String,
}

/// One channel bookmark as `bookmarks.list` reports it.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct SlackBookmark {
    pub id: String,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub link: Option<String>,
}

/// One session's ownership of a followed thread, named after the
/// `SlackSubscription` fields it is taken from.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SlackThreadOwner {
    pub project: String,
    pub team_role: Option<String>,
}

/// What the store keeps about one followed thread: how far its replies have
/// been read, the newest edit already handed over, and the sessions whose
/// subscriptions put the thread on their radar.
///
/// The cursor is usually the string Slack sent, but not always: a thread
/// forge starts tracking seeds it one microsecond below the reply that
/// brought the thread in, since the cursor is exclusive. The per-tick read
/// sends one microsecond below the cursor as the walk's lower bound, so a
/// reply at the cursor is re-read for an edit; the periodic whole read passes
/// none. It is compared as a string throughout.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SlackThreadRecord {
    pub cursor: String,
    /// The newest edit stamp this thread has already handed over. Durable
    /// with the row: held in memory only, a restart re-offers every
    /// correction in the thread on the next whole read. A row written before
    /// this field existed reads as `None` and is approximated by its cursor,
    /// which drops an unjudged edit below that cursor and can re-offer an
    /// already-handed one above it.
    pub edit_watermark: Option<String>,
    pub owners: Vec<SlackThreadOwner>,
    /// Whether the user is in this thread, once that has been read off its
    /// replies. Kept because a reply cannot un-happen: once true, every walk
    /// can read past the cursor instead of reading the thread whole.
    #[serde(default)]
    pub participating: bool,
}

/// One followed thread as the pump sees it, minus the cursor it reads
/// through its own port method.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackFollowedThread {
    pub parent_ts: String,
    pub owners: Vec<SlackThreadOwner>,
    /// Whether the user is already known to be in this thread.
    pub participating: bool,
}

/// The thread a held draft replies into, named for the card: the parent's
/// author and one flattened line of its text, so the reader is not asked to
/// read a ts.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SlackThreadName {
    /// The parent's author: a bot's own name when the parent carries one,
    /// else the resolved display name, else the raw user id when that lookup
    /// fails. Never invented.
    pub author: String,
    /// The parent's text flattened to one line and cut at the last space
    /// before the bound where there is one. Empty when the parent carried no
    /// text.
    pub excerpt: String,
}

/// One person a held draft tags. `name` is the resolved display name; `None`
/// when the lookup failed, and the card draws the id rather than a guess.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SlackPerson {
    pub id: String,
    pub name: Option<String>,
}

/// A composed but unsent Slack message. The workspace holds it until the
/// user approves it in the dock prompt; nothing reaches Slack otherwise.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SlackDraft {
    pub id: Uuid,
    pub workspace: String,
    pub conversation: String,
    /// Display name for the conversation, which the approval prompt shows
    /// in place of the id: the DM partner's id when Slack names none.
    pub conversation_label: String,
    /// `None` posts a root message; `Some(ts)` replies into that thread.
    pub thread_ts: Option<String>,
    pub text: String,
    /// What the draft would do, which the approval prompt's verbs follow:
    /// the MCP tool alone cannot tell an edit from a delete, and the card
    /// must not say "post" for either.
    pub operation: SlackDraftOperation,
    /// The thread named for the card. `None` on a root message, and `None`
    /// when the parent could not be read: nothing is named that was not read.
    #[serde(default)]
    pub thread: Option<SlackThreadName>,
    /// Every person the draft's text tags, in order of first appearance. A
    /// mention the lookup could not name keeps its id, so no tag is dropped.
    #[serde(default)]
    pub tagged: Vec<SlackPerson>,
}

/// What a held draft would do in Slack.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SlackDraftOperation {
    Post,
    Edit,
    Delete,
    React,
    Unreact,
    Upload,
}

/// The reader's answer to a held draft, which is what the blocked call
/// receives.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SlackDraftAnswer {
    /// Let it go out.
    Approve,
    /// Do not send it.
    Decline,
    /// Do not send it, and hand the note back to the agent to revise.
    SendBack { note: String },
}

/// What ended a held draft, which a view that did not answer it has no
/// other way to learn.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SlackDraftEnding {
    /// The reader answered it, in whichever view: `approved` says whether
    /// the message went out.
    Answered { approved: bool },
    /// The reader sent it back with words for the agent; nothing went out.
    SentBack,
    /// The asking session went away before anyone answered.
    Abandoned,
}

/// One message as the pump sees it, after matching. Carries what delivery
/// needs and nothing the wire happened to include.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SlackMessage {
    pub workspace: String,
    pub conversation: String,
    /// Conversation name for display; the DM partner's id when unnamed.
    /// Not `Option`, so a caller never has to invent a fallback.
    pub conversation_label: String,
    pub ts: String,
    /// `None` on a message with no thread at all. Equal to `ts` on a
    /// thread's parent, and the parent's `ts` on a reply.
    pub thread_ts: Option<String>,
    pub user: Option<String>,
    /// The name to display for the author, resolved by the connector: the
    /// handle the search path sends, a bot's own name, or a `users.info`
    /// lookup. `None` means no name is known, and `user` carries a raw id
    /// that must never be shown as one.
    pub author: Option<String>,
    pub text: String,
    /// Set on a reply, carrying the parent's author. This, not `thread_ts`,
    /// is what marks a reply: a parent carries `thread_ts` too.
    pub parent_user_id: Option<String>,
    /// A parent's newest reply `ts`. Absent on a message with no replies.
    pub latest_reply: Option<String>,
    /// The `ts` of the message's newest edit, absent on one never edited.
    /// An edit keeps the message's own `ts`, so this is what says the text
    /// changed after it was sent - and what keeps a redelivered correction
    /// distinct from a re-run of the delivery it corrects.
    pub edited: Option<String>,
    /// Files shared on the message. A file-share with no text is a real
    /// message, and the ids are what `slack__attachment` fetches with.
    pub files: Vec<SlackFile>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_token_never_reaches_the_config_debug_output() {
        let config = SlackConfig {
            workspace: "acme".to_owned(),
            token: "xoxp-supersecret".to_owned(),
            poll_seconds: 30,
            dm_poll_seconds: 150,
            thread_idle_days: 14,
            stale_after_hours: 24,
        };
        let rendered = format!("{config:?}");
        assert!(!rendered.contains("supersecret"), "token leaked: {rendered}");
        assert!(rendered.contains("acme"), "the label stays readable: {rendered}");
    }

    /// Records written before conversation names were captured carry no
    /// `name` key; dropping them at decode would silently unsubscribe
    /// every session on restart.
    #[test]
    fn a_target_recorded_without_a_name_still_decodes() {
        let old = r#"{"Conversation":{"id":"C0C0T5E6RM1","mode":"All"}}"#;
        let target: SlackSubscriptionTarget =
            serde_json::from_str(old).expect("the old shape decodes");
        assert_eq!(
            target,
            SlackSubscriptionTarget::Conversation {
                id: "C0C0T5E6RM1".to_owned(),
                name: None,
                mode: SlackWatchMode::All,
            },
            "a missing name decodes as None, never as a decode failure",
        );
    }

    /// A send-back carries the reader's words, so the shape has to hold them
    /// whole: a note flattened to a tag would reach the agent as a hint rather
    /// than as what the reader said.
    #[test]
    fn a_draft_answer_carries_the_note_verbatim() {
        let answer = SlackDraftAnswer::SendBack { note: "tone it down".to_owned() };
        let encoded = serde_json::to_value(&answer).expect("an answer serialises");
        assert_eq!(
            encoded,
            serde_json::json!({ "send_back": { "note": "tone it down" } }),
            "the note rides the variant as its own field",
        );
        assert_eq!(
            serde_json::from_value::<SlackDraftAnswer>(encoded).expect("and decodes back"),
            answer,
        );
    }

    /// The card's verbs are chosen from this field, and the client narrows an
    /// unknown value to "post" - so every name is pinned: a renamed variant
    /// would draw post copy for a delete with nothing else red.
    #[test]
    fn a_draft_operation_crosses_as_the_name_the_card_reads() {
        for (operation, name) in [
            (SlackDraftOperation::Post, "post"),
            (SlackDraftOperation::Edit, "edit"),
            (SlackDraftOperation::Delete, "delete"),
            (SlackDraftOperation::React, "react"),
            (SlackDraftOperation::Unreact, "unreact"),
            (SlackDraftOperation::Upload, "upload"),
        ] {
            assert_eq!(
                serde_json::to_value(operation).expect("an operation serialises"),
                serde_json::json!(name),
                "this is the name the card reads the operation from",
            );
        }
    }

    /// The card names the thread it replies into and the people it tags
    /// instead of drawing a ts and raw ids. A draft recorded before those
    /// fields existed still decodes - the frame is additive, and a client
    /// older than it draws the line it always drew.
    #[test]
    fn a_draft_carries_its_thread_and_tags_and_an_older_draft_still_decodes() {
        let draft = SlackDraft {
            id: Uuid::nil(),
            workspace: "acme".to_owned(),
            conversation: "C1".to_owned(),
            conversation_label: "staging".to_owned(),
            thread_ts: Some("1758901234.482910".to_owned()),
            text: "confirmed <@U2>".to_owned(),
            operation: SlackDraftOperation::Post,
            thread: Some(SlackThreadName {
                author: "alice".to_owned(),
                excerpt: "the staging deploy is green...".to_owned(),
            }),
            tagged: vec![
                SlackPerson { id: "U2".to_owned(), name: Some("bob".to_owned()) },
                SlackPerson { id: "U3".to_owned(), name: None },
            ],
        };
        let encoded = serde_json::to_value(&draft).expect("a draft serialises");
        assert_eq!(
            encoded["thread"],
            serde_json::json!({
                "author": "alice",
                "excerpt": "the staging deploy is green...",
            }),
            "the thread crosses as its author and one line of the parent",
        );
        assert_eq!(
            encoded["tagged"],
            serde_json::json!([
                {"id": "U2", "name": "bob"},
                {"id": "U3", "name": null},
            ]),
            "an unresolved mention crosses with no name rather than being dropped",
        );
        assert_eq!(serde_json::from_value::<SlackDraft>(encoded).expect("and decodes back"), draft,);

        let older = serde_json::json!({
            "id": Uuid::nil(),
            "workspace": "acme",
            "conversation": "C1",
            "conversation_label": "staging",
            "thread_ts": null,
            "text": "hello",
            "operation": "post",
        });
        let decoded: SlackDraft =
            serde_json::from_value(older).expect("a draft recorded before the fields decodes");
        assert_eq!(
            (decoded.thread, decoded.tagged),
            (None, Vec::new()),
            "the absent fields read as no thread and no tags",
        );
    }

    /// A view that did not answer still hears how the draft ended, and a
    /// send-back is not a plain decline: the reader wrote something.
    #[test]
    fn a_sent_back_ending_crosses_as_its_own_name() {
        assert_eq!(
            serde_json::to_value(SlackDraftEnding::SentBack).expect("an ending serialises"),
            serde_json::json!("sent_back"),
        );
    }
}