//! What the parent needs from Supabase (STORAGE.md §2.2 RPCs and §3.3 Storage calls), behind //! one trait so the job and sweep logic is tested on an in-memory fake and the HTTP //! implementation stays thin. The M6 verification RPCs (V1-2.3) have a trait of their own. use std::fmt; use serde::Deserialize; /// One claimed row of `assets` (`claim_avatar_jobs`). #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct Job { pub asset_id: String, pub owner_id: String, pub bucket_id: String, pub object_key: String, pub quarantine_key: Option, pub lock_token: String, pub attempts: i64, } /// One claimed purge (`claim_purges`). #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct Purge { pub purge_id: String, pub bucket_id: String, pub object_name: String, } /// One quarantine object without a live row (`claim_quarantine_leftovers`). #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct Leftover { pub bucket_id: String, pub object_name: String, pub asset_id: Option, } /// Closed failure kinds of a backend call. `Refused` carries the closed code a `P0001` /// refusal names (`invalid_state`, `invalid_reason`…); every other kind is transport-side. #[derive(Debug, Clone, PartialEq, Eq)] pub enum BackendError { Network(String), Status(u16), Refused(String), Decode(String), /// The downloaded body exceeded the input cap. Overflow, Internal(String), } impl fmt::Display for BackendError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Network(detail) => write!(f, "network: {detail}"), Self::Status(status) => write!(f, "http status {status}"), Self::Refused(code) => write!(f, "refused: {code}"), Self::Decode(detail) => write!(f, "decode: {detail}"), Self::Overflow => f.write_str("body over the cap"), Self::Internal(detail) => write!(f, "internal: {detail}"), } } } impl std::error::Error for BackendError {} impl BackendError { /// Stable name for the `code` log field. pub fn kind(&self) -> &'static str { match self { Self::Network(_) => "network", Self::Status(_) => "status", Self::Refused(_) => "refused", Self::Decode(_) => "decode", Self::Overflow => "overflow", Self::Internal(_) => "internal", } } } pub type BackendResult = Result; /// The eleven operations of STORAGE.md §2.2 and §3.3. pub trait Backend { fn claim_jobs(&self, max_jobs: u32) -> BackendResult>; /// `Status(404)` when the object never landed; `Overflow` past the input cap. fn download_quarantine(&self, bucket: &str, key: &str) -> BackendResult>; /// Upsert of the clean bytes at the final key (idempotent on retry). fn put_clean(&self, bucket: &str, key: &str, bytes: &[u8]) -> BackendResult<()>; fn complete( &self, asset_id: &str, lock_token: &str, byte_size: usize, sha256: &str, ) -> BackendResult<()>; fn reject(&self, asset_id: &str, lock_token: &str, reason: &str) -> BackendResult<()>; /// A missing object counts as deleted. fn delete_object(&self, bucket: &str, key: &str) -> BackendResult<()>; fn mark_quarantine_purged(&self, asset_id: &str) -> BackendResult<()>; fn claim_purges(&self, max_items: u32) -> BackendResult>; fn ack_purge(&self, purge_id: &str) -> BackendResult<()>; fn claim_quarantine_leftovers( &self, older_than_seconds: u64, max_items: u32, ) -> BackendResult>; fn expire_pending_uploads(&self, max_age_seconds: u64) -> BackendResult; } /// One claimed round (`claim_sheet_verifications`, M6). #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct VerifyJob { pub review_id: String, pub version_id: String, pub sheet_id: String, pub revision: u32, pub lease_token: String, pub attempts: i64, } /// One drawing row of a round's input: registered for the sheet, referenced by the document. #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct DrawingRow { pub asset_id: String, pub sha256: String, pub byte_size: u64, pub bucket: String, pub object_key: String, pub uploaded: bool, } /// The input of a leased round (`get_sheet_verification_input`): the texts are passed to /// the child as they are, never parsed by the parent. #[derive(Debug, Clone, Deserialize, PartialEq, Eq)] pub struct VerifyInput { pub review_id: String, pub version_id: String, pub sheet_id: String, pub revision: u32, pub document: String, pub base_document: Option, pub drawings: Vec, } /// `complete_sheet_verification`: `stale` and `malformed` wrote nothing. #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)] #[serde(rename_all = "lowercase")] pub enum CompleteAnswer { Passed, Failed, Stale, Malformed, } /// `fail_sheet_verification`: claimable again, closed `unavailable` at the attempt limit, /// or `stale` (nothing written). #[derive(Debug, Clone, Copy, Deserialize, PartialEq, Eq)] #[serde(rename_all = "lowercase")] pub enum FailAnswer { Retry, Unavailable, Stale, } /// The four RPCs of M6 and the drawing download (V1-2.3, `run --jobs sheet-verify`). pub trait VerifyBackend { fn claim_verifications(&self, max_jobs: u32) -> BackendResult>; /// `None` when the lease or the round is stale. fn verification_input( &self, review_id: &str, lease_token: &str, ) -> BackendResult>; /// `Status(404)` when the object is missing; `Overflow` past `max_bytes`. fn download_drawing(&self, bucket: &str, key: &str, max_bytes: usize) -> BackendResult>; /// `verdict` is the child's output, a JSON object. fn complete_verification( &self, review_id: &str, lease_token: &str, verdict: &[u8], ) -> BackendResult; /// `code` is one of the closed worker codes (`verify_job::codes`). fn fail_verification( &self, review_id: &str, lease_token: &str, code: &str, ) -> BackendResult; }