//! Durable attempt, retry-snapshot and cancellation vocabulary of a Task (Story 4.4). use serde::{Deserialize, Serialize}; use super::{TASK_IDENTITY_MAX_BYTES, TaskAccess, TaskEnvelope, TaskError, TaskId, TaskRecord}; /// Upper bound of the retry budget a Task may pin at acceptance (Story 4.4). pub const TASK_MAX_ATTEMPTS: u32 = 5; /// Upper bound of the pinned backoff step between two durable attempts (Story 4.4). pub const TASK_MAX_BACKOFF_STEP_MS: i64 = 1_000; /// Bound of a stored cancellation reason. pub const TASK_CANCEL_REASON_MAX_BYTES: usize = 160; /// Immutable retry snapshot of one accepted Task. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct TaskRetryPolicy { /// Total durable outbound attempts (1 = a single attempt, never retried). pub max_attempts: u32, /// Pinned base backoff between two attempts; the delay grows by this step per attempt. pub backoff_step_ms: i64, } impl TaskRetryPolicy { /// A Task that may be dispatched exactly once (legacy Tasks and unverified writes). pub const fn single_attempt() -> Self { Self { max_attempts: 1, backoff_step_ms: 0, } } pub fn new(max_attempts: u32, backoff_step_ms: i64) -> Self { Self { max_attempts, backoff_step_ms, } } pub fn validate(&self) -> Result<(), TaskError> { if !(1..=TASK_MAX_ATTEMPTS).contains(&self.max_attempts) { return Err(TaskError::invalid("task retry budget is invalid")); } if !(0..=TASK_MAX_BACKOFF_STEP_MS).contains(&self.backoff_step_ms) { return Err(TaskError::invalid("task retry backoff is invalid")); } Ok(()) } /// Delay before attempt number `next_ordinal` (2..=max_attempts), capped so a pinned snapshot can /// never stretch the accepted execution deadline on its own. pub fn backoff_before(&self, next_ordinal: u32) -> i64 { let steps = i64::from(next_ordinal.saturating_sub(1)).max(1); self.backoff_step_ms .saturating_mul(steps) .min(self.backoff_step_ms.saturating_mul(4)) } } /// Certainty of one durable attempt outcome. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum AttemptCertainty { /// The outcome of the outbound operation is proven (success or a definite failure). Known, /// The operation may have been applied upstream; the effect cannot be proven locally. Unknown, } impl AttemptCertainty { pub const fn as_str(self) -> &'static str { match self { Self::Known => "known", Self::Unknown => "unknown", } } pub fn parse(value: &str) -> Result { match value { "known" => Ok(Self::Known), "unknown" => Ok(Self::Unknown), _ => Err(TaskError::invalid("unknown attempt certainty")), } } } /// Phase of one durable attempt at the moment it was resolved. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum AttemptPhase { /// The durable checkpoint exists but no outbound send was observed. BeforeDispatch, /// The request was handed to the transport; its effect may exist upstream. Dispatched, } impl AttemptPhase { pub const fn as_str(self) -> &'static str { match self { Self::BeforeDispatch => "before_dispatch", Self::Dispatched => "dispatched", } } pub fn parse(value: &str) -> Result { match value { "before_dispatch" => Ok(Self::BeforeDispatch), "dispatched" => Ok(Self::Dispatched), _ => Err(TaskError::invalid("unknown attempt phase")), } } } /// Closed outcome vocabulary of one resolved attempt. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum AttemptOutcomeClass { Completed, Failed, /// A bounded further attempt was scheduled instead of a terminal outcome. RetryScheduled, OutcomeUnknown, } impl AttemptOutcomeClass { pub const fn as_str(self) -> &'static str { match self { Self::Completed => "completed", Self::Failed => "failed", Self::RetryScheduled => "retry_scheduled", Self::OutcomeUnknown => "outcome_unknown", } } pub fn parse(value: &str) -> Result { match value { "completed" => Ok(Self::Completed), "failed" => Ok(Self::Failed), "retry_scheduled" => Ok(Self::RetryScheduled), "outcome_unknown" => Ok(Self::OutcomeUnknown), _ => Err(TaskError::invalid("unknown attempt outcome")), } } } /// One durable outbound attempt. The row is created by the dispatch checkpoint before any network /// use and becomes immutable once resolved, so a stale worker can never append to the history. #[derive(Clone, Debug, PartialEq, Eq)] pub struct TaskAttempt { pub attempt_id: String, pub task_id: TaskId, pub ordinal: u32, pub owner: String, pub fence: u64, /// Canonical fingerprint of the sealed executable input this attempt was admitted for. pub input_fingerprint: String, /// Digest of the stable upstream idempotency key (never the raw key or headers). pub upstream_key_digest: Option, /// Whether a retry of this attempt is safe (read or server-verified idempotent write). pub retry_allowed: bool, pub checkpoint_at_unix_ms: i64, pub resolved_at_unix_ms: Option, pub outcome: Option, pub certainty: Option, pub phase: Option, } /// Committed dispatch intent of one durable attempt (Story 4.4). The store owns the transaction: the /// attempt row, the incremented budget and the new Task version commit together before the network is /// touched, so an uncommitted checkpoint can never produce an outbound call. #[derive(Clone, Debug, PartialEq, Eq)] pub struct BeginAttempt { pub task_id: TaskId, pub owner: String, pub fence: u64, /// Version the worker read from the lease; a concurrent change rejects the checkpoint. pub expected_version: u32, pub attempt_id: String, pub input_fingerprint: String, pub upstream_key_digest: Option, /// The runtime's decision that a retry of this attempt is safe; the store still enforces the /// pinned budget and the absolute deadline. pub retry_allowed: bool, } impl BeginAttempt { pub fn validate(&self) -> Result<(), TaskError> { if self.owner.is_empty() || self.owner.len() > TASK_IDENTITY_MAX_BYTES { return Err(TaskError::invalid("task attempt owner is invalid")); } if self.attempt_id.is_empty() || self.attempt_id.len() > TASK_IDENTITY_MAX_BYTES { return Err(TaskError::invalid("task attempt identity is invalid")); } if self.input_fingerprint.len() != 64 { return Err(TaskError::invalid("task attempt fingerprint is invalid")); } if let Some(digest) = self.upstream_key_digest.as_deref() && (digest.is_empty() || digest.len() > TASK_IDENTITY_MAX_BYTES) { return Err(TaskError::invalid( "task attempt upstream key digest is invalid", )); } Ok(()) } } /// Leased, committed view of one in-flight attempt and the Task version it was admitted under. #[derive(Clone, Debug, PartialEq)] pub struct AttemptLease { pub attempt: TaskAttempt, pub task: TaskRecord, } /// Typed outcome of one attempt, handed to the store for a single atomic resolution. #[derive(Clone, Debug, PartialEq, Eq)] pub enum AttemptOutcome { /// Proven success; the Task becomes `completed` with this result. Completed(TaskEnvelope), /// Proven failure. `retryable` only schedules another attempt when the store's pinned budget, /// the attempt's safe-retry decision and the absolute deadline all still allow it; otherwise the /// Task fails with this error. Failed { error: TaskEnvelope, retryable: bool, phase: AttemptPhase, }, /// The outbound effect cannot be proven. `repeatable` only schedules another bounded attempt when /// repeating it is safe and the pinned budget/deadline still allow it; otherwise the Task becomes /// the non-terminal `outcome_unknown`, never a plain failure. Uncertain { error: TaskEnvelope, repeatable: bool, phase: AttemptPhase, }, } /// Single-winner result of resolving one attempt. #[derive(Clone, Debug, PartialEq)] pub enum AttemptResolution { /// A terminal transition committed (completed or failed). Finished(TaskRecord), /// The attempt failed in a known way and another bounded attempt was armed. RetryAt { task: TaskRecord, next_attempt_at_unix_ms: i64, }, /// The attempt resolved to the non-terminal uncertain state. Unknown(TaskRecord), } /// Owner-side cancellation request. `expected_version` is optional so a repeated cancel of the same /// accepted Task stays idempotent while a stale version is reported as a conflict. #[derive(Clone, Debug, PartialEq, Eq)] pub struct TaskCancelRequest { pub access: TaskAccess, pub task_id: TaskId, pub expected_version: Option, pub reason: String, } impl TaskCancelRequest { pub fn validate(&self) -> Result<(), TaskError> { self.access.validate()?; if self.reason.is_empty() || self.reason.len() > TASK_CANCEL_REASON_MAX_BYTES || self.reason.bytes().any(|byte| byte.is_ascii_control()) { return Err(TaskError::invalid("task cancellation reason is invalid")); } Ok(()) } } /// Typed result of an owner-scoped cancellation. #[derive(Clone, Debug, PartialEq)] pub enum TaskCancelOutcome { /// Cancelled before the dispatch checkpoint: no outbound call can have happened. Cancelled(TaskRecord), /// The Task already had a checkpointed attempt: non-terminal uncertain, never a plain cancel. OutcomeUnknown(TaskRecord), /// The Task was already in a terminal state; its accepted result is unchanged. AlreadyTerminal(TaskRecord), /// The caller's expected version is stale; `current` is the authorized current state. Conflict(TaskRecord), }