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
//! Stable import identities, commands and receipts. See `docs/runbooks/slack-archive-import-contract.md`.
use std::{collections::BTreeMap, fmt, str::FromStr};
use chrono::{DateTime, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use uuid::Uuid;
#[cfg(test)]
mod test;
/// Safe, content-free validation failure; never includes supplied input.
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
pub enum ValidationError {
/// An identifier has an invalid shape.
#[error("invalid identifier")]
InvalidId,
/// A path component could escape its namespace.
#[error("unsafe key segment")]
UnsafeKeySegment,
/// A timestamp is malformed or out of range.
#[error("invalid Slack timestamp")]
InvalidTimestamp,
/// SHA-256 must be 64 lowercase hexadecimal characters.
#[error("invalid SHA-256")]
InvalidDigest,
/// A configured byte, record or collection bound was exceeded.
#[error("import limit exceeded")]
LimitExceeded,
/// Descriptors are not the exact contiguous manifest declared by the seal.
#[error("invalid manifest")]
InvalidManifest,
}
macro_rules! uuid_id {
($name:ident, $doc:literal) => {
#[doc = $doc]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "Uuid", into = "Uuid")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct $name(Uuid);
impl TryFrom<Uuid> for $name {
type Error = ValidationError;
fn try_from(value: Uuid) -> Result<Self, Self::Error> {
if value.is_nil() || value.is_max() {
return Err(ValidationError::InvalidId);
}
Ok(Self(value))
}
}
impl From<$name> for Uuid {
fn from(value: $name) -> Self {
value.0
}
}
impl FromStr for $name {
type Err = ValidationError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
Uuid::parse_str(value)
.map_err(|_| ValidationError::InvalidId)?
.try_into()
}
}
impl fmt::Display for $name {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(f)
}
}
};
}
uuid_id!(
JobId,
"Import job identity. Generate UUIDv7 in application code."
);
uuid_id!(
TeamId,
"Macro team identity, derived from an admin receipt, not request JSON."
);
uuid_id!(
CreateToken,
"Client-generated create idempotency token, scoped to team and administrator."
);
uuid_id!(
LeaseToken,
"Unpredictable fencing token for one worker claim; never part of public progress."
);
uuid_id!(WorkerId, "Identity of a worker process holding a lease.");
macro_rules! string_id {
($name:ident, $doc:literal, $validate:expr, $error:expr) => {
#[doc = $doc]
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct $name(String);
impl $name {
/// The validated string representation.
pub fn as_str(&self) -> &str {
&self.0
}
}
impl TryFrom<String> for $name {
type Error = ValidationError;
fn try_from(value: String) -> Result<Self, Self::Error> {
if !($validate)(&value) {
return Err($error);
}
Ok(Self(value))
}
}
impl From<$name> for String {
fn from(value: $name) -> Self {
value.0
}
}
impl FromStr for $name {
type Err = ValidationError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
value.to_owned().try_into()
}
}
impl fmt::Display for $name {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
self.0.fmt(f)
}
}
};
}
fn slack_id(value: &str, prefixes: &[u8]) -> bool {
(2..=64).contains(&value.len())
&& prefixes.contains(&value.as_bytes()[0])
&& value
.bytes()
.all(|b| b.is_ascii_uppercase() || b.is_ascii_digit())
}
fn safe_segment(value: &str) -> bool {
!value.is_empty()
&& value.len() <= 255
&& value != "."
&& value != ".."
&& !value
.chars()
.any(|c| c.is_control() || matches!(c, '/' | '\\' | '%'))
}
string_id!(
ConversationId,
"Source Slack conversation ID (C, G or D prefix); unique only within a source.",
|v: &str| slack_id(v, b"CGD"),
ValidationError::InvalidId
);
string_id!(
SourceId,
"Known Slack workspace identity (T prefix); an enterprise ID alone is insufficient.",
|v: &str| slack_id(v, b"T"),
ValidationError::InvalidId
);
string_id!(
SlackUserId,
"Slack member identity (U or W prefix), including USLACKBOT.",
|v: &str| slack_id(v, b"UW"),
ValidationError::InvalidId
);
string_id!(
KeySegment,
"Single safe source folder/key segment; never a path or authorization proof.",
safe_segment,
ValidationError::UnsafeKeySegment
);
string_id!(
ObjectKey,
"Server-generated staging object key. Never accepted in client or queue commands.",
|v: &str| v.len() <= 1024 && v.split('/').all(safe_segment),
ValidationError::UnsafeKeySegment
);
string_id!(
Sha256Digest,
"SHA-256 encoded as exactly 64 lowercase hexadecimal characters.",
|v: &str| v.len() == 64
&& v.bytes()
.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b)),
ValidationError::InvalidDigest
);
/// Slack time represented exactly as nonnegative Unix microseconds.
/// JSON is a string with six fractional digits, never a floating-point number.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "inbound", schema(value_type = String))]
pub struct SlackTimestamp(i64);
impl SlackTimestamp {
/// Exact number of microseconds since the Unix epoch.
pub fn unix_micros(self) -> i64 {
self.0
}
}
impl FromStr for SlackTimestamp {
type Err = ValidationError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
let invalid = ValidationError::InvalidTimestamp;
let (seconds, fraction) = value.split_once('.').ok_or(invalid)?;
if seconds.is_empty()
|| seconds.len() > 12
|| !(1..=6).contains(&fraction.len())
|| !seconds
.bytes()
.chain(fraction.bytes())
.all(|b| b.is_ascii_digit())
{
return Err(invalid);
}
let seconds: i64 = seconds.parse().map_err(|_| invalid)?;
// Bound to year 9999 for interoperable database/browser timestamps.
if seconds > 253_402_300_799 {
return Err(invalid);
}
let fraction: i64 =
fraction.parse::<i64>().map_err(|_| invalid)? * 10_i64.pow(6 - fraction.len() as u32);
Ok(Self(seconds * 1_000_000 + fraction))
}
}
impl TryFrom<String> for SlackTimestamp {
type Error = ValidationError;
fn try_from(value: String) -> Result<Self, Self::Error> {
value.parse()
}
}
impl From<SlackTimestamp> for String {
fn from(value: SlackTimestamp) -> Self {
value.to_string()
}
}
impl fmt::Display for SlackTimestamp {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}.{:06}", self.0 / 1_000_000, self.0 % 1_000_000)
}
}
/// Source identity supplied when creating a job. One binding per Macro team in v1.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(
tag = "kind",
rename_all = "snake_case",
rename_all_fields = "camelCase"
)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum SourceIdentity {
/// Archive names its Slack workspace; reject a conflicting team binding.
Known {
/// Workspace identifier in the archive.
#[serde(rename = "sourceId")]
source_id: SourceId,
},
/// Explicit confirmation that an unidentified archive belongs to this team's source.
/// Choosing this variant is affirmative confirmation, not an inferred default.
ConfirmedUnknown,
}
/// Slack conversation kind. Public Slack channels map to Macro Team, never Public.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum ConversationKind {
/// Team channel with explicit members and auto-join disabled.
PublicChannel,
/// Private Macro channel.
PrivateChannel,
/// Exactly two distinct mapped email identities; otherwise skip.
DirectMessage,
/// Private Macro channel named from source member display names.
GroupDirectMessage,
}
/// Full selected conversation metadata, persisted before granting any uploads.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ConversationMetadata {
/// Stable Slack identity.
pub slack_channel_id: ConversationId,
/// Source conversation kind.
pub kind: ConversationKind,
/// Original display name; not a storage key.
pub name: String,
/// Single archive folder name, not a backend object key.
pub folder: KeySegment,
/// Complete source member list, including members unknown to Macro.
pub member_ids: Vec<SlackUserId>,
/// Source creator when available.
pub creator_id: Option<SlackUserId>,
/// Missing time is resolved once from earliest message or persisted job time.
pub created_at: Option<SlackTimestamp>,
/// Source archived flag (does not silently archive a reused Macro target).
pub archived: bool,
/// Advisory only; null means not yet counted, not zero.
pub message_count: Option<u64>,
}
/// Create command. Team identity is deliberately absent.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateImport {
/// Replay with the same semantic payload returns the original job; changes conflict.
pub idempotency_token: CreateToken,
/// Binding or explicit unknown-source confirmation.
pub source: SourceIdentity,
/// Default true at the client; false still requires users and zero-part seals.
pub include_message_history: bool,
/// Full, unique selected conversations (at most the configured bound).
#[cfg_attr(feature = "inbound", schema(min_items = 1, max_items = 2000))]
pub conversations: Vec<ConversationMetadata>,
}
/// Configurable bounds shared with browser staging and enforced again by the worker.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ImportLimits {
/// Maximum NDJSON part bytes.
pub part_bytes: u64,
/// Maximum records per part.
pub part_records: u32,
/// Maximum bytes per NDJSON record, including newline.
pub record_bytes: u64,
/// Maximum users, root metadata or individual day JSON bytes.
pub json_bytes: u64,
/// Maximum selected temporary data bytes across all uploads.
pub selected_bytes: u64,
/// Maximum ZIP entries scanned by the browser.
pub zip_entries: u32,
/// Maximum selected conversations.
pub conversations: u32,
/// Maximum descriptors or completion identities per call.
pub registration_batch: u32,
/// Maximum historical batch payload bytes.
pub database_batch_bytes: u64,
/// Maximum messages in a historical batch.
pub database_batch_messages: u32,
}
impl Default for ImportLimits {
fn default() -> Self {
Self {
part_bytes: 16 * 1024 * 1024,
part_records: 20_000,
record_bytes: 1024 * 1024,
json_bytes: 32 * 1024 * 1024,
selected_bytes: 2 * 1024 * 1024 * 1024,
zip_entries: 100_000,
conversations: 2_000,
registration_batch: 50,
database_batch_bytes: 4 * 1024 * 1024,
database_batch_messages: 500,
}
}
}
/// Identity in a job's persisted manifest. No user-supplied object keys.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(
tag = "kind",
rename_all = "snake_case",
rename_all_fields = "camelCase",
deny_unknown_fields
)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum UploadId {
/// One normalized users payload from users.json and/or org_users.json.
Users,
/// One NDJSON part in a selected conversation.
ConversationPart {
/// Selected Slack conversation.
#[serde(rename = "slackChannelId")]
slack_channel_id: ConversationId,
/// Zero-based part index; sealed manifests must be contiguous.
#[serde(rename = "partIndex")]
part_index: u32,
},
}
/// Immutable expected object properties, registered before signing an upload.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct UploadDescriptor {
/// Manifest identity within this job.
pub upload: UploadId,
/// SHA-256 of the exact uploaded bytes, not the ETag.
pub sha256: Sha256Digest,
/// Exact byte length including delimiters.
pub byte_length: u64,
/// Exact NDJSON record count; null for the users JSON payload.
pub record_count: Option<u32>,
}
impl UploadDescriptor {
/// Check per-object limits and the users/NDJSON distinction.
/// The service separately checks aggregate bytes and selection membership.
pub fn validate(&self, limits: &ImportLimits) -> Result<(), ValidationError> {
let valid = match &self.upload {
UploadId::Users => {
self.record_count.is_none()
&& self.byte_length > 0
&& self.byte_length <= limits.json_bytes
}
UploadId::ConversationPart { .. } => {
self.byte_length > 0
&& self.byte_length <= limits.part_bytes
&& self
.record_count
.is_some_and(|n| n > 0 && n <= limits.part_records)
}
};
if valid {
Ok(())
} else {
Err(ValidationError::LimitExceeded)
}
}
}
/// Batched registration, also used to renew an unchanged descriptor's grant.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct RegisterUploads {
/// At most 50 descriptors; no duplicate identities in a call.
#[cfg_attr(feature = "inbound", schema(max_items = 50))]
pub descriptors: Vec<UploadDescriptor>,
}
/// Complete immutable expected part set for one conversation, including zero parts.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ConversationSeal {
/// Selected source conversation.
pub slack_channel_id: ConversationId,
/// Exact number of registered parts, starting at index zero.
pub part_count: u32,
/// SHA-256 of canonical descriptor lines; zero parts hash the empty byte string.
pub manifest_sha256: Sha256Digest,
}
impl ConversationSeal {
/// Validate and hash descriptors sorted by index, independently of registration order.
/// Input must contain only this conversation's parts, with no gaps or duplicates.
pub fn from_descriptors(
slack_channel_id: ConversationId,
descriptors: &[UploadDescriptor],
limits: &ImportLimits,
) -> Result<Self, ValidationError> {
let mut parts = Vec::with_capacity(descriptors.len());
let mut total_bytes = 0_u64;
for descriptor in descriptors {
descriptor.validate(limits)?;
let UploadId::ConversationPart {
slack_channel_id: id,
part_index,
} = &descriptor.upload
else {
return Err(ValidationError::InvalidManifest);
};
if *id != slack_channel_id {
return Err(ValidationError::InvalidManifest);
}
total_bytes = total_bytes
.checked_add(descriptor.byte_length)
.filter(|n| *n <= limits.selected_bytes)
.ok_or(ValidationError::LimitExceeded)?;
parts.push((*part_index, descriptor));
}
parts.sort_unstable_by_key(|(index, _)| *index);
let mut hash = Sha256::new();
for (expected, (index, descriptor)) in parts.iter().enumerate() {
if usize::try_from(*index).ok() != Some(expected) {
return Err(ValidationError::InvalidManifest);
}
let records = descriptor
.record_count
.ok_or(ValidationError::InvalidManifest)?;
hash.update(format!(
"{index}:{}:{}:{records}\n",
descriptor.sha256, descriptor.byte_length
));
}
Ok(Self {
slack_channel_id,
part_count: parts
.len()
.try_into()
.map_err(|_| ValidationError::LimitExceeded)?,
manifest_sha256: format!("{:x}", hash.finalize()).parse()?,
})
}
}
/// Explicit upload completion; a seal can be submitted separately with an empty list.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CompleteUploads {
/// Registered identities to verify against storage (at most 50).
#[cfg_attr(feature = "inbound", schema(max_items = 50))]
pub uploads: Vec<UploadId>,
/// Optional immutable expected part set; identical retries are idempotent.
pub seal: Option<ConversationSeal>,
}
/// Request for an existing job (finalize, cancel or progress); no body-supplied team.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct JobCommand {
/// Job identity from the resource path.
pub job_id: JobId,
}
/// Job lifecycle. Cancellation remains in progress while any lease is active.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum JobStatus {
/// Registration is open; some conversations may already be running.
Uploading,
/// Registration closed; ready conversations are queued or importing.
Processing,
/// All selected conversations settled successfully or were deliberately skipped.
Completed,
/// All work settled, with at least one failure and some successful work.
CompletedWithErrors,
/// Terminal failure without successful conversations.
Failed,
/// No further claims/publications; existing leases are settling.
Cancelling,
/// Terminal cancellation, retaining committed partial history.
Cancelled,
}
/// Durable per-conversation lifecycle.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum ConversationStatus {
/// Manifest or verified uploads are incomplete.
AwaitingUploads,
/// Readiness and a unique outbox event have committed together.
Queued,
/// Claimed under a renewable fenced lease.
Importing,
/// Historical persistence completed; indexing is tracked separately.
Completed,
/// Never ready at finalize, unauthorized target, unsupported DM, or cancelled unclaimed work.
Skipped,
/// Exhausted or non-retryable failure; partial committed counts remain visible.
Failed,
}
/// Public error codes; never carry raw provider errors, keys, emails or source text.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, thiserror::Error)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum ImportError {
/// Creation and upload operations are disabled by server configuration.
#[error("Slack imports are disabled")]
Disabled,
/// Malformed command or export data.
#[error("invalid import input")]
InvalidInput,
/// A configured bound was exceeded.
#[error("import limit exceeded")]
LimitExceeded,
/// Unknown or inaccessible job/target, deliberately indistinguishable.
#[error("import unavailable")]
Unavailable,
/// Requester is no longer a team administrator.
#[error("administrator access required")]
AdminRequired,
/// Known source differs from the team's bound source.
#[error("Slack workspace mismatch")]
SourceMismatch,
/// Idempotency token, descriptor, seal or lifecycle conflict.
#[error("import state conflict")]
Conflict,
/// Object checksum, length or identity disagrees with the persisted descriptor.
#[error("upload verification failed")]
UploadMismatch,
/// Current lease no longer permits writes.
#[error("import lease lost")]
LeaseLost,
/// Transient dependency outage; safe to retry using the same identity.
#[error("import temporarily unavailable")]
Retryable,
/// Exhausted retries or an internal failure, without leaking diagnostics.
#[error("import failed")]
Internal,
}
/// Non-fatal, sanitized explanations displayed in admin progress.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum ImportWarning {
/// Creation time resolved from earliest message.
CreationTimeFromMessage,
/// No source time; persisted job creation time used.
CreationTimeFromJob,
/// DM does not map to exactly two distinct email identities.
UnresolvableDirectMessage,
/// Existing target could not be authorized; no target ID may be exposed.
TargetUnavailable,
/// Conversation never became ready before finalization.
UploadsIncomplete,
}
/// Committed counters, never optimistic browser or uncommitted worker counts.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ImportCounters {
/// Source records examined through the committed checkpoint.
pub processed: u64,
/// Newly persisted messages.
pub imported: u64,
/// Previously committed source identities.
pub duplicates: u64,
/// Unsupported, empty or otherwise deliberately skipped records.
pub skipped: u64,
/// Newly persisted reactions.
pub reactions: u64,
}
/// Search publication/receipt state. Acceptance is not completed publication;
/// even completed publication still awaits consumer indexing and refresh.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(
tag = "status",
rename_all = "snake_case",
rename_all_fields = "camelCase"
)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum SearchState {
/// No committed history requires indexing.
NotNeeded,
/// Committed history requires an outbox-backed scoped submission.
Pending,
/// Search service accepted the request, but has not completed it.
Submitted {
/// Receipt from the search service.
#[serde(rename = "receiptId")]
receipt_id: Uuid,
},
/// Search service durably published the scope; eventual indexing is separate.
Completed,
/// Publication failed; retained history must be retried independently.
Failed,
}
/// Admin-visible progress for one selected conversation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ConversationProgress {
/// Source identity (always visible to the importing team's administrator).
pub slack_channel_id: ConversationId,
/// Persisted source display name, never the reused Macro target's name.
pub name: String,
/// Persisted source kind.
pub kind: ConversationKind,
/// Whether the selected source conversation was archived.
pub archived: bool,
/// Durable state.
pub status: ConversationStatus,
/// Authorized target only; absent for inaccessible reused targets.
pub channel_id: Option<Uuid>,
/// Null until sealed; zero is a valid sealed empty manifest.
pub part_count: Option<u32>,
/// Number of parts whose object identity has been verified.
pub verified_parts: u32,
/// Durably committed record counts.
pub counters: ImportCounters,
/// Independent indexing state.
pub search: SearchState,
/// Sanitized terminal or retry diagnostic.
pub error: Option<ImportError>,
/// Non-fatal metadata/skip explanations.
pub warnings: Vec<ImportWarning>,
}
/// Common receipt returned by create, completion, finalize, cancel and progress.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ImportProgress {
/// Immutable source confirmation from this job, not the current team binding.
pub source: SourceIdentity,
/// Immutable history option confirmed when creating this job.
pub include_message_history: bool,
/// Stable job identity.
pub job_id: JobId,
/// Durable job lifecycle.
pub status: JobStatus,
/// Monotonic job revision for polling/websocket invalidation.
pub revision: u64,
/// Persisted creation time, also the final historical-time fallback.
pub created_at: DateTime<Utc>,
/// Last durable lifecycle/progress update.
pub updated_at: DateTime<Utc>,
/// Registration closure time; cancellation also closes registration.
pub registration_closed_at: Option<DateTime<Utc>>,
/// Whether users metadata is verified and pinned.
pub users_verified: bool,
/// Server bounds for staging and registration.
pub limits: ImportLimits,
/// All selected conversations, bounded by the create limit.
pub conversations: Vec<ConversationProgress>,
}
/// Team's durable single-source binding, including confirmed unidentified archives.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(
tag = "kind",
rename_all = "snake_case",
rename_all_fields = "camelCase"
)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub enum SourceBinding {
/// No import has bound this team yet.
Unbound,
/// Legacy/onboarding or explicitly confirmed unidentified source.
ConfirmedUnknown,
/// Known Slack workspace; reject mismatches.
Known {
/// Bound source identity.
#[serde(rename = "sourceId")]
source_id: SourceId,
},
}
/// Admin list result, also supplying upload limits before a job exists.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ImportPage {
/// At most 50 job receipts, newest first.
pub jobs: Vec<ImportProgress>,
/// Exclusive cursor for the next page; null when exhausted.
pub next_cursor: Option<JobId>,
/// Effective server limits.
pub limits: ImportLimits,
/// Binding summary used by the picker confirmation.
pub source_binding: SourceBinding,
}
/// Signed upload permission returned just before PUT; never persisted as an identity.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct UploadGrant {
/// Exact immutable descriptor being signed.
pub descriptor: UploadDescriptor,
/// Short-lived signed destination; must not be logged.
pub url: String,
/// Required signed upload headers (including checksum, content type and create-only
/// condition). Browser-forbidden Content-Length is derived from the exact Blob bytes.
pub required_headers: BTreeMap<String, String>,
/// Grant expiry; callers renew by re-registering the identical descriptor.
pub expires_at: DateTime<Utc>,
}
/// Server-owned manifest entry used by storage adapters, never by request deserialization.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RegisteredUpload {
/// Expected bytes and manifest identity.
pub descriptor: UploadDescriptor,
/// Key generated server-side and looked up through the owning job's manifest.
pub key: ObjectKey,
}
string_id!(
ObjectValidator,
"Opaque storage version or entity tag, used only to pin reads; never interpreted as SHA-256.",
|v: &str| !v.is_empty() && v.len() <= 1024 && !v.chars().any(char::is_control),
ValidationError::InvalidId
);
/// Verified immutable object identity; adapters must enforce the selected read condition.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ObjectIdentity {
/// Read this exact storage version.
Version(ObjectValidator),
/// Conditional read against the verified entity tag when versioning is unavailable.
EntityTag(ObjectValidator),
}
/// Verified object and mandatory read pin. The streamed digest is checked independently.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VerifiedUpload {
/// Persisted manifest entry whose checksum and length storage verified.
pub registered: RegisteredUpload,
/// Version or entity-tag precondition; an unpinned read is never valid.
pub identity: ObjectIdentity,
}
/// Queue payload: identity and event generation only, never storage locations or authority.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ImportEvent {
/// Job owning the work.
pub job_id: JobId,
/// Selected source conversation.
pub slack_channel_id: ConversationId,
/// Durable outbox generation; distinct from the execution lease generation.
pub generation: u64,
}
/// Renewable worker fencing capability; every batch/final transition checks all fields.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Lease {
/// Work identity and publication generation.
pub event: ImportEvent,
/// Claiming process.
pub owner: WorkerId,
/// Fresh token per claim/reclaim.
pub token: LeaseToken,
/// Monotonically increasing execution generation.
pub generation: u64,
/// Persisted expiry, evaluated against the database clock.
pub expires_at: DateTime<Utc>,
/// Last persisted heartbeat time.
pub heartbeat_at: DateTime<Utc>,
/// Durable claim attempt count, including reclaims.
pub attempts: u32,
}
/// Exact restart position in the sorted, deduplicated NDJSON stream.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Checkpoint {
/// Next part to read (part count means end of stream).
pub part_index: u32,
/// Next zero-based line within that part.
pub record_index: u32,
}
/// Trusted persisted context loaded on claim, never reconstructed from a queue body.
#[derive(Debug, Clone)]
pub struct ClaimedConversation {
/// Current fenced lease.
pub lease: Lease,
/// Owning team for source-scoped dedupe and authorization.
pub team_id: TeamId,
/// Original requesting admin; revalidated before claim/reclaim.
pub requested_by: MacroUserIdStr<'static>,
/// Full selected source metadata.
pub metadata: ConversationMetadata,
/// Verified users payload, required even for shape-only imports.
pub users: VerifiedUpload,
/// Sealed verified parts in index order (possibly empty).
pub parts: Vec<VerifiedUpload>,
/// Durably committed restart position.
pub checkpoint: Checkpoint,
/// Stable fallback when creation time is absent.
pub job_created_at: DateTime<Utc>,
}
/// Claim result distinguishes busy work from obsolete events so a duplicate delivery
/// cannot accidentally acknowledge away another worker's recovery opportunity.
#[derive(Debug, Clone)]
pub enum ClaimOutcome {
/// Newly claimed or reclaimed persisted work.
Claimed(Box<ClaimedConversation>),
/// A current worker owns the work; defer delivery without acknowledging it.
ActiveLease,
/// Work is durably terminal, unknown or superseded by a newer durable event.
Obsolete,
}
/// Driver decision after processing an identity-only queue event.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkerOutcome {
/// Durable settlement or obsolete event; safe to acknowledge.
Acknowledge,
/// Active work still needs recovery coverage; do not acknowledge.
Defer,
}
/// Natural identity of a message, shared by thread lookup and durable dedupe.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
pub struct SourceMessageId {
/// Team's single bound Slack source namespace.
pub team_id: TeamId,
/// Source conversation, not target channel.
pub slack_channel_id: ConversationId,
/// Original exact Slack time.
pub ts: SlackTimestamp,
}
/// Historical attribution distinguishes an email-mapped user from the platform bot.
/// The composition root resolves `SystemBot` to the canonical `MACRO_SYSTEM_BOT_ID`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub enum HistoricalSender {
/// Raw lowercase-email identity, without roster lookup.
User(MacroUserIdStr<'static>),
/// Fallback for unknown authors, accompanied by `imported_author`.
SystemBot,
}
/// Converted message passed to the atomic historical sink, not the live send path.
#[derive(Debug, Clone, Serialize)]
pub struct HistoricalMessage {
/// Caller-generated UUIDv7; existing source mapping wins across jobs.
pub id: Uuid,
/// Durable source-scoped identity.
pub source: SourceMessageId,
/// Already authorized target channel.
pub channel_id: Uuid,
/// Resolved root message ID, validated as belonging to this target.
pub parent_id: Option<Uuid>,
/// Original thread root time when its parent is absent/skipped; retained as import
/// metadata without promising automatic repair when a later archive supplies it.
pub orphaned_thread_ts: Option<SlackTimestamp>,
/// Lowercase raw-email identity or the system bot.
pub sender: HistoricalSender,
/// Slack display name only for system-bot fallback attribution.
pub imported_author: Option<String>,
/// Converted, nonempty Macro markdown (attachment bytes are excluded).
pub content: String,
/// Only user identities emitted by conversion outside code; never rediscover
/// these by parsing the serialized body.
pub user_mentions: Vec<MacroUserIdStr<'static>>,
/// Typed occurrences against the safe initial content, never speculative IDs.
pub body_references: Vec<super::slack::references::ReferenceIntent>,
/// Deterministic source ordering for equal-time historical display.
pub import_order: u64,
/// Converted, deduplicated reactions with email-bearing actors only.
pub reactions: Vec<HistoricalReaction>,
}
/// One silent historical reaction; source message time supplies missing reaction time.
#[derive(Debug, Clone, Serialize)]
pub struct HistoricalReaction {
/// Raw lowercase email mapped to a Macro identity.
pub user_id: MacroUserIdStr<'static>,
/// Supported Unicode reaction, after shortcode conversion.
pub emoji: String,
/// Original reaction time or its source-message fallback.
pub created_at: SlackTimestamp,
}
/// Unit of atomic persistence across owning-crate transaction helpers.
#[derive(Debug, Clone)]
pub struct HistoricalBatch {
/// Required fencing capability, checked inside the shared transaction.
pub lease: Lease,
/// Bounded by both message count and bytes.
pub messages: Vec<HistoricalMessage>,
/// Resume point committed with the rows and mappings.
pub checkpoint: Checkpoint,
/// Examined records skipped before persistence; sink computes inserts/duplicates/reactions.
pub skipped: u64,
}
/// Durable canonical target reservation state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReservationStatus {
/// Stable candidate allocated, creation/ledger completion still recoverable.
Pending,
/// Canonical target is ready.
Ready,
/// Ambiguous legacy mappings; fail closed rather than choose a target.
Conflict,
}
/// Canonical import-owned target reservation shared with onboarding.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TargetReservation {
/// Bound source namespace owner.
pub team_id: TeamId,
/// Slack natural key; source is Slack, initiator may be onboarding or archive.
pub slack_channel_id: ConversationId,
/// Stable UUIDv7 allocated before idempotent channel creation.
pub channel_id: Uuid,
/// Creation/ledger reconciliation state.
pub status: ReservationStatus,
}
/// Scoped channel indexing request; acceptance alone never means indexing is finished.
#[derive(Debug, Clone)]
pub struct SearchBackfill {
/// Import that owns this indexing attempt.
pub job_id: JobId,
/// Only these authorized imported channels may be enumerated.
pub channel_ids: Vec<Uuid>,
/// Dirty-search generation used to deduplicate retries.
pub generation: u64,
/// Persisted submission state, including the receipt to poll when submitted.
pub state: SearchState,
/// Last submission/state update, used to reconcile stale receipts.
pub updated_at: DateTime<Utc>,
}