feat(artifacts): add fenced reconciliation recovery

This commit is contained in:
bsodfather committed 2026-08-28 00:44:27 +03:00
1 parent 8784964fb2
commit d2849ea3fe
21 files changed
+3322 -97

No files matched your search

@@ -3,19 +3,373 @@ use crank_core::WorkspaceId;
use sqlx::{Postgres, Row, Transaction, postgres::PgRow};
use crate::{
ArtifactBlobLifecycle, ArtifactBlobRecord, ArtifactDigest, ArtifactSourceCursor,
ArtifactBlobLifecycle, ArtifactBlobRecord, ArtifactClaimFinalization,
ArtifactClaimFinalizeOutcome, ArtifactClaimOutcome, ArtifactClaimRecheckOutcome,
ArtifactDigest, ArtifactExpiredClaimProbe, ArtifactReconciliationClaim, ArtifactSourceCursor,
ArtifactSourceId, ArtifactSourceLifecycle, ArtifactSourcePage, ArtifactSourceRecord,
ArtifactSourceSensitivity, CreateArtifactSourceRequest, DetachArtifactSourceRequest,
ListArtifactSourcesQuery, MAX_ARTIFACT_SOURCE_PAGE_SIZE, RegistryError, VerifiedArtifactSource,
ArtifactSourceSensitivity, ClaimArtifactReconciliationRequest,
ClaimExpiredArtifactReconciliationRequest, CreateArtifactSourceRequest,
DetachArtifactSourceRequest, ListArtifactSourcesQuery, MAX_ARTIFACT_CLAIM_RECOVERY_BATCH,
MAX_ARTIFACT_SOURCE_PAGE_SIZE, RegistryError, VerifiedArtifactSource,
};
use super::PostgresRegistry;
mod reconciliation;
use reconciliation::{
checked_cutoff, database_now, insert_blob_if_missing_at_database_time, validate_claim_lease,
};
const SOURCE_ID_PREFIX: &str = "src_";
const MAX_SOURCE_ID_SUFFIX_BYTES: usize = 128;
const MAX_MIME_TYPE_BYTES: usize = 255;
impl PostgresRegistry {
/// Acquires a short, fenced reconciliation lease after checking references
/// across every workspace. A lease may be replayed by its original token,
/// or stolen only after expiry.
pub async fn claim_artifact_reconciliation(
&self,
request: ClaimArtifactReconciliationRequest<'_>,
) -> Result<ArtifactClaimOutcome, RegistryError> {
let lease_duration = validate_claim_lease(request.claimed_at, request.lease_expires_at)?;
if request.detached_grace.is_negative() {
return Err(RegistryError::InvalidArtifactSource {
field: "detached_grace",
});
}
if !valid_artifact_size(request.artifact.size_bytes()) {
return Err(RegistryError::InvalidArtifactSource {
field: "size_bytes",
});
}
let mut transaction = self.pool().begin().await?;
let artifact_ref = request.artifact.artifact_ref();
let size_bytes = i64::try_from(request.artifact.size_bytes()).map_err(|_| {
RegistryError::InvalidArtifactSource {
field: "size_bytes",
}
})?;
insert_blob_if_missing_at_database_time(&mut transaction, artifact_ref, size_bytes).await?;
let row = lock_blob(&mut transaction, artifact_ref.digest_hex()).await?;
let database_now = database_now(&mut transaction).await?;
if !blob_metadata_matches(&row, artifact_ref, size_bytes)? {
transaction.rollback().await?;
return Ok(ArtifactClaimOutcome::MetadataConflict);
}
if global_active_reference(&mut transaction, artifact_ref.digest_hex()).await? {
transaction.rollback().await?;
return Ok(ArtifactClaimOutcome::ActiveReference);
}
if global_detached_reference_in_grace(
&mut transaction,
artifact_ref.digest_hex(),
checked_cutoff(database_now, request.detached_grace)?,
)
.await?
{
transaction.rollback().await?;
return Ok(ArtifactClaimOutcome::DetachedReferenceInGrace);
}
let claim_token = row.try_get::<Option<String>, _>("claim_token")?;
let claim_expires_at =
row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
if let (Some(current_token), Some(expires_at)) = (claim_token, claim_expires_at) {
if current_token == request.token.as_str() && expires_at > database_now {
transaction.commit().await?;
return Ok(ArtifactClaimOutcome::Claimed(
ArtifactReconciliationClaim::new(artifact_ref.clone(), request.token),
));
}
if expires_at > database_now || current_token == request.token.as_str() {
transaction.rollback().await?;
return Ok(ArtifactClaimOutcome::HeldByOther);
}
}
let updated = sqlx::query(
"update artifact_blobs
set claim_token = $1, claim_expires_at = $2, updated_at = greatest(updated_at, $3)
where digest = $4",
)
.bind(request.token.as_str())
.bind(database_now + lease_duration)
.bind(database_now)
.bind(artifact_ref.digest_hex())
.execute(&mut *transaction)
.await?
.rows_affected();
debug_assert_eq!(updated, 1);
transaction.commit().await?;
Ok(ArtifactClaimOutcome::Claimed(
ArtifactReconciliationClaim::new(artifact_ref.clone(), request.token),
))
}
/// Reads a bounded set of expired claims without taking their leases.
///
/// Recovery first probes physical presence through the artifact store. Only
/// a confirmed absence should call `claim_expired_artifact_reconciliation`.
/// Leaving final or quarantine entries untouched lets the ordinary scanner
/// reclaim them with a store-validated `RegisteredArtifact`.
pub async fn list_expired_artifact_reconciliation_probes(
&self,
now: time::OffsetDateTime,
limit: u32,
) -> Result<Vec<ArtifactExpiredClaimProbe>, RegistryError> {
self.list_expired_artifact_reconciliation_probes_after(now, None, limit)
.await
}
/// Continues the bounded expired-claim read after an opaque prior probe.
///
/// Keyset pagination prevents an unsafe or still-present first claim from
/// starving later absent claims without persisting worker state in V12.
pub async fn list_expired_artifact_reconciliation_probes_after(
&self,
now: time::OffsetDateTime,
after: Option<&ArtifactExpiredClaimProbe>,
limit: u32,
) -> Result<Vec<ArtifactExpiredClaimProbe>, RegistryError> {
let limit = limit.min(MAX_ARTIFACT_CLAIM_RECOVERY_BATCH);
if limit == 0 {
return Ok(Vec::new());
}
let after_expires_at = after.map(ArtifactExpiredClaimProbe::claim_expires_at);
let after_digest = after.map(|probe| probe.artifact_ref().digest_hex());
let rows = sqlx::query(
"select artifact_ref, claim_token, claim_expires_at
from artifact_blobs
where claim_token is not null
and claim_expires_at <= $1
and (
$2::timestamptz is null
or (claim_expires_at, digest) > ($2::timestamptz, $3::text)
)
order by claim_expires_at asc, digest asc
limit $4",
)
.bind(now)
.bind(after_expires_at)
.bind(after_digest)
.bind(i64::from(limit))
.fetch_all(self.pool())
.await?;
rows.into_iter()
.map(|row| {
let artifact_ref = ArtifactRef::parse(&row.try_get::<String, _>("artifact_ref")?)
.map_err(|_| RegistryError::InvalidArtifactSource {
field: "artifact_ref",
})?;
let prior_token = row.try_get::<Option<String>, _>("claim_token")?.ok_or(
RegistryError::InvalidArtifactSource {
field: "claim_token",
},
)?;
let claim_expires_at = row
.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?
.ok_or(RegistryError::InvalidArtifactSource {
field: "claim_expires_at",
})?;
Ok(ArtifactExpiredClaimProbe::new(
artifact_ref,
prior_token,
claim_expires_at,
))
})
.collect()
}
/// Compare-and-swap steals an expired probe after recovery observed absence.
///
/// The caller must probe physical state again after a successful claim: a
/// concurrent scanner may have changed the inode between the read and CAS.
pub async fn claim_expired_artifact_reconciliation(
&self,
probe: &ArtifactExpiredClaimProbe,
request: ClaimExpiredArtifactReconciliationRequest,
) -> Result<Option<ArtifactReconciliationClaim>, RegistryError> {
let lease_duration = validate_claim_lease(request.claimed_at, request.lease_expires_at)?;
if request.token.as_str() == probe.prior_token() {
return Err(RegistryError::InvalidArtifactSource {
field: "claim_token",
});
}
let mut transaction = self.pool().begin().await?;
let Some(row) =
lock_blob_optional(&mut transaction, probe.artifact_ref().digest_hex()).await?
else {
transaction.rollback().await?;
return Ok(None);
};
let database_now = database_now(&mut transaction).await?;
let current_token = row.try_get::<Option<String>, _>("claim_token")?;
let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
if current_token.as_deref() != Some(probe.prior_token())
|| expires_at.is_none_or(|value| value > database_now)
{
transaction.rollback().await?;
return Ok(None);
}
let claimed = sqlx::query(
"update artifact_blobs
set claim_token = $1,
claim_expires_at = $2,
updated_at = greatest(updated_at, $3)
where digest = $4
and claim_token = $5
and claim_expires_at <= $3",
)
.bind(request.token.as_str())
.bind(database_now + lease_duration)
.bind(database_now)
.bind(probe.artifact_ref().digest_hex())
.bind(probe.prior_token())
.execute(&mut *transaction)
.await?
.rows_affected()
== 1;
transaction.commit().await?;
Ok(claimed
.then(|| ArtifactReconciliationClaim::new(probe.artifact_ref().clone(), request.token)))
}
/// Rechecks an owned claim immediately before blocking filesystem I/O.
///
/// `create_artifact_source` holds the same blob lock and rejects any active
/// claim, so a `Mutate` outcome fences the recheck-to-filesystem window.
pub async fn recheck_artifact_reconciliation_claim(
&self,
claim: &ArtifactReconciliationClaim,
_now: time::OffsetDateTime,
detached_grace: time::Duration,
) -> Result<ArtifactClaimRecheckOutcome, RegistryError> {
if detached_grace.is_negative() {
return Err(RegistryError::InvalidArtifactSource {
field: "detached_grace",
});
}
let mut transaction = self.pool().begin().await?;
let Some(row) =
lock_blob_optional(&mut transaction, claim.artifact_ref().digest_hex()).await?
else {
transaction.rollback().await?;
return Ok(ArtifactClaimRecheckOutcome::Stale);
};
let database_now = database_now(&mut transaction).await?;
let current_token = row.try_get::<Option<String>, _>("claim_token")?;
let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
if current_token.as_deref() != Some(claim.token().as_str())
|| expires_at.is_none_or(|value| value <= database_now)
{
transaction.rollback().await?;
return Ok(ArtifactClaimRecheckOutcome::Stale);
}
if global_active_reference(&mut transaction, claim.artifact_ref().digest_hex()).await? {
transaction.commit().await?;
return Ok(ArtifactClaimRecheckOutcome::ActiveReference);
}
if global_detached_reference_in_grace(
&mut transaction,
claim.artifact_ref().digest_hex(),
checked_cutoff(database_now, detached_grace)?,
)
.await?
{
transaction.commit().await?;
return Ok(ArtifactClaimRecheckOutcome::DetachedReferenceInGrace);
}
transaction.commit().await?;
Ok(ArtifactClaimRecheckOutcome::Mutate)
}
/// Records a filesystem observation without performing filesystem I/O.
///
/// Only confirmed absence clears the claim and transitions V12 metadata to
/// `unavailable`; every ambiguous observation deliberately retains it for
/// a later bounded recovery attempt.
pub async fn finalize_artifact_reconciliation_claim(
&self,
claim: &ArtifactReconciliationClaim,
observation: ArtifactClaimFinalization,
_observed_at: time::OffsetDateTime,
) -> Result<ArtifactClaimFinalizeOutcome, RegistryError> {
let mut transaction = self.pool().begin().await?;
let Some(row) =
lock_blob_optional(&mut transaction, claim.artifact_ref().digest_hex()).await?
else {
transaction.rollback().await?;
return Ok(ArtifactClaimFinalizeOutcome::Stale);
};
let database_now = database_now(&mut transaction).await?;
let current_token = row.try_get::<Option<String>, _>("claim_token")?;
let expires_at = row.try_get::<Option<time::OffsetDateTime>, _>("claim_expires_at")?;
if current_token.as_deref() != Some(claim.token().as_str())
|| expires_at.is_none_or(|value| value <= database_now)
{
transaction.rollback().await?;
return Ok(ArtifactClaimFinalizeOutcome::Stale);
}
let (lifecycle, clear_claim, outcome) = match observation {
ArtifactClaimFinalization::Deleted | ArtifactClaimFinalization::AlreadyAbsent => (
"unavailable",
true,
ArtifactClaimFinalizeOutcome::Unavailable,
),
ArtifactClaimFinalization::Quarantined | ArtifactClaimFinalization::Retryable => {
("available", false, ArtifactClaimFinalizeOutcome::Retained)
}
};
let updated = if clear_claim {
sqlx::query(
"update artifact_blobs
set storage_lifecycle = $1, claim_token = null, claim_expires_at = null,
updated_at = greatest(updated_at, $2)
where digest = $3 and claim_token = $4 and claim_expires_at > $2",
)
.bind(lifecycle)
.bind(database_now)
.bind(claim.artifact_ref().digest_hex())
.bind(claim.token().as_str())
.execute(&mut *transaction)
.await?
.rows_affected()
} else {
sqlx::query(
"update artifact_blobs
set updated_at = greatest(updated_at, $1)
where digest = $2 and claim_token = $3 and claim_expires_at > $1",
)
.bind(database_now)
.bind(claim.artifact_ref().digest_hex())
.bind(claim.token().as_str())
.execute(&mut *transaction)
.await?
.rows_affected()
};
if updated != 1 {
transaction.rollback().await?;
return Ok(ArtifactClaimFinalizeOutcome::Stale);
}
transaction.commit().await?;
Ok(outcome)
}
/// Alias used by startup recovery once its filesystem probe has produced a
/// typed observation. The registry never performs the probe itself.
pub async fn recover_artifact_reconciliation_claim(
&self,
claim: &ArtifactReconciliationClaim,
observation: ArtifactClaimFinalization,
recovered_at: time::OffsetDateTime,
) -> Result<ArtifactClaimFinalizeOutcome, RegistryError> {
self.finalize_artifact_reconciliation_claim(claim, observation, recovered_at)
.await
}
pub async fn create_artifact_source(
&self,
request: CreateArtifactSourceRequest<'_>,
@@ -254,6 +608,41 @@ async fn ensure_blob(
field: "size_bytes",
}
})?;
insert_blob_if_missing(
transaction,
request.artifact.artifact_ref(),
size_bytes,
request.created_at,
)
.await?;
let row = lock_blob(transaction, digest).await?;
if !blob_metadata_matches(&row, request.artifact.artifact_ref(), size_bytes)? {
return Err(source_conflict(request.source_id));
}
if row.try_get::<Option<String>, _>("claim_token")?.is_some() {
return Err(RegistryError::ArtifactClaimInProgress);
}
if row.try_get::<String, _>("storage_lifecycle")? == "unavailable" {
sqlx::query(
"update artifact_blobs
set storage_lifecycle = 'available', updated_at = greatest(updated_at, $1)
where digest = $2 and claim_token is null",
)
.bind(request.created_at)
.bind(digest)
.execute(&mut **transaction)
.await?;
}
Ok(())
}
async fn insert_blob_if_missing(
transaction: &mut Transaction<'_, Postgres>,
artifact_ref: &ArtifactRef,
size_bytes: i64,
created_at: time::OffsetDateTime,
) -> Result<(), RegistryError> {
sqlx::query(
"insert into artifact_blobs (
digest, artifact_ref, size_bytes, storage_lifecycle,
@@ -261,25 +650,87 @@ async fn ensure_blob(
) values ($1, $2, $3, 'available', null, null, $4, $4)
on conflict (digest) do nothing",
)
.bind(digest)
.bind(request.artifact.artifact_ref().as_str())
.bind(artifact_ref.digest_hex())
.bind(artifact_ref.as_str())
.bind(size_bytes)
.bind(request.created_at)
.bind(created_at)
.execute(&mut **transaction)
.await?;
Ok(())
}
let row = sqlx::query(
"select artifact_ref, size_bytes from artifact_blobs where digest = $1 for update",
async fn lock_blob(
transaction: &mut Transaction<'_, Postgres>,
digest: &str,
) -> Result<PgRow, RegistryError> {
lock_blob_optional(transaction, digest)
.await?
.ok_or(RegistryError::InvalidArtifactSource {
field: "artifact_blob",
})
}
async fn lock_blob_optional(
transaction: &mut Transaction<'_, Postgres>,
digest: &str,
) -> Result<Option<PgRow>, RegistryError> {
sqlx::query(
"select artifact_ref, size_bytes, storage_lifecycle, claim_token, claim_expires_at
from artifact_blobs
where digest = $1
for update",
)
.bind(digest)
.fetch_optional(&mut **transaction)
.await
.map_err(Into::into)
}
fn blob_metadata_matches(
row: &PgRow,
artifact_ref: &ArtifactRef,
size_bytes: i64,
) -> Result<bool, RegistryError> {
Ok(
row.try_get::<String, _>("artifact_ref")? == artifact_ref.as_str()
&& row.try_get::<i64, _>("size_bytes")? == size_bytes,
)
}
async fn global_active_reference(
transaction: &mut Transaction<'_, Postgres>,
digest: &str,
) -> Result<bool, RegistryError> {
sqlx::query_scalar::<_, bool>(
"select exists(
select 1 from artifact_sources
where blob_digest = $1 and lifecycle = 'active'
)",
)
.bind(digest)
.fetch_one(&mut **transaction)
.await?;
let recorded_ref = row.try_get::<String, _>("artifact_ref")?;
let recorded_size = row.try_get::<i64, _>("size_bytes")?;
if recorded_ref != request.artifact.artifact_ref().as_str() || recorded_size != size_bytes {
return Err(source_conflict(request.source_id));
}
Ok(())
.await
.map_err(Into::into)
}
async fn global_detached_reference_in_grace(
transaction: &mut Transaction<'_, Postgres>,
digest: &str,
detached_after: time::OffsetDateTime,
) -> Result<bool, RegistryError> {
sqlx::query_scalar::<_, bool>(
"select exists(
select 1 from artifact_sources
where blob_digest = $1
and lifecycle = 'detached'
and detached_at > $2
)",
)
.bind(digest)
.bind(detached_after)
.fetch_one(&mut **transaction)
.await
.map_err(Into::into)
}
async fn get_source_in_transaction(
@@ -0,0 +1,68 @@
use crank_artifacts::ArtifactRef;
use sqlx::{Postgres, Transaction};
use crate::{PostgresRegistry, RegistryError};
const MAX_ARTIFACT_CLAIM_LEASE: time::Duration = time::Duration::minutes(5);
impl PostgresRegistry {
/// Returns the PostgreSQL clock used by production reconciliation leases.
pub async fn artifact_reconciliation_now(&self) -> Result<time::OffsetDateTime, RegistryError> {
sqlx::query_scalar("select clock_timestamp()")
.fetch_one(self.pool())
.await
.map_err(RegistryError::from)
}
}
pub(super) async fn insert_blob_if_missing_at_database_time(
transaction: &mut Transaction<'_, Postgres>,
artifact_ref: &ArtifactRef,
size_bytes: i64,
) -> Result<(), RegistryError> {
sqlx::query(
"insert into artifact_blobs (
digest, artifact_ref, size_bytes, storage_lifecycle,
claim_token, claim_expires_at, created_at, updated_at
) values ($1, $2, $3, 'available', null, null, clock_timestamp(), clock_timestamp())
on conflict (digest) do nothing",
)
.bind(artifact_ref.digest_hex())
.bind(artifact_ref.as_str())
.bind(size_bytes)
.execute(&mut **transaction)
.await?;
Ok(())
}
pub(super) fn validate_claim_lease(
claimed_at: time::OffsetDateTime,
lease_expires_at: time::OffsetDateTime,
) -> Result<time::Duration, RegistryError> {
let duration = lease_expires_at - claimed_at;
if duration <= time::Duration::ZERO || duration > MAX_ARTIFACT_CLAIM_LEASE {
return Err(RegistryError::InvalidArtifactSource {
field: "claim_lease",
});
}
Ok(duration)
}
pub(super) fn checked_cutoff(
now: time::OffsetDateTime,
grace: time::Duration,
) -> Result<time::OffsetDateTime, RegistryError> {
now.checked_sub(grace)
.ok_or(RegistryError::InvalidArtifactSource {
field: "detached_grace",
})
}
pub(super) async fn database_now(
transaction: &mut Transaction<'_, Postgres>,
) -> Result<time::OffsetDateTime, RegistryError> {
sqlx::query_scalar("select clock_timestamp()")
.fetch_one(&mut **transaction)
.await
.map_err(Into::into)
}