//! Read-before-comment guard backed by forge's own notification //! read-state — no local mirror (which drifts across restarts). //! //! `hive-forge-notify` marks a thread read on forge as soon as it delivers //! the thread to the agent as a todo, so the todo carries the news and //! forge's unread flag does not wait for the agent to open the thread. //! "Unread activity here" is therefore "forge still has an unread //! notification for this thread": activity newer than the last delivery //! (the poll interval, about 30 s) and threads whose delivery failed. //! Reading a thread (`comments` / `view`) also marks its notification //! read, so the guard clears for a thread the agent opens itself. use anyhow::Result; use forge_client::NotificationThread; use forgejo_api::structs::NotifyReadThreadQuery; use crate::client::{Client, index, split_repo}; /// Forgejo's per-page notification cap. const PAGE_SIZE: u32 = 50; /// How many pages of unread notifications to scan for the thread. /// Notifications come newest-first and a thread the caller is about to /// comment on was just active, so it sits near the top; this cap keeps /// the guard cheap even when the unread list is large (an uncontrolled /// firehose), at the cost of not detecting a match buried past /// `MAX_PAGES * PAGE_SIZE` unread items (degrade-open — acceptable for /// a courtesy guard). const MAX_PAGES: u32 = 5; /// The notification thread id of an UNREAD notification on /// `#`, or `None` when the thread has no unread /// notification (nothing to read / already read). Repo-scoped so a bare /// number can't false-match another repo. Errors only on transport / /// non-2xx — callers degrade open on `Err`. pub fn unread_thread_id(client: &Client, repo: &str, number: u64) -> Result> { let (owner, name) = split_repo(repo)?; let limit = PAGE_SIZE.to_string(); let path = format!("/repos/{owner}/{name}/notifications"); for page in 1..=MAX_PAGES { let page_str = page.to_string(); let threads: Vec = client.get_api_json( &path, &[("all", "false"), ("page", &page_str), ("limit", &limit)], )?; for n in &threads { let subject_url = n .subject .as_ref() .and_then(|s| s.url.as_ref()) .map_or("", url::Url::as_str); if subject_matches(subject_url, number) { return Ok(n.id.as_deref().and_then(|id| id.parse().ok())); } } // Last (short) page reached — stop. if threads.len() < PAGE_SIZE as usize { break; } } Ok(None) } /// Mark a notification thread read (best-effort; the caller ignores the /// result). Clears the unread signal so a subsequent comment isn't /// blocked after the agent has read the thread. pub fn mark_thread_read(client: &Client, thread_id: u64) -> Result<()> { client .api() .notify_read_thread(index(thread_id)?, NotifyReadThreadQuery::default()) .send()?; Ok(()) } /// Reading a thread (`comments` / `view`) is the "I've seen it" signal: /// clear its unread notification so the read-before-comment guard lets a /// subsequent comment through. Fully best-effort — never fails or noises /// up the read verb (a thread with no unread notification is a no-op). pub fn mark_read_best_effort(client: &Client, repo: &str, number: u64) { if let Ok(Some(id)) = unread_thread_id(client, repo, number) { let _ = mark_thread_read(client, id); } } /// True when a notification `subject.url` refers to issue/PR `number` in /// the (already repo-scoped) query. Forgejo subject URLs end in the /// issue/PR number (an `/issues/` or `/pulls/` path); match the /// trailing path segment. Tolerates a trailing slash. #[must_use] pub fn subject_matches(subject_url: &str, number: u64) -> bool { subject_url .trim_end_matches('/') .rsplit('/') .next() .and_then(|seg| seg.parse::().ok()) == Some(number) } #[cfg(test)] mod tests { use super::subject_matches; #[test] fn matches_issue_subject_url() { assert!(subject_matches( "https://forge/api/v1/repos/o/r/issues/42", // lint:allow: test fixture, not a real forge link 42 )); } #[test] fn matches_pull_subject_url() { assert!(subject_matches("https://forge/api/v1/repos/o/r/pulls/7", 7)); } #[test] fn tolerates_trailing_slash() { assert!(subject_matches( "https://forge/api/v1/repos/o/r/issues/9/", // lint:allow: test fixture, not a real forge link 9 )); } #[test] fn rejects_different_number() { assert!(!subject_matches( "https://forge/api/v1/repos/o/r/issues/42", // lint:allow: test fixture, not a real forge link 7 )); } #[test] fn rejects_non_numeric_tail() { assert!(!subject_matches("https://forge/api/v1/repos/o/r", 42)); } #[test] fn rejects_substring_number() { // 142 must not match 42 — full-segment parse, not substring. assert!(!subject_matches( "https://forge/api/v1/repos/o/r/issues/142", // lint:allow: test fixture, not a real forge link 42 )); } }