Files
faunosteo/crates/worker/src/backend.rs
T

191 lines
6.3 KiB
Rust

//! 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<String>,
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<String>,
}
/// 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<T> = Result<T, BackendError>;
/// The eleven operations of STORAGE.md §2.2 and §3.3.
pub trait Backend {
fn claim_jobs(&self, max_jobs: u32) -> BackendResult<Vec<Job>>;
/// `Status(404)` when the object never landed; `Overflow` past the input cap.
fn download_quarantine(&self, bucket: &str, key: &str) -> BackendResult<Vec<u8>>;
/// 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<Vec<Purge>>;
fn ack_purge(&self, purge_id: &str) -> BackendResult<()>;
fn claim_quarantine_leftovers(
&self,
older_than_seconds: u64,
max_items: u32,
) -> BackendResult<Vec<Leftover>>;
fn expire_pending_uploads(&self, max_age_seconds: u64) -> BackendResult<i64>;
}
/// 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<String>,
pub drawings: Vec<DrawingRow>,
}
/// `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<Vec<VerifyJob>>;
/// `None` when the lease or the round is stale.
fn verification_input(
&self,
review_id: &str,
lease_token: &str,
) -> BackendResult<Option<VerifyInput>>;
/// `Status(404)` when the object is missing; `Overflow` past `max_bytes`.
fn download_drawing(&self, bucket: &str, key: &str, max_bytes: usize)
-> BackendResult<Vec<u8>>;
/// `verdict` is the child's output, a JSON object.
fn complete_verification(
&self,
review_id: &str,
lease_token: &str,
verdict: &[u8],
) -> BackendResult<CompleteAnswer>;
/// `code` is one of the closed worker codes (`verify_job::codes`).
fn fail_verification(
&self,
review_id: &str,
lease_token: &str,
code: &str,
) -> BackendResult<FailAnswer>;
}