Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
#![deny(missing_docs)]
//! This crate contains models for the search cursor.
use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
/// Required trait to be able to create a cursor from a Sortable list of items
pub trait SearchCursorAttributes {
/// Gets the entity id
fn entity_id(&self) -> uuid::Uuid;
/// Gets the updated_at
fn updated_at(&self) -> chrono::DateTime<chrono::Utc>;
}
/// Result of processing sorted results for pagination
#[derive(Debug, Clone)]
pub struct PaginatedResult<T> {
/// The items to return (with extra item removed if present)
pub items: Vec<T>,
/// The cursor for fetching the next page
pub cursor: SearchCursorOption,
}
/// Cursor for a single search method. Each variant matches the sort fields
/// of the search it paginates, so the values can be passed straight to
/// OpenSearch's `search_after` without re-purposing.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum SearchMethodCursor {
/// Sort: `[updated_at_ms desc, entity_id asc]`. Used by name searches and
/// the default channel content sort.
UpdatedAt {
/// Tiebreaker entity id.
entity_id: uuid::Uuid,
/// Primary sort timestamp.
updated_at: chrono::DateTime<chrono::Utc>,
},
/// Sort: `[thread_id desc, message_id desc]`. Used by channel content
/// search in thread-grouped mode.
Thread {
/// Primary sort key.
thread_id: uuid::Uuid,
/// Tiebreaker for replies within the same thread.
message_id: uuid::Uuid,
},
}
impl SearchMethodCursor {
/// Produces the values to pass as OpenSearch `search_after`.
pub fn search_after(&self) -> Vec<serde_json::Value> {
match self {
Self::UpdatedAt {
entity_id,
updated_at,
} => vec![
serde_json::json!(updated_at.timestamp_millis()),
serde_json::json!(entity_id.to_string()),
],
Self::Thread {
thread_id,
message_id,
} => vec![
serde_json::json!(thread_id.to_string()),
serde_json::json!(message_id.to_string()),
],
}
}
/// Returns `(entity_id, updated_at)` for the `UpdatedAt` variant.
/// Callers that only paginate by `(updated_at, entity_id)` use this to
/// avoid exhaustive matching; `Thread` cursors yield `None`.
pub fn as_updated_at(&self) -> Option<(uuid::Uuid, chrono::DateTime<chrono::Utc>)> {
match self {
Self::UpdatedAt {
entity_id,
updated_at,
} => Some((*entity_id, *updated_at)),
Self::Thread { .. } => None,
}
}
/// Encodes the cursor as a base64 string for client transport.
pub fn encode(&self) -> Option<String> {
serde_json::to_vec(self)
.ok()
.map(|bytes| BASE64.encode(bytes))
}
/// Decodes a base64-encoded cursor string.
pub fn decode(encoded: &str) -> Option<Self> {
BASE64
.decode(encoded)
.ok()
.and_then(|bytes| serde_json::from_slice(&bytes).ok())
}
}
/// Represents the state of a search cursor
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum SearchCursorOption {
/// The cursor has either not been started or is not exhausted
NotDone(Option<SearchMethodCursor>),
/// The cursor is exhausted
Done,
}
impl Default for SearchCursorOption {
fn default() -> Self {
SearchCursorOption::NotDone(None)
}
}
impl SearchCursorOption {
/// Returns true if there are more results to fetch
pub fn has_more(&self) -> bool {
matches!(self, SearchCursorOption::NotDone(_))
}
/// Returns true if the cursor is exhausted (no more results)
pub fn is_done(&self) -> bool {
matches!(self, SearchCursorOption::Done)
}
/// Processes sorted results for pagination.
///
/// Expects the query to have fetched `limit + 1` items. Returns the trimmed
/// items (at most `limit`) and the appropriate cursor.
pub fn paginate<T: SearchCursorAttributes>(
mut items: Vec<T>,
limit: usize,
) -> PaginatedResult<T> {
let has_more = items.len() > limit;
if has_more {
items.pop();
}
let cursor = if has_more {
match items.last() {
Some(last) => SearchCursorOption::NotDone(Some(SearchMethodCursor::UpdatedAt {
entity_id: last.entity_id(),
updated_at: last.updated_at(),
})),
None => SearchCursorOption::Done,
}
} else {
SearchCursorOption::Done
};
PaginatedResult { items, cursor }
}
}
/// The search cursor contains all the individual `SearchCursorOption` for each search method.
#[derive(Debug, serde::Serialize, serde::Deserialize, Default)]
pub struct SearchCursor {
/// The chat name cursor
pub chat_name_cursor: SearchCursorOption,
/// The content cursor
pub content_cursor: SearchCursorOption,
/// The project cursor
pub project_name_cursor: SearchCursorOption,
/// The CRM company name cursor. `#[serde(default)]` so cursors minted
/// before CRM search existed still decode (defaults to a fresh cursor).
#[serde(default)]
pub crm_company_cursor: SearchCursorOption,
/// The channel name cursor. `#[serde(default)]` so cursors minted before
/// channels were name-searched in Postgres still decode.
#[serde(default)]
pub channel_name_cursor: SearchCursorOption,
}
impl SearchCursor {
/// Decodes a base64-encoded cursor string into a SearchCursor
pub fn decode(encoded: &str) -> Option<Self> {
BASE64
.decode(encoded)
.ok()
.and_then(|bytes| serde_json::from_slice(&bytes).ok())
}
/// Encodes the SearchCursor into a base64 string
pub fn encode(&self) -> Option<String> {
serde_json::to_vec(self)
.ok()
.map(|bytes| BASE64.encode(bytes))
}
/// Returns if the cursor is fully exhausted
pub fn is_exhausted(&self) -> bool {
self.chat_name_cursor.is_done()
&& self.content_cursor.is_done()
&& self.project_name_cursor.is_done()
&& self.crm_company_cursor.is_done()
&& self.channel_name_cursor.is_done()
}
}
#[cfg(test)]
mod test {
use super::*;
/// A cursor minted before CRM search existed (no `crm_company_cursor`
/// field) must still decode, with the new field defaulting to a fresh
/// `NotDone(None)` rather than failing.
#[test]
fn decodes_legacy_cursor_without_crm_field() {
let legacy = r#"{"document_name_cursor":"Done","chat_name_cursor":"Done","content_cursor":"Done","project_name_cursor":"Done"}"#;
let encoded = BASE64.encode(legacy);
let cursor = SearchCursor::decode(&encoded).expect("legacy cursor should decode");
assert!(
cursor.crm_company_cursor.has_more(),
"missing crm cursor should default to NotDone(None)"
);
// The four legacy sources are Done, but the defaulted CRM cursor is
// NotDone, so the whole cursor is not yet exhausted.
assert!(!cursor.is_exhausted());
}
/// A cursor minted before channels were name-searched in Postgres (no
/// `channel_name_cursor` field) decodes with a fresh channel cursor, so
/// the next page runs the channel search from the start.
#[test]
fn decodes_legacy_cursor_without_channel_name_field() {
let legacy = r#"{"chat_name_cursor":"Done","content_cursor":"Done","project_name_cursor":"Done","crm_company_cursor":"Done"}"#;
let encoded = BASE64.encode(legacy);
let cursor = SearchCursor::decode(&encoded).expect("legacy cursor should decode");
assert!(cursor.channel_name_cursor.has_more());
assert!(!cursor.is_exhausted());
}
#[test]
fn crm_cursor_round_trips() {
let cursor = SearchCursor {
crm_company_cursor: SearchCursorOption::Done,
..Default::default()
};
let decoded = SearchCursor::decode(&cursor.encode().expect("encode")).expect("decode");
assert!(decoded.crm_company_cursor.is_done());
}
#[test]
fn is_exhausted_requires_every_source_done() {
let mut cursor = SearchCursor {
chat_name_cursor: SearchCursorOption::Done,
content_cursor: SearchCursorOption::Done,
project_name_cursor: SearchCursorOption::Done,
crm_company_cursor: SearchCursorOption::Done,
channel_name_cursor: SearchCursorOption::Done,
};
assert!(cursor.is_exhausted());
cursor.crm_company_cursor = SearchCursorOption::NotDone(None);
assert!(
!cursor.is_exhausted(),
"a not-done CRM cursor must keep the aggregate cursor alive"
);
cursor.crm_company_cursor = SearchCursorOption::Done;
cursor.channel_name_cursor = SearchCursorOption::NotDone(None);
assert!(
!cursor.is_exhausted(),
"a not-done channel name cursor must keep the aggregate cursor alive"
);
}
}