commit 690380d80d777c3e03f2f6e04859685c6732f061 parent 2607ef68fecbdbb2ead383cdee78d1adbd35de89 Author: triesap <tyson@radroots.org> Date: Fri, 2 Oct 2026 14:59:25 +0000 availability: define discovery outcomes and typed errors - Preserve independent bounded source progress and valid retained results - Serialize finite safe metadata without private items or remote messages - Map static availability failures through the additive native contract - Verify frozen behavioral cases and current Rust Kotlin and graph proofs Diffstat:
20 files changed, 2104 insertions(+), 14 deletions(-)
diff --git a/app/desktop/src/main/kotlin/org/harvestcircle/application/NativeRuntimeMappings.kt b/app/desktop/src/main/kotlin/org/harvestcircle/application/NativeRuntimeMappings.kt @@ -247,6 +247,12 @@ internal fun WireErrorCode.toApplicationErrorCode(): ApplicationErrorCode = WireErrorCode.NATIVE_LIBRARY_LOAD_FAILED -> ApplicationErrorCode.NativeLibraryLoadFailed WireErrorCode.COMPATIBILITY_MISMATCH -> ApplicationErrorCode.CompatibilityMismatch WireErrorCode.INTERNAL -> ApplicationErrorCode.Internal + WireErrorCode.AVAILABILITY_INVALID_INPUT -> ApplicationErrorCode.AvailabilityInvalidInput + WireErrorCode.AVAILABILITY_UNSUPPORTED_PROFILE -> ApplicationErrorCode.AvailabilityUnsupportedProfile + WireErrorCode.AVAILABILITY_SCOPE_MISMATCH -> ApplicationErrorCode.AvailabilityScopeMismatch + WireErrorCode.AVAILABILITY_STALE_QUERY -> ApplicationErrorCode.AvailabilityStaleQuery + WireErrorCode.AVAILABILITY_CAPACITY -> ApplicationErrorCode.AvailabilityCapacity + WireErrorCode.AVAILABILITY_UNAVAILABLE -> ApplicationErrorCode.AvailabilityUnavailable } internal fun WireErrorCategory.toApplicationErrorCategory(): ApplicationErrorCategory = diff --git a/app/desktop/src/test/kotlin/org/harvestcircle/application/NativeRuntimeMappingsTest.kt b/app/desktop/src/test/kotlin/org/harvestcircle/application/NativeRuntimeMappingsTest.kt @@ -255,7 +255,7 @@ class NativeRuntimeMappingsTest { .size, ) assertEquals( - 23, + 29, WireErrorCode.entries .map(WireErrorCode::toApplicationErrorCode) .distinct() @@ -278,6 +278,110 @@ class NativeRuntimeMappingsTest { } @Test + fun availabilityErrorsPreserveDistinctCodesAndStaticRecovery() { + data class ExpectedError( + val wireCode: String, + val applicationCode: String, + val wireCategory: WireErrorCategory, + val applicationCategory: ApplicationErrorCategory, + val retryable: Boolean, + val wireRecovery: WireRecoveryAction, + val applicationRecovery: RecoveryAction, + val message: String, + ) + + val cases = + listOf( + ExpectedError( + "AVAILABILITY_INVALID_INPUT", + "AvailabilityInvalidInput", + WireErrorCategory.INPUT, + ApplicationErrorCategory.Input, + false, + WireRecoveryAction.NONE, + RecoveryAction.None, + "The availability request is invalid.", + ), + ExpectedError( + "AVAILABILITY_UNSUPPORTED_PROFILE", + "AvailabilityUnsupportedProfile", + WireErrorCategory.COMPATIBILITY, + ApplicationErrorCategory.Compatibility, + false, + WireRecoveryAction.NONE, + RecoveryAction.None, + "This availability profile is unsupported.", + ), + ExpectedError( + "AVAILABILITY_SCOPE_MISMATCH", + "AvailabilityScopeMismatch", + WireErrorCategory.CONFLICT, + ApplicationErrorCategory.Conflict, + false, + WireRecoveryAction.NONE, + RecoveryAction.None, + "The availability request belongs to another scope.", + ), + ExpectedError( + "AVAILABILITY_STALE_QUERY", + "AvailabilityStaleQuery", + WireErrorCategory.CONFLICT, + ApplicationErrorCategory.Conflict, + false, + WireRecoveryAction.NONE, + RecoveryAction.None, + "The availability query is stale.", + ), + ExpectedError( + "AVAILABILITY_CAPACITY", + "AvailabilityCapacity", + WireErrorCategory.LIFECYCLE, + ApplicationErrorCategory.Lifecycle, + true, + WireRecoveryAction.RETRY, + RecoveryAction.Retry, + "The availability operation reached its capacity.", + ), + ExpectedError( + "AVAILABILITY_UNAVAILABLE", + "AvailabilityUnavailable", + WireErrorCategory.NETWORK, + ApplicationErrorCategory.Network, + true, + WireRecoveryAction.RETRY, + RecoveryAction.Retry, + "Availability discovery is unavailable.", + ), + ) + + assertEquals(22, WireErrorCode.INTERNAL.ordinal) + assertEquals(22, ApplicationErrorCode.Internal.ordinal) + cases.forEachIndexed { index, expected -> + val wireCode = WireErrorCode.valueOf(expected.wireCode) + val applicationCode = ApplicationErrorCode.valueOf(expected.applicationCode) + val problem = + SafeErrorDto( + code = wireCode, + category = expected.wireCategory, + retryable = expected.retryable, + recoveryAction = expected.wireRecovery, + message = expected.message, + ).toApplicationProblem() + + assertEquals(23 + index, wireCode.ordinal) + assertEquals(23 + index, applicationCode.ordinal) + assertEquals(applicationCode, problem.code) + assertEquals(expected.applicationCategory, problem.category) + assertEquals(expected.retryable, problem.retryable) + assertEquals(expected.applicationRecovery, problem.recoveryAction) + assertEquals(expected.message, problem.safeMessage) + assertNull(problem.operationId) + assertFalse(problem.toString().contains("HCAV_PRIVATE_REMOTE_PAYLOAD")) + } + assertEquals(6, cases.map { WireErrorCode.valueOf(it.wireCode).toApplicationErrorCode() }.distinct().size) + } + + @Test fun snapshotMapperPreservesEveryRecordAndOptionalField() { val native = populatedSnapshot(revision = 2UL) val mapped = native.toApplicationSnapshot() diff --git a/app/shared/src/commonMain/kotlin/org/harvestcircle/application/ApplicationModels.kt b/app/shared/src/commonMain/kotlin/org/harvestcircle/application/ApplicationModels.kt @@ -146,6 +146,12 @@ enum class ApplicationErrorCode { NativeLibraryLoadFailed, CompatibilityMismatch, Internal, + AvailabilityInvalidInput, + AvailabilityUnsupportedProfile, + AvailabilityScopeMismatch, + AvailabilityStaleQuery, + AvailabilityCapacity, + AvailabilityUnavailable, } enum class ApplicationErrorCategory { diff --git a/app/shared/src/commonTest/kotlin/org/harvestcircle/application/RuntimeContractsTest.kt b/app/shared/src/commonTest/kotlin/org/harvestcircle/application/RuntimeContractsTest.kt @@ -131,7 +131,7 @@ class RuntimeContractsTest { .size, ) assertEquals( - 23, + 29, ApplicationErrorCode.entries .map(::errorCodeName) .distinct() diff --git a/build-logic/contracts/src/main/kotlin/org/harvestcircle/buildlogic/contracts/FfiCompatibilityBaseline.kt b/build-logic/contracts/src/main/kotlin/org/harvestcircle/buildlogic/contracts/FfiCompatibilityBaseline.kt @@ -47,7 +47,7 @@ public class FfiCompatibilityBaseline private constructor( require(values.getValue("schema") == "harvestcircle.ffi.v4") require(values.getValue("contract.id") == "harvestcircle-desktop-ffi-v4") require(values.getValue("contract.major") == "4") - require(values.getValue("contract.minor") == "3") + require(values.getValue("contract.minor") == "4") require(values.getValue("snapshot.schema") == "1") require(values.getValue("storage.schema.minimum") == "1") require(values.getValue("storage.schema.current") == "2") diff --git a/build-logic/contracts/src/test/kotlin/org/harvestcircle/buildlogic/contracts/BuildContractsTest.kt b/build-logic/contracts/src/test/kotlin/org/harvestcircle/buildlogic/contracts/BuildContractsTest.kt @@ -210,7 +210,20 @@ class BuildContractsTest { assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("package.version=1.0.0", "package.version=invalid")) } assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("schema=harvestcircle.ffi.v4", "schema=harvestcircle.ffi.v3")) } assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("contract.major=4", "contract.major=3")) } - assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("contract.minor=3", "contract.minor=2")) } + assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("contract.minor=4", "contract.minor=3")) } + } + + @Test + fun ffiBaselineAdmitsAllocatedMinorAndRejectsOldCurrentMinor() { + val baseline = FfiCompatibilityBaseline.parse(ffiBaseline) + + assertEquals("4", baseline["contract.major"]) + assertEquals("4", baseline["contract.minor"]) + assertEquals("1", baseline["snapshot.schema"]) + assertEquals("1", baseline["storage.schema.minimum"]) + assertEquals("2", baseline["storage.schema.current"]) + assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("contract.minor=4", "contract.minor=3")) } + assertFails { FfiCompatibilityBaseline.parse(ffiBaseline.replace("contract.minor=4", "contract.minor=5")) } } @Test @@ -366,7 +379,7 @@ class BuildContractsTest { schema=harvestcircle.ffi.v4 contract.id=harvestcircle-desktop-ffi-v4 contract.major=4 - contract.minor=3 + contract.minor=4 contract.hash=${"a".repeat(64)} product.coordinate_digest=${"b".repeat(64)} snapshot.schema=1 diff --git a/build-logic/plugins/src/functionalTest/kotlin/org/harvestcircle/buildlogic/plugins/ConventionPluginSmokeTest.kt b/build-logic/plugins/src/functionalTest/kotlin/org/harvestcircle/buildlogic/plugins/ConventionPluginSmokeTest.kt @@ -676,7 +676,7 @@ class ConventionPluginSmokeTest { schema=harvestcircle.ffi.v4 contract.id=harvestcircle-desktop-ffi-v4 contract.major=4 - contract.minor=3 + contract.minor=4 contract.hash=b32b9a47d12e445e93866ae0ab668b18de503ba6c999e3a053f26dc9509ddaf9 product.coordinate_digest=bf50f9ea6c2537406de255f025463e670eb6263c295f992f7e4c4db36d957064 snapshot.schema=1 diff --git a/core/Cargo.lock b/core/Cargo.lock @@ -980,6 +980,7 @@ name = "harvestcircle_application" version = "0.1.0-alpha" dependencies = [ "harvestcircle_domain", + "radroots_transport", "radroots_transport_nostr", "secrecy", "tokio", diff --git a/core/compatibility/harvestcircle-ffi-v4.properties b/core/compatibility/harvestcircle-ffi-v4.properties @@ -1,8 +1,8 @@ schema=harvestcircle.ffi.v4 contract.id=harvestcircle-desktop-ffi-v4 contract.major=4 -contract.minor=3 -contract.hash=237a67e864761fded90c9a41d92da7b6a514ef22810adbdc2784b7ad5e10826a +contract.minor=4 +contract.hash=7d62bb5f894725b648503254b97f6e9a274daba06196184f1c2014f66f398efd product.coordinate_digest=bf50f9ea6c2537406de255f025463e670eb6263c295f992f7e4c4db36d957064 snapshot.schema=1 storage.schema.minimum=1 diff --git a/core/crates/harvestcircle_application/Cargo.toml b/core/crates/harvestcircle_application/Cargo.toml @@ -13,6 +13,7 @@ include = ["src/**", "tests/**", "Cargo.toml"] [dependencies] harvestcircle_domain.workspace = true +radroots_transport.workspace = true radroots_transport_nostr.workspace = true secrecy = "=0.10.3" tokio = { version = "=1.47.1", features = ["macros", "rt-multi-thread", "sync", "time"] } diff --git a/core/crates/harvestcircle_application/src/availability_outcomes.rs b/core/crates/harvestcircle_application/src/availability_outcomes.rs @@ -0,0 +1,537 @@ +//! Bounded caller-supplied discovery requests, progress and owned valid results. +//! +//! These immutable values perform no I/O, admission, event validation, deadline +//! enforcement or resource reservation. Their counters describe supplied work; +//! they do not establish exhaustive network knowledge or current local storage. + +use std::fmt::{self, Write}; + +use harvestcircle_domain::SafeError; +use harvestcircle_domain::error::AvailabilityFailure; +pub use radroots_transport::outcome::FetchTargetState; +pub use radroots_transport::target::TargetFingerprint; + +use crate::{AvailabilityLocalQueryScope, RequestId}; + +pub const MAX_DISCOVERY_TARGETS: usize = 16; +pub const MAX_DISCOVERY_FETCH_CALLS: u8 = 4; +pub const DISCOVERY_FETCH_RAW_RESERVATION_BYTES: u64 = 8_388_608; +pub const MAX_DISCOVERY_RETURNED_PER_TARGET: u16 = 64; +pub const MAX_DISCOVERY_RETURNED_EVENTS: u16 = 1_024; +pub const MAX_DISCOVERY_METADATA_BYTES: usize = 16_384; + +// Fixed keys, finite labels and bounded decimals fit in 384 envelope bytes. +// Each target's 64 hex bytes and three progress objects fit in 384 bytes, +// including its separator. The complete structural bound is therefore 6,528. +const METADATA_ENVELOPE_MAX_BYTES: usize = 384; +const METADATA_TARGET_MAX_BYTES: usize = 384; +const _: () = assert!( + METADATA_ENVELOPE_MAX_BYTES + MAX_DISCOVERY_TARGETS * METADATA_TARGET_MAX_BYTES + <= MAX_DISCOVERY_METADATA_BYTES +); + +/// Structural source selection and local bindings without effect authority. +#[derive(Clone, Eq, PartialEq)] +pub struct AvailabilityDiscoveryRequest { + request_id: RequestId, + scope: AvailabilityLocalQueryScope, + targets: Vec<TargetFingerprint>, + deadline_millis: u64, +} + +impl AvailabilityDiscoveryRequest { + /// Retains the original bounded unique target vector and structural scope. + /// + /// # Errors + /// + /// Returns capacity for more than sixteen targets, or invalid input for + /// duplicate canonical fingerprints or a deadline outside 1..=30,000 ms. + pub fn new( + request_id: RequestId, + scope: AvailabilityLocalQueryScope, + targets: Vec<TargetFingerprint>, + deadline_millis: u64, + ) -> Result<Self, SafeError> { + if targets.len() > MAX_DISCOVERY_TARGETS { + return Err(AvailabilityFailure::Capacity.into()); + } + if targets + .iter() + .enumerate() + .any(|(index, target)| targets[..index].contains(target)) + || !(1..=30_000).contains(&deadline_millis) + { + return Err(AvailabilityFailure::InvalidInput.into()); + } + Ok(Self { + request_id, + scope, + targets, + deadline_millis, + }) + } + + #[must_use] + pub const fn request_id(&self) -> RequestId { + self.request_id + } + + #[must_use] + pub const fn scope(&self) -> &AvailabilityLocalQueryScope { + &self.scope + } + + #[must_use] + pub fn targets(&self) -> &[TargetFingerprint] { + &self.targets + } + + #[must_use] + pub const fn deadline_millis(&self) -> u64 { + self.deadline_millis + } +} + +impl fmt::Debug for AvailabilityDiscoveryRequest { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityDiscoveryRequest") + .field("selected_targets", &self.targets.len()) + .field("deadline_millis", &self.deadline_millis) + .finish_non_exhaustive() + } +} + +/// Exact shared target state, with an explicit absence of requested work. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AvailabilityDiscoveryState { + NotRequested, + Requested(FetchTargetState), +} + +impl AvailabilityDiscoveryState { + const fn metadata_label(self) -> &'static str { + match self { + Self::NotRequested => "not_requested", + Self::Requested(FetchTargetState::Complete) => "complete", + Self::Requested(FetchTargetState::Partial) => "partial", + Self::Requested(FetchTargetState::Unavailable) => "unavailable", + Self::Requested(FetchTargetState::FailedRetryable) => "failed_retryable", + Self::Requested(FetchTargetState::FailedTerminal) => "failed_terminal", + Self::Requested(FetchTargetState::Cancelled) => "cancelled", + } + } +} + +/// Finite target-local stopping information without arbitrary diagnostic text. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AvailabilityDiscoveryStopReason { + None, + BudgetExhausted, + DeadlineExpired, + Stopped, +} + +impl AvailabilityDiscoveryStopReason { + const fn metadata_label(self) -> &'static str { + match self { + Self::None => "none", + Self::BudgetExhausted => "budget_exhausted", + Self::DeadlineExpired => "deadline_expired", + Self::Stopped => "stopped", + } + } +} + +/// One stream's consistent target-local facts, including earlier results. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct AvailabilityDiscoveryProgress { + state: AvailabilityDiscoveryState, + reason: AvailabilityDiscoveryStopReason, + returned: u16, +} + +impl AvailabilityDiscoveryProgress { + /// Preserves complete-empty, interrupted and unrequested distinctions. + /// + /// # Errors + /// + /// Returns capacity for more than sixty-four returned events, or invalid + /// input for a reason/count inconsistent with the supplied stream state. + pub fn new( + state: AvailabilityDiscoveryState, + reason: AvailabilityDiscoveryStopReason, + returned: u16, + ) -> Result<Self, SafeError> { + if returned > MAX_DISCOVERY_RETURNED_PER_TARGET { + return Err(AvailabilityFailure::Capacity.into()); + } + let valid = match state { + AvailabilityDiscoveryState::NotRequested + | AvailabilityDiscoveryState::Requested(FetchTargetState::Unavailable) => { + reason == AvailabilityDiscoveryStopReason::None && returned == 0 + } + AvailabilityDiscoveryState::Requested( + FetchTargetState::Complete + | FetchTargetState::FailedRetryable + | FetchTargetState::FailedTerminal, + ) => reason == AvailabilityDiscoveryStopReason::None, + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial) => { + matches!( + reason, + AvailabilityDiscoveryStopReason::None + | AvailabilityDiscoveryStopReason::BudgetExhausted + | AvailabilityDiscoveryStopReason::DeadlineExpired + ) + } + AvailabilityDiscoveryState::Requested(FetchTargetState::Cancelled) => { + reason == AvailabilityDiscoveryStopReason::Stopped + } + }; + if !valid { + return Err(AvailabilityFailure::InvalidInput.into()); + } + Ok(Self { + state, + reason, + returned, + }) + } + + #[must_use] + pub const fn state(&self) -> AvailabilityDiscoveryState { + self.state + } + + #[must_use] + pub const fn reason(&self) -> AvailabilityDiscoveryStopReason { + self.reason + } + + #[must_use] + pub const fn returned(&self) -> u16 { + self.returned + } + + fn append_metadata(self, json: &mut String) { + write!( + json, + "{{\"state\":\"{}\",\"reason\":\"{}\",\"returned\":{}}}", + self.state.metadata_label(), + self.reason.metadata_label(), + self.returned + ) + .expect("writing finite metadata to String cannot fail"); + } +} + +/// Three independent streams sharing one sixty-four-event target allowance. +#[derive(Clone, Eq, PartialEq)] +pub struct AvailabilityDiscoveryTargetOutcome { + target: TargetFingerprint, + listings: AvailabilityDiscoveryProgress, + profiles: AvailabilityDiscoveryProgress, + deletions: AvailabilityDiscoveryProgress, +} + +impl AvailabilityDiscoveryTargetOutcome { + /// Retains admitted progress only after checking the shared target sum. + /// + /// # Errors + /// + /// Returns capacity if the three returned counts together exceed sixty-four. + pub fn new( + target: TargetFingerprint, + listings: AvailabilityDiscoveryProgress, + profiles: AvailabilityDiscoveryProgress, + deletions: AvailabilityDiscoveryProgress, + ) -> Result<Self, SafeError> { + if listings.returned() + profiles.returned() + deletions.returned() + > MAX_DISCOVERY_RETURNED_PER_TARGET + { + return Err(AvailabilityFailure::Capacity.into()); + } + Ok(Self { + target, + listings, + profiles, + deletions, + }) + } + + #[must_use] + pub const fn target(&self) -> &TargetFingerprint { + &self.target + } + + #[must_use] + pub const fn listings(&self) -> AvailabilityDiscoveryProgress { + self.listings + } + + #[must_use] + pub const fn profiles(&self) -> AvailabilityDiscoveryProgress { + self.profiles + } + + #[must_use] + pub const fn deletions(&self) -> AvailabilityDiscoveryProgress { + self.deletions + } + + const fn returned(&self) -> u16 { + self.listings.returned() + self.profiles.returned() + self.deletions.returned() + } + + fn has_complete_stream(&self) -> bool { + [self.listings, self.profiles, self.deletions] + .iter() + .any(|progress| { + progress.state() + == AvailabilityDiscoveryState::Requested(FetchTargetState::Complete) + }) + } +} + +impl fmt::Debug for AvailabilityDiscoveryTargetOutcome { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityDiscoveryTargetOutcome") + .field("listings", &self.listings) + .field("profiles", &self.profiles) + .field("deletions", &self.deletions) + .finish_non_exhaustive() + } +} + +/// Bounded supplied operation accounting without actual transport reservation. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct AvailabilityDiscoveryUsage { + fetch_calls: u8, + returned_events: u16, +} + +impl AvailabilityDiscoveryUsage { + /// Admits at most four fetch calls and 1,024 aggregate returned events. + /// + /// # Errors + /// + /// Returns capacity for either exceeded bound, or invalid input for returned + /// events with zero supplied calls. Reported reservations are never refunded. + pub fn new(fetch_calls: u8, returned_events: u16) -> Result<Self, SafeError> { + if fetch_calls > MAX_DISCOVERY_FETCH_CALLS + || returned_events > MAX_DISCOVERY_RETURNED_EVENTS + { + return Err(AvailabilityFailure::Capacity.into()); + } + if fetch_calls == 0 && returned_events != 0 { + return Err(AvailabilityFailure::InvalidInput.into()); + } + Ok(Self { + fetch_calls, + returned_events, + }) + } + + #[must_use] + pub const fn fetch_calls(&self) -> u8 { + self.fetch_calls + } + + #[must_use] + pub const fn returned_events(&self) -> u16 { + self.returned_events + } + + #[must_use] + pub const fn reserved_raw_bytes(&self) -> u64 { + self.fetch_calls as u64 * DISCOVERY_FETCH_RAW_RESERVATION_BYTES + } +} + +/// Original owned valid items retained across independently interrupted targets. +/// +/// Item admission remains the caller's responsibility. No item serialization, +/// event evidence, freshness or persistence is inferred from these values. +pub struct AvailabilityDiscoveryOutcome<T> { + request: AvailabilityDiscoveryRequest, + usage: AvailabilityDiscoveryUsage, + targets: Vec<AvailabilityDiscoveryTargetOutcome>, + items: Vec<T>, +} + +impl<T> AvailabilityDiscoveryOutcome<T> { + /// Binds exactly one outcome to each selected target without cloning items. + /// + /// # Errors + /// + /// Returns capacity for oversized vectors, scope mismatch for a different + /// target set, or invalid input for duplicate outcomes, inconsistent counts, + /// completion without a call, or fabricated work for an empty selection. + pub fn new( + request: AvailabilityDiscoveryRequest, + usage: AvailabilityDiscoveryUsage, + targets: Vec<AvailabilityDiscoveryTargetOutcome>, + items: Vec<T>, + ) -> Result<Self, SafeError> { + if targets.len() > MAX_DISCOVERY_TARGETS + || items.len() > usize::from(MAX_DISCOVERY_RETURNED_EVENTS) + { + return Err(AvailabilityFailure::Capacity.into()); + } + if targets.iter().enumerate().any(|(index, target)| { + targets[..index] + .iter() + .any(|previous| previous.target() == target.target()) + }) { + return Err(AvailabilityFailure::InvalidInput.into()); + } + if targets.len() != request.targets().len() + || targets + .iter() + .any(|target| !request.targets().contains(target.target())) + { + return Err(AvailabilityFailure::ScopeMismatch.into()); + } + // At most sixteen independently admitted sums of at most sixty-four. + let returned: u16 = targets + .iter() + .map(AvailabilityDiscoveryTargetOutcome::returned) + .sum(); + if returned != usage.returned_events() + || items.len() > usize::from(returned) + || (usage.fetch_calls() == 0 + && targets + .iter() + .any(AvailabilityDiscoveryTargetOutcome::has_complete_stream)) + || (request.targets().is_empty() && usage.fetch_calls() != 0) + { + return Err(AvailabilityFailure::InvalidInput.into()); + } + Ok(Self { + request, + usage, + targets, + items, + }) + } + + #[must_use] + pub const fn request(&self) -> &AvailabilityDiscoveryRequest { + &self.request + } + + #[must_use] + pub const fn usage(&self) -> AvailabilityDiscoveryUsage { + self.usage + } + + #[must_use] + pub fn targets(&self) -> &[AvailabilityDiscoveryTargetOutcome] { + &self.targets + } + + #[must_use] + pub fn items(&self) -> &[T] { + &self.items + } + + #[must_use] + pub fn into_items(self) -> Vec<T> { + self.items + } + + #[must_use] + pub fn listings_state(&self) -> AvailabilityDiscoveryState { + self.stream_state(AvailabilityDiscoveryTargetOutcome::listings) + } + + #[must_use] + pub fn profiles_state(&self) -> AvailabilityDiscoveryState { + self.stream_state(AvailabilityDiscoveryTargetOutcome::profiles) + } + + #[must_use] + pub fn deletions_state(&self) -> AvailabilityDiscoveryState { + self.stream_state(AvailabilityDiscoveryTargetOutcome::deletions) + } + + fn stream_state( + &self, + progress: fn(&AvailabilityDiscoveryTargetOutcome) -> AvailabilityDiscoveryProgress, + ) -> AvailabilityDiscoveryState { + let Some(first) = self.targets.first() else { + return AvailabilityDiscoveryState::NotRequested; + }; + let state = progress(first).state(); + if self + .targets + .iter() + .all(|target| progress(target).state() == state) + { + state + } else { + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial) + } + } + + /// Serializes only finite metadata, preserving the supplied target order. + /// + /// The fixed envelope and sixteen bounded target objects fit within 6,528 + /// ASCII bytes, below the 16 KiB contract. Only shared admitted fingerprints, + /// finite labels and bounded decimals enter JSON; items and scope do not. + #[must_use] + pub fn metadata_json(&self) -> String { + let mut json = String::with_capacity( + METADATA_ENVELOPE_MAX_BYTES + self.targets.len() * METADATA_TARGET_MAX_BYTES, + ); + write!( + json, + concat!( + "{{\"version\":1,\"fetch_calls\":{},\"reserved_raw_bytes\":{},", + "\"returned_events\":{},\"retained_items\":{},\"listings\":\"{}\",", + "\"profiles\":\"{}\",\"deletions\":\"{}\",\"targets\":[" + ), + self.usage.fetch_calls(), + self.usage.reserved_raw_bytes(), + self.usage.returned_events(), + self.items.len(), + self.listings_state().metadata_label(), + self.profiles_state().metadata_label(), + self.deletions_state().metadata_label() + ) + .expect("writing finite metadata to String cannot fail"); + for (index, target) in self.targets.iter().enumerate() { + if index != 0 { + json.push(','); + } + json.push_str("{\"target\":\""); + json.push_str(target.target().as_str()); + json.push_str("\",\"listings\":"); + target.listings().append_metadata(&mut json); + json.push_str(",\"profiles\":"); + target.profiles().append_metadata(&mut json); + json.push_str(",\"deletions\":"); + target.deletions().append_metadata(&mut json); + json.push('}'); + } + json.push_str("]}"); + json + } +} + +impl<T> fmt::Debug for AvailabilityDiscoveryOutcome<T> { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter + .debug_struct("AvailabilityDiscoveryOutcome") + .field("fetch_calls", &self.usage.fetch_calls()) + .field("reserved_raw_bytes", &self.usage.reserved_raw_bytes()) + .field("returned_events", &self.usage.returned_events()) + .field("retained_items", &self.items.len()) + .field("selected_targets", &self.targets.len()) + .field("listings", &self.listings_state()) + .field("profiles", &self.profiles_state()) + .field("deletions", &self.deletions_state()) + .finish_non_exhaustive() + } +} diff --git a/core/crates/harvestcircle_application/src/lib.rs b/core/crates/harvestcircle_application/src/lib.rs @@ -2,6 +2,7 @@ pub mod actor; pub mod app_core; +pub mod availability_outcomes; pub mod availability_query; mod change_stream; pub mod config; @@ -24,6 +25,13 @@ pub use actor::{ RuntimeCommandClass, RuntimeLifecycle, SessionGeneration, TaskCorrelation, }; pub use app_core::{AppCore, RemovalConfirmationToken, RemovalImpact}; +pub use availability_outcomes::{ + AvailabilityDiscoveryOutcome, AvailabilityDiscoveryProgress, AvailabilityDiscoveryRequest, + AvailabilityDiscoveryState, AvailabilityDiscoveryStopReason, + AvailabilityDiscoveryTargetOutcome, AvailabilityDiscoveryUsage, + DISCOVERY_FETCH_RAW_RESERVATION_BYTES, MAX_DISCOVERY_FETCH_CALLS, MAX_DISCOVERY_METADATA_BYTES, + MAX_DISCOVERY_RETURNED_EVENTS, MAX_DISCOVERY_RETURNED_PER_TARGET, MAX_DISCOVERY_TARGETS, +}; pub use availability_query::{AvailabilityLocalQueryScope, ScopedAvailabilityQuery}; pub use change_stream::{ ChangeSubscriptionId, OrderedSnapshotChanges, SnapshotChange, SnapshotChangeReceiver, diff --git a/core/crates/harvestcircle_application/tests/focused_availability_outcomes.rs b/core/crates/harvestcircle_application/tests/focused_availability_outcomes.rs @@ -0,0 +1,1160 @@ +use std::error::Error; + +use harvestcircle_application::availability_outcomes::{FetchTargetState, TargetFingerprint}; +use harvestcircle_application::{ + AvailabilityDiscoveryOutcome, AvailabilityDiscoveryProgress, AvailabilityDiscoveryRequest, + AvailabilityDiscoveryState, AvailabilityDiscoveryStopReason, + AvailabilityDiscoveryTargetOutcome, AvailabilityDiscoveryUsage, AvailabilityLocalQueryScope, + DISCOVERY_FETCH_RAW_RESERVATION_BYTES, MAX_DISCOVERY_FETCH_CALLS, MAX_DISCOVERY_METADATA_BYTES, + MAX_DISCOVERY_RETURNED_EVENTS, MAX_DISCOVERY_RETURNED_PER_TARGET, MAX_DISCOVERY_TARGETS, + RequestId, SessionGeneration, +}; +use harvestcircle_domain::error::AvailabilityFailure; +use harvestcircle_domain::{ + AvailabilityQueryContext, AvailabilityQueryError, PublicKey, SafeError, SafeErrorCode, +}; +use radroots_transport::outcome::FetchTargetOutcome; + +const AUTHOR_HEX: &str = "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"; + +fn scope() -> AvailabilityLocalQueryScope { + AvailabilityLocalQueryScope::new( + PublicKey::from_hex(AUTHOR_HEX).expect("fixed public curve author"), + AvailabilityQueryContext::new([1; 32], [2; 32], u64::MAX, u64::MAX) + .expect("nonzero structural context and store"), + SessionGeneration::from_value(u64::MAX), + ) +} + +fn fingerprint(index: u8) -> TargetFingerprint { + TargetFingerprint::parse(format!("{index:064x}")).expect("fixed public target fingerprint") +} + +fn request(targets: Vec<TargetFingerprint>) -> AvailabilityDiscoveryRequest { + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("nonzero request"), + scope(), + targets, + 30_000, + ) + .expect("bounded unique structural request") +} + +fn progress( + state: FetchTargetState, + reason: AvailabilityDiscoveryStopReason, + returned: u16, +) -> AvailabilityDiscoveryProgress { + AvailabilityDiscoveryProgress::new( + AvailabilityDiscoveryState::Requested(state), + reason, + returned, + ) + .expect("consistent bounded target progress") +} + +fn not_requested() -> AvailabilityDiscoveryProgress { + AvailabilityDiscoveryProgress::new( + AvailabilityDiscoveryState::NotRequested, + AvailabilityDiscoveryStopReason::None, + 0, + ) + .expect("explicit unrequested stream") +} + +fn target( + id: TargetFingerprint, + listings: AvailabilityDiscoveryProgress, + profiles: AvailabilityDiscoveryProgress, + deletions: AvailabilityDiscoveryProgress, +) -> AvailabilityDiscoveryTargetOutcome { + AvailabilityDiscoveryTargetOutcome::new(id, listings, profiles, deletions) + .expect("one shared bounded target allowance") +} + +fn unrequested_target(index: u8) -> AvailabilityDiscoveryTargetOutcome { + target( + fingerprint(index), + not_requested(), + not_requested(), + not_requested(), + ) +} + +fn usage(calls: u8, returned: u16) -> AvailabilityDiscoveryUsage { + AvailabilityDiscoveryUsage::new(calls, returned).expect("bounded supplied operation accounting") +} + +fn assert_code(error: SafeError, code: SafeErrorCode) { + assert_eq!(error.code(), code); + let standard_error: &dyn Error = &error; + assert!(standard_error.source().is_none()); +} + +#[test] +fn request_admits_empty_and_exact_target_limit() { + assert_eq!(MAX_DISCOVERY_TARGETS, 16); + for count in [0, 1, 16] { + let targets: Vec<_> = (1..=count).map(fingerprint).collect(); + let pointer = targets.as_ptr(); + let expected: Vec<_> = targets + .iter() + .map(|value| value.as_str().to_owned()) + .collect(); + let value = request(targets); + assert_eq!(value.targets().len(), usize::from(count)); + assert_eq!(value.targets().as_ptr(), pointer); + assert_eq!( + value + .targets() + .iter() + .map(TargetFingerprint::as_str) + .collect::<Vec<_>>(), + expected + ); + } + assert_code( + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("request"), + scope(), + (1..=17).map(fingerprint).collect(), + 1, + ) + .expect_err("seventeen selected targets"), + SafeErrorCode::AvailabilityCapacity, + ); +} + +#[test] +fn request_refuses_duplicates_and_invalid_deadlines() { + for targets in [ + vec![fingerprint(1), fingerprint(1)], + vec![ + fingerprint(1), + fingerprint(2), + fingerprint(3), + fingerprint(1), + ], + ] { + assert_code( + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("request"), + scope(), + targets, + 1, + ) + .expect_err("duplicate canonical target"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } + let uppercase = TargetFingerprint::parse("AB".repeat(32)).expect("shared canonicalization"); + let lowercase = TargetFingerprint::parse("ab".repeat(32)).expect("canonical target"); + assert_eq!(uppercase.as_str(), "ab".repeat(32)); + assert_code( + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("request"), + scope(), + vec![uppercase, lowercase], + 1, + ) + .expect_err("canonical aliases are duplicate targets"), + SafeErrorCode::AvailabilityInvalidInput, + ); + for deadline in [1, 30_000] { + assert_eq!( + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("request"), + scope(), + vec![], + deadline + ) + .expect("exact allowed deadline") + .deadline_millis(), + deadline + ); + } + for deadline in [0, 30_001, u64::MAX] { + assert_code( + AvailabilityDiscoveryRequest::new( + RequestId::new(7).expect("request"), + scope(), + vec![], + deadline, + ) + .expect_err("outside absolute deadline range"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } +} + +#[test] +fn request_preserves_scope_and_request_without_signer() { + let value = AvailabilityDiscoveryRequest::new( + RequestId::new(u64::MAX).expect("full-width request"), + scope(), + vec![fingerprint(1)], + 30_000, + ) + .expect("pure structural values require no signing capability"); + assert_eq!(value.request_id().get(), u64::MAX); + assert_eq!(value.scope().owner().to_hex(), AUTHOR_HEX); + assert_eq!(value.scope().context().context_id(), &[1; 32]); + assert_eq!(value.scope().context().store_generation(), &[2; 32]); + assert_eq!(value.scope().context().source_revision(), u64::MAX); + assert_eq!(value.scope().context().projection_generation(), u64::MAX); + assert_eq!(value.scope().session_generation().value(), u64::MAX); + assert_eq!(value.deadline_millis(), 30_000); + let value = AvailabilityDiscoveryOutcome::new( + value, + usage(0, 0), + vec![unrequested_target(1)], + Vec::<u8>::new(), + ) + .expect("structural unrequested outcome"); + assert_eq!(value.request().request_id().get(), u64::MAX); + assert_eq!( + value.request().scope().context().projection_generation(), + u64::MAX + ); +} + +#[test] +fn progress_preserves_every_shared_state_and_empty_distinction() { + let unrequested = not_requested(); + assert_eq!( + unrequested.state(), + AvailabilityDiscoveryState::NotRequested + ); + assert_eq!(unrequested.reason(), AvailabilityDiscoveryStopReason::None); + assert_eq!(unrequested.returned(), 0); + let cases = [ + ( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::BudgetExhausted, + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::DeadlineExpired, + ), + ( + FetchTargetState::Unavailable, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::FailedRetryable, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::FailedTerminal, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::Cancelled, + AvailabilityDiscoveryStopReason::Stopped, + ), + ]; + for (state, reason) in cases { + let value = progress(state, reason, 0); + assert_eq!(value.state(), AvailabilityDiscoveryState::Requested(state)); + assert_eq!(value.reason(), reason); + assert_eq!(value.returned(), 0); + assert_ne!(value.state(), unrequested.state()); + if state != FetchTargetState::Unavailable { + for count in [1, 64] { + assert_eq!(progress(state, reason, count).returned(), count); + } + } + } + assert_ne!( + progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 0 + ) + .state(), + progress( + FetchTargetState::Unavailable, + AvailabilityDiscoveryStopReason::None, + 0 + ) + .state() + ); +} + +#[test] +fn progress_rejects_inconsistent_stop_reasons_and_counts() { + let states = [ + AvailabilityDiscoveryState::NotRequested, + AvailabilityDiscoveryState::Requested(FetchTargetState::Complete), + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial), + AvailabilityDiscoveryState::Requested(FetchTargetState::Unavailable), + AvailabilityDiscoveryState::Requested(FetchTargetState::FailedRetryable), + AvailabilityDiscoveryState::Requested(FetchTargetState::FailedTerminal), + AvailabilityDiscoveryState::Requested(FetchTargetState::Cancelled), + ]; + for state in states { + for reason in [ + AvailabilityDiscoveryStopReason::None, + AvailabilityDiscoveryStopReason::BudgetExhausted, + AvailabilityDiscoveryStopReason::DeadlineExpired, + AvailabilityDiscoveryStopReason::Stopped, + ] { + for count in [0, 1, 64, 65] { + let valid = match state { + AvailabilityDiscoveryState::NotRequested => { + reason == AvailabilityDiscoveryStopReason::None && count == 0 + } + AvailabilityDiscoveryState::Requested( + FetchTargetState::Complete + | FetchTargetState::FailedRetryable + | FetchTargetState::FailedTerminal, + ) => reason == AvailabilityDiscoveryStopReason::None, + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial) => { + reason != AvailabilityDiscoveryStopReason::Stopped + } + AvailabilityDiscoveryState::Requested(FetchTargetState::Unavailable) => { + reason == AvailabilityDiscoveryStopReason::None && count == 0 + } + AvailabilityDiscoveryState::Requested(FetchTargetState::Cancelled) => { + reason == AvailabilityDiscoveryStopReason::Stopped + } + }; + let result = AvailabilityDiscoveryProgress::new(state, reason, count); + if count > 64 { + assert_code( + result.expect_err("returned cap checked first"), + SafeErrorCode::AvailabilityCapacity, + ); + } else if valid { + let value = result.expect("admitted state/reason/count matrix entry"); + assert_eq!( + (value.state(), value.reason(), value.returned()), + (state, reason, count) + ); + } else { + assert_code( + result.expect_err("inconsistent progress facts"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } + } + } + } +} + +#[test] +fn target_streams_remain_independent() { + let listings = progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 10, + ); + let profiles = progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::DeadlineExpired, + 2, + ); + let deletions = progress( + FetchTargetState::FailedTerminal, + AvailabilityDiscoveryStopReason::None, + 1, + ); + let value = target(fingerprint(1), listings, profiles, deletions); + assert_eq!(value.target(), &fingerprint(1)); + assert_eq!(value.listings(), listings); + assert_eq!(value.profiles(), profiles); + assert_eq!(value.deletions(), deletions); + assert_eq!( + value.listings().state(), + AvailabilityDiscoveryState::Requested(FetchTargetState::Complete) + ); + assert_eq!( + value.profiles().reason(), + AvailabilityDiscoveryStopReason::DeadlineExpired + ); + assert_eq!(value.deletions().returned(), 1); +} + +#[test] +fn per_target_limit_is_shared_across_all_three_streams() { + assert_eq!(MAX_DISCOVERY_RETURNED_PER_TARGET, 64); + for counts in [ + [0, 0, 0], + [1, 0, 0], + [64, 0, 0], + [0, 64, 0], + [0, 0, 64], + [21, 21, 21], + [22, 21, 21], + ] { + let stages = counts.map(|count| { + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + count, + ) + }); + let value = target(fingerprint(1), stages[0], stages[1], stages[2]); + assert_eq!( + [ + value.listings().returned(), + value.profiles().returned(), + value.deletions().returned() + ], + counts + ); + } + for counts in [ + [23, 21, 21], + [64, 1, 0], + [0, 64, 1], + [1, 0, 64], + [64, 64, 64], + ] { + let stages = counts.map(|count| { + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + count, + ) + }); + assert_code( + AvailabilityDiscoveryTargetOutcome::new( + fingerprint(1), + stages[0], + stages[1], + stages[2], + ) + .expect_err("sum exceeds the one target allowance"), + SafeErrorCode::AvailabilityCapacity, + ); + } +} + +#[test] +fn usage_enforces_operation_wide_calls_events_and_no_refunds() { + assert_eq!(MAX_DISCOVERY_FETCH_CALLS, 4); + assert_eq!(MAX_DISCOVERY_RETURNED_EVENTS, 1024); + assert_eq!(DISCOVERY_FETCH_RAW_RESERVATION_BYTES, 8_388_608); + for calls in 0..=4 { + for returned in [0, 1, 1024] { + if calls == 0 && returned > 0 { + assert_code( + AvailabilityDiscoveryUsage::new(calls, returned) + .expect_err("returns without any call"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } else { + let value = usage(calls, returned); + assert_eq!(value.fetch_calls(), calls); + assert_eq!(value.returned_events(), returned); + assert_eq!(value.reserved_raw_bytes(), u64::from(calls) * 8_388_608); + } + } + } + assert_eq!(usage(4, 0).reserved_raw_bytes(), 33_554_432); + assert_eq!( + usage(4, 1024).reserved_raw_bytes(), + usage(4, 0).reserved_raw_bytes() + ); + for (calls, returned) in [(5, 0), (5, 1024), (4, 1025), (0, 1025), (u8::MAX, u16::MAX)] { + assert_code( + AvailabilityDiscoveryUsage::new(calls, returned).expect_err("aggregate accounting cap"), + SafeErrorCode::AvailabilityCapacity, + ); + } +} + +#[test] +fn outcome_preserves_items_after_partial_capped_failed_and_cancelled_targets() { + for (state, reason) in [ + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::BudgetExhausted, + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::DeadlineExpired, + ), + ( + FetchTargetState::FailedRetryable, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::FailedTerminal, + AvailabilityDiscoveryStopReason::None, + ), + ( + FetchTargetState::Cancelled, + AvailabilityDiscoveryStopReason::Stopped, + ), + ] { + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 3), + vec![target( + fingerprint(1), + progress(state, reason, 3), + not_requested(), + not_requested(), + )], + vec![11_u8, 22, 33], + ) + .expect("valid earlier results survive non-complete target states"); + assert_eq!(value.items(), &[11, 22, 33]); + assert_eq!(value.usage().returned_events(), 3); + assert_eq!( + value.listings_state(), + AvailabilityDiscoveryState::Requested(state) + ); + assert_eq!(value.targets()[0].listings().reason(), reason); + assert_eq!(value.into_items(), vec![11, 22, 33]); + } +} + +#[test] +fn outcome_refuses_missing_extra_and_duplicate_targets() { + for supplied in [ + vec![], + vec![unrequested_target(2)], + vec![unrequested_target(1), unrequested_target(2)], + ] { + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(0, 0), + supplied, + Vec::<u8>::new(), + ) + .expect_err("missing or unrequested target fingerprint"), + SafeErrorCode::AvailabilityScopeMismatch, + ); + } + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1), fingerprint(2)]), + usage(0, 0), + vec![unrequested_target(1), unrequested_target(1)], + Vec::<u8>::new(), + ) + .expect_err("duplicate supplied outcome"), + SafeErrorCode::AvailabilityInvalidInput, + ); + assert_code( + AvailabilityDiscoveryOutcome::new( + request((1..=16).map(fingerprint).collect()), + usage(0, 0), + (1..=17).map(unrequested_target).collect(), + Vec::<u8>::new(), + ) + .expect_err("target cap before set validation"), + SafeErrorCode::AvailabilityCapacity, + ); + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1), fingerprint(2), fingerprint(3)]), + usage(0, 0), + vec![ + unrequested_target(3), + unrequested_target(1), + unrequested_target(2), + ], + Vec::<u8>::new(), + ) + .expect("permuted exact fingerprint set"); + assert_eq!( + value + .targets() + .iter() + .map(|value| value.target().as_str()) + .collect::<Vec<_>>(), + vec![ + format!("{:064x}", 3), + format!("{:064x}", 1), + format!("{:064x}", 2) + ] + ); +} + +#[test] +fn outcome_binds_returned_count_and_valid_item_count() { + for retained in [0, 1, 3] { + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 3), + vec![target( + fingerprint(1), + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + 3, + ), + not_requested(), + not_requested(), + )], + vec![9_u8; retained], + ) + .expect("valid items may be fewer than returned candidates"); + assert_eq!(value.items().len(), retained); + } + for returned in [0, 2, 4] { + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, returned), + vec![target( + fingerprint(1), + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + 3, + ), + not_requested(), + not_requested(), + )], + Vec::<u8>::new(), + ) + .expect_err("exact aggregate returned count"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 3), + vec![target( + fingerprint(1), + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::None, + 3, + ), + not_requested(), + not_requested(), + )], + vec![9_u8; 4], + ) + .expect_err("valid items cannot exceed returned candidates"), + SafeErrorCode::AvailabilityInvalidInput, + ); + assert_code( + AvailabilityDiscoveryOutcome::new(request(vec![]), usage(0, 0), vec![], vec![9_u8; 1025]) + .expect_err("item cap before empty-source/count validation"), + SafeErrorCode::AvailabilityCapacity, + ); + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(0, 0), + vec![target( + fingerprint(1), + progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 0, + ), + not_requested(), + not_requested(), + )], + Vec::<u8>::new(), + ) + .expect_err("completion requires a supplied fetch call"), + SafeErrorCode::AvailabilityInvalidInput, + ); +} + +#[test] +fn empty_selection_never_fabricates_complete_or_network_work() { + let value = + AvailabilityDiscoveryOutcome::new(request(vec![]), usage(0, 0), vec![], Vec::<u8>::new()) + .expect("explicit no-source selection"); + assert_eq!( + value.listings_state(), + AvailabilityDiscoveryState::NotRequested + ); + assert_eq!( + value.profiles_state(), + AvailabilityDiscoveryState::NotRequested + ); + assert_eq!( + value.deletions_state(), + AvailabilityDiscoveryState::NotRequested + ); + assert_eq!(value.usage().reserved_raw_bytes(), 0); + assert!(value.targets().is_empty()); + assert!(value.items().is_empty()); + for (calls, returned, items) in [ + (1, 0, vec![]), + (1, 1, vec![]), + (1, 1, vec![1_u8]), + (0, 0, vec![1_u8]), + ] { + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![]), + usage(calls, returned), + vec![], + items, + ) + .expect_err("empty selection cannot fabricate work or items"), + SafeErrorCode::AvailabilityInvalidInput, + ); + } + assert_code( + AvailabilityDiscoveryOutcome::new( + request(vec![]), + usage(0, 0), + vec![unrequested_target(1)], + Vec::<u8>::new(), + ) + .expect_err("no target may be fabricated"), + SafeErrorCode::AvailabilityScopeMismatch, + ); +} + +#[test] +fn stream_completeness_requires_every_selected_target() { + let states = [ + AvailabilityDiscoveryState::NotRequested, + AvailabilityDiscoveryState::Requested(FetchTargetState::Complete), + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial), + AvailabilityDiscoveryState::Requested(FetchTargetState::Unavailable), + AvailabilityDiscoveryState::Requested(FetchTargetState::FailedRetryable), + AvailabilityDiscoveryState::Requested(FetchTargetState::FailedTerminal), + AvailabilityDiscoveryState::Requested(FetchTargetState::Cancelled), + ]; + for first in states { + for second in states { + let stage = |state| { + AvailabilityDiscoveryProgress::new( + state, + if state == AvailabilityDiscoveryState::Requested(FetchTargetState::Cancelled) { + AvailabilityDiscoveryStopReason::Stopped + } else { + AvailabilityDiscoveryStopReason::None + }, + 0, + ) + .expect("zero-count stream state") + }; + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1), fingerprint(2)]), + usage(1, 0), + vec![ + target(fingerprint(1), stage(first), stage(first), stage(first)), + target(fingerprint(2), stage(second), stage(second), stage(second)), + ], + Vec::<u8>::new(), + ) + .expect("exact selected stream evidence"); + let expected = if first == second { + first + } else { + AvailabilityDiscoveryState::Requested(FetchTargetState::Partial) + }; + assert_eq!(value.listings_state(), expected); + assert_eq!(value.profiles_state(), expected); + assert_eq!(value.deletions_state(), expected); + } + } +} + +#[test] +fn one_stream_failure_never_erases_another_stream_completion() { + for interrupted in [ + FetchTargetState::Partial, + FetchTargetState::Unavailable, + FetchTargetState::FailedRetryable, + FetchTargetState::FailedTerminal, + FetchTargetState::Cancelled, + ] { + let reason = if interrupted == FetchTargetState::Cancelled { + AvailabilityDiscoveryStopReason::Stopped + } else { + AvailabilityDiscoveryStopReason::None + }; + for stream in 0..3 { + let mut stages = [progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 0, + ); 3]; + stages[stream] = progress(interrupted, reason, 0); + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 0), + vec![target(fingerprint(1), stages[0], stages[1], stages[2])], + Vec::<u8>::new(), + ) + .expect("independent stream statuses"); + for (index, observed) in [ + value.listings_state(), + value.profiles_state(), + value.deletions_state(), + ] + .into_iter() + .enumerate() + { + assert_eq!( + observed, + AvailabilityDiscoveryState::Requested(if index == stream { + interrupted + } else { + FetchTargetState::Complete + }) + ); + } + } + } +} + +#[test] +fn outcome_retains_owned_nonclone_items_without_copy() { + struct PrivateItem { + marker: String, + } + let items = vec![PrivateItem { + marker: "HCAV_PRIVATE_NONDEBUG_ITEM".to_owned(), + }]; + let pointer = items.as_ptr(); + let capacity = items.capacity(); + let targets = vec![target( + fingerprint(1), + progress( + FetchTargetState::FailedRetryable, + AvailabilityDiscoveryStopReason::None, + 1, + ), + not_requested(), + not_requested(), + )]; + let targets_pointer = targets.as_ptr(); + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 1), + targets, + items, + ) + .expect("no item Clone/Debug requirement"); + assert_eq!(value.items().as_ptr(), pointer); + assert_eq!(value.targets().as_ptr(), targets_pointer); + assert_eq!(value.items()[0].marker, "HCAV_PRIVATE_NONDEBUG_ITEM"); + assert!(!format!("{value:?}").contains("HCAV_PRIVATE_NONDEBUG_ITEM")); + assert!(!value.metadata_json().contains("HCAV_PRIVATE_NONDEBUG_ITEM")); + let returned = value.into_items(); + assert_eq!(returned.as_ptr(), pointer); + assert_eq!(returned.capacity(), capacity); + assert_eq!(returned[0].marker, "HCAV_PRIVATE_NONDEBUG_ITEM"); +} + +#[test] +fn metadata_serialization_has_exact_safe_schema() { + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 3), + vec![target( + fingerprint(1), + progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 1, + ), + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::BudgetExhausted, + 2, + ), + not_requested(), + )], + vec!["HCAV_PRIVATE_ITEM_PAYLOAD"], + ) + .expect("independently described metadata fixture"); + let expected = concat!( + "{\"version\":1,\"fetch_calls\":1,\"reserved_raw_bytes\":8388608,\"returned_events\":3,\"retained_items\":1,", + "\"listings\":\"complete\",\"profiles\":\"partial\",\"deletions\":\"not_requested\",\"targets\":[", + "{\"target\":\"0000000000000000000000000000000000000000000000000000000000000001\",", + "\"listings\":{\"state\":\"complete\",\"reason\":\"none\",\"returned\":1},", + "\"profiles\":{\"state\":\"partial\",\"reason\":\"budget_exhausted\",\"returned\":2},", + "\"deletions\":{\"state\":\"not_requested\",\"reason\":\"none\",\"returned\":0}}]}" + ); + assert_eq!(value.metadata_json(), expected); + assert_eq!(value.metadata_json(), value.metadata_json()); + let empty = + AvailabilityDiscoveryOutcome::new(request(vec![]), usage(0, 0), vec![], Vec::<u8>::new()) + .expect("empty metadata"); + assert_eq!( + empty.metadata_json(), + "{\"version\":1,\"fetch_calls\":0,\"reserved_raw_bytes\":0,\"returned_events\":0,\"retained_items\":0,\"listings\":\"not_requested\",\"profiles\":\"not_requested\",\"deletions\":\"not_requested\",\"targets\":[]}" + ); +} + +#[test] +fn metadata_serialization_is_bounded_at_sixteen_targets() { + assert_eq!(MAX_DISCOVERY_METADATA_BYTES, 16_384); + let targets: Vec<_> = (1..=16) + .rev() + .map(|index| { + target( + fingerprint(index), + progress( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + 32, + ), + progress( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::DeadlineExpired, + 16, + ), + progress( + FetchTargetState::FailedRetryable, + AvailabilityDiscoveryStopReason::None, + 16, + ), + ) + }) + .collect(); + let value = AvailabilityDiscoveryOutcome::new( + request((1..=16).map(fingerprint).collect()), + usage(4, 1024), + targets, + vec!["HCAV_PRIVATE_LARGE_RESULT"; 1024], + ) + .expect("exact full target/result/accounting bounds"); + let json = value.metadata_json(); + assert!(json.is_ascii()); + assert!(json.len() <= 16_384); + assert_eq!(json.matches("\"target\":").count(), 16); + assert_eq!(json.matches("\"returned\":32").count(), 16); + assert_eq!(json.matches("\"returned\":16").count(), 32); + assert!(json.starts_with("{\"version\":1,\"fetch_calls\":4,\"reserved_raw_bytes\":33554432,\"returned_events\":1024,\"retained_items\":1024,")); + let first = format!("\"target\":\"{:064x}\"", 16); + let last = format!("\"target\":\"{:064x}\"", 1); + assert!( + json.find(&first).expect("supplied first target") + < json.find(&last).expect("supplied last target") + ); + assert!(!json.contains("HCAV_PRIVATE_LARGE_RESULT")); + for (state, reason, name, reason_name) in [ + ( + FetchTargetState::Complete, + AvailabilityDiscoveryStopReason::None, + "complete", + "none", + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::BudgetExhausted, + "partial", + "budget_exhausted", + ), + ( + FetchTargetState::Partial, + AvailabilityDiscoveryStopReason::DeadlineExpired, + "partial", + "deadline_expired", + ), + ( + FetchTargetState::Unavailable, + AvailabilityDiscoveryStopReason::None, + "unavailable", + "none", + ), + ( + FetchTargetState::FailedRetryable, + AvailabilityDiscoveryStopReason::None, + "failed_retryable", + "none", + ), + ( + FetchTargetState::FailedTerminal, + AvailabilityDiscoveryStopReason::None, + "failed_terminal", + "none", + ), + ( + FetchTargetState::Cancelled, + AvailabilityDiscoveryStopReason::Stopped, + "cancelled", + "stopped", + ), + ] { + let value = AvailabilityDiscoveryOutcome::new( + request(vec![fingerprint(1)]), + usage(1, 0), + vec![target( + fingerprint(1), + progress(state, reason, 0), + not_requested(), + not_requested(), + )], + Vec::<u8>::new(), + ) + .expect("every exact metadata state spelling"); + assert!(value.metadata_json().contains(&format!( + "\"listings\":{{\"state\":\"{name}\",\"reason\":\"{reason_name}\",\"returned\":0}}" + ))); + } +} + +#[test] +fn diagnostics_omit_private_payloads_and_remote_messages() { + struct PrivateItem(&'static str); + const PRIVATE_MARKER: &str = "HCAV_PRIVATE_PAYLOAD_MARKER"; + const REMOTE_MARKER: &str = "HCAV_HOSTILE_REMOTE_MESSAGE_\"\n\0🥕"; + let shared = FetchTargetOutcome::new(fingerprint(0xab), FetchTargetState::FailedRetryable) + .with_message(REMOTE_MARKER); + assert_eq!(shared.message(), Some(REMOTE_MARKER)); + let stage = progress(shared.state(), AvailabilityDiscoveryStopReason::None, 1); + let target_value = target( + shared.target().clone(), + stage, + not_requested(), + not_requested(), + ); + let target_debug = format!("{target_value:?}"); + let requested = request(vec![shared.target().clone()]); + let request_debug = format!("{requested:?}"); + let value = AvailabilityDiscoveryOutcome::new( + requested, + usage(1, 1), + vec![target_value], + vec![PrivateItem(PRIVATE_MARKER)], + ) + .expect("retains only selected shared identity/state facts"); + assert_eq!(value.items()[0].0, PRIVATE_MARKER); + let context_bytes = format!("{:?}", [1_u8; 32]); + let store_bytes = format!("{:?}", [2_u8; 32]); + for diagnostic in [ + request_debug, + target_debug, + format!("{value:?}"), + format!("{stage:?}"), + ] { + for forbidden in [ + PRIVATE_MARKER, + "HCAV_HOSTILE_REMOTE_MESSAGE_", + AUTHOR_HEX, + context_bytes.as_str(), + store_bytes.as_str(), + shared.target().as_str(), + "RequestId", + "request_id", + ] { + assert!(!diagnostic.contains(forbidden)); + } + } + let json = value.metadata_json(); + assert!( + json.contains(shared.target().as_str()), + "metadata admits only the bounded canonical public target identity" + ); + for forbidden in [ + PRIVATE_MARKER, + "HCAV_HOSTILE_REMOTE_MESSAGE_", + AUTHOR_HEX, + "request_id", + "context_id", + "store_generation", + "scope", + "message", + "endpoint", + "\"events\":", + "payload", + ] { + assert!(!json.contains(forbidden)); + } +} + +#[test] +fn query_errors_map_to_static_distinct_availability_errors() { + for (source, expected_code, expected_message) in [ + ( + AvailabilityQueryError::InvalidInput, + SafeErrorCode::AvailabilityInvalidInput, + "The availability request is invalid.", + ), + ( + AvailabilityQueryError::InputTooLarge, + SafeErrorCode::AvailabilityInvalidInput, + "The availability request is invalid.", + ), + ( + AvailabilityQueryError::ScopeMismatch, + SafeErrorCode::AvailabilityScopeMismatch, + "The availability request belongs to another scope.", + ), + ( + AvailabilityQueryError::StaleQuery, + SafeErrorCode::AvailabilityStaleQuery, + "The availability query is stale.", + ), + ( + AvailabilityQueryError::Capacity, + SafeErrorCode::AvailabilityCapacity, + "The availability operation reached its capacity.", + ), + ] { + let value = SafeError::from(source); + assert_eq!(value.code(), expected_code); + assert_eq!(value.message().as_str(), expected_message); + assert_eq!(value.to_string(), expected_message); + } +} + +#[test] +fn availability_failures_have_fixed_public_messages() { + for (source, expected_code, expected_message) in [ + ( + AvailabilityFailure::InvalidInput, + SafeErrorCode::AvailabilityInvalidInput, + "The availability request is invalid.", + ), + ( + AvailabilityFailure::UnsupportedProfile, + SafeErrorCode::AvailabilityUnsupportedProfile, + "This availability profile is unsupported.", + ), + ( + AvailabilityFailure::ScopeMismatch, + SafeErrorCode::AvailabilityScopeMismatch, + "The availability request belongs to another scope.", + ), + ( + AvailabilityFailure::StaleQuery, + SafeErrorCode::AvailabilityStaleQuery, + "The availability query is stale.", + ), + ( + AvailabilityFailure::Capacity, + SafeErrorCode::AvailabilityCapacity, + "The availability operation reached its capacity.", + ), + ( + AvailabilityFailure::Unavailable, + SafeErrorCode::AvailabilityUnavailable, + "Availability discovery is unavailable.", + ), + ] { + let value = SafeError::from(source); + assert_eq!(value.code(), expected_code); + assert_eq!(value.message().as_str(), expected_message); + assert_eq!(value.to_string(), expected_message); + assert!(!format!("{value:?}").contains("HCAV_HOSTILE_REMOTE_MESSAGE")); + let copied = value; + assert_eq!(copied, value); + let standard_error: &dyn Error = &value; + assert!(standard_error.source().is_none()); + } +} diff --git a/core/crates/harvestcircle_domain/src/error.rs b/core/crates/harvestcircle_domain/src/error.rs @@ -24,6 +24,23 @@ pub enum SafeErrorCode { ProfileRefreshFailed, ObserverRegistrationFailed, NativeLibraryLoadFailed, + AvailabilityInvalidInput, + AvailabilityUnsupportedProfile, + AvailabilityScopeMismatch, + AvailabilityStaleQuery, + AvailabilityCapacity, + AvailabilityUnavailable, +} + +/// Finite availability failures with fixed public diagnostic messages. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum AvailabilityFailure { + InvalidInput, + UnsupportedProfile, + ScopeMismatch, + StaleQuery, + Capacity, + Unavailable, } #[derive(Clone, Copy, Eq, PartialEq)] @@ -94,6 +111,54 @@ impl Display for SafeError { impl Error for SafeError {} +impl From<AvailabilityFailure> for SafeError { + fn from(failure: AvailabilityFailure) -> Self { + let (code, message) = match failure { + AvailabilityFailure::InvalidInput => ( + SafeErrorCode::AvailabilityInvalidInput, + "The availability request is invalid.", + ), + AvailabilityFailure::UnsupportedProfile => ( + SafeErrorCode::AvailabilityUnsupportedProfile, + "This availability profile is unsupported.", + ), + AvailabilityFailure::ScopeMismatch => ( + SafeErrorCode::AvailabilityScopeMismatch, + "The availability request belongs to another scope.", + ), + AvailabilityFailure::StaleQuery => ( + SafeErrorCode::AvailabilityStaleQuery, + "The availability query is stale.", + ), + AvailabilityFailure::Capacity => ( + SafeErrorCode::AvailabilityCapacity, + "The availability operation reached its capacity.", + ), + AvailabilityFailure::Unavailable => ( + SafeErrorCode::AvailabilityUnavailable, + "Availability discovery is unavailable.", + ), + }; + Self::new(code, SafeMessage::new(message)) + } +} + +impl From<crate::AvailabilityQueryError> for SafeError { + fn from(error: crate::AvailabilityQueryError) -> Self { + use crate::AvailabilityQueryError; + + let failure = match error { + AvailabilityQueryError::InvalidInput | AvailabilityQueryError::InputTooLarge => { + AvailabilityFailure::InvalidInput + } + AvailabilityQueryError::ScopeMismatch => AvailabilityFailure::ScopeMismatch, + AvailabilityQueryError::StaleQuery => AvailabilityFailure::StaleQuery, + AvailabilityQueryError::Capacity => AvailabilityFailure::Capacity, + }; + failure.into() + } +} + #[cfg(test)] mod tests { use super::{SafeError, SafeErrorCode, SafeMessage}; @@ -110,4 +175,73 @@ mod tests { assert_eq!(error.message().as_str(), "The secret key is invalid."); assert!(!format!("{error:?}").contains("nsec1unsafe-test-value")); } + + #[test] + fn availability_failures_and_query_errors_are_static() { + use super::AvailabilityFailure; + use crate::AvailabilityQueryError; + + for (failure, code, message) in [ + ( + AvailabilityFailure::InvalidInput, + SafeErrorCode::AvailabilityInvalidInput, + "The availability request is invalid.", + ), + ( + AvailabilityFailure::UnsupportedProfile, + SafeErrorCode::AvailabilityUnsupportedProfile, + "This availability profile is unsupported.", + ), + ( + AvailabilityFailure::ScopeMismatch, + SafeErrorCode::AvailabilityScopeMismatch, + "The availability request belongs to another scope.", + ), + ( + AvailabilityFailure::StaleQuery, + SafeErrorCode::AvailabilityStaleQuery, + "The availability query is stale.", + ), + ( + AvailabilityFailure::Capacity, + SafeErrorCode::AvailabilityCapacity, + "The availability operation reached its capacity.", + ), + ( + AvailabilityFailure::Unavailable, + SafeErrorCode::AvailabilityUnavailable, + "Availability discovery is unavailable.", + ), + ] { + let error = SafeError::from(failure); + assert_eq!(error.code(), code); + assert_eq!(error.message().as_str(), message); + assert_eq!(error.to_string(), message); + assert!(!format!("{error:?}").contains("HCAV_PRIVATE_REMOTE_PAYLOAD")); + } + for (query, code) in [ + ( + AvailabilityQueryError::InvalidInput, + SafeErrorCode::AvailabilityInvalidInput, + ), + ( + AvailabilityQueryError::InputTooLarge, + SafeErrorCode::AvailabilityInvalidInput, + ), + ( + AvailabilityQueryError::ScopeMismatch, + SafeErrorCode::AvailabilityScopeMismatch, + ), + ( + AvailabilityQueryError::StaleQuery, + SafeErrorCode::AvailabilityStaleQuery, + ), + ( + AvailabilityQueryError::Capacity, + SafeErrorCode::AvailabilityCapacity, + ), + ] { + assert_eq!(SafeError::from(query).code(), code); + } + } } diff --git a/core/crates/harvestcircle_ffi/build.rs b/core/crates/harvestcircle_ffi/build.rs @@ -216,7 +216,7 @@ fn validate_baseline_inputs(baseline: &BTreeMap<String, String>) { "harvestcircle-desktop-ffi-v4" ); assert_eq!(required(baseline, "contract.major"), "4"); - assert_eq!(required(baseline, "contract.minor"), "3"); + assert_eq!(required(baseline, "contract.minor"), "4"); assert_eq!(required(baseline, "snapshot.schema"), "1"); assert_eq!(required(baseline, "storage.schema.minimum"), "1"); assert_eq!(required(baseline, "storage.schema.current"), "2"); diff --git a/core/crates/harvestcircle_ffi/src/contract.rs b/core/crates/harvestcircle_ffi/src/contract.rs @@ -2,7 +2,7 @@ pub const FFI_CONTRACT_ID: &str = env!("HARVESTCIRCLE_FFI_CONTRACT_ID"); pub const PRODUCT_VERSION: &str = env!("HARVESTCIRCLE_PRODUCT_VERSION"); pub const DISTRIBUTION_PACKAGE_VERSION: &str = env!("HARVESTCIRCLE_PACKAGE_VERSION"); pub const FFI_CONTRACT_MAJOR: u16 = 4; -pub const FFI_CONTRACT_MINOR: u16 = 3; +pub const FFI_CONTRACT_MINOR: u16 = 4; pub const PRODUCT_COORDINATE_DIGEST: &str = env!("HARVESTCIRCLE_PRODUCT_COORDINATE_DIGEST"); pub const SNAPSHOT_SCHEMA_VERSION: u32 = 1; pub const MINIMUM_SCHEMA_VERSION: u32 = 1; diff --git a/core/crates/harvestcircle_ffi/src/dto.rs b/core/crates/harvestcircle_ffi/src/dto.rs @@ -79,6 +79,12 @@ pub enum WireErrorCode { NativeLibraryLoadFailed, CompatibilityMismatch, Internal, + AvailabilityInvalidInput, + AvailabilityUnsupportedProfile, + AvailabilityScopeMismatch, + AvailabilityStaleQuery, + AvailabilityCapacity, + AvailabilityUnavailable, } #[derive(Clone, Copy, Debug, Eq, PartialEq)] @@ -427,6 +433,12 @@ impl From<SafeErrorCode> for WireErrorCode { SafeErrorCode::ProfileRefreshFailed => Self::ProfileRefreshFailed, SafeErrorCode::ObserverRegistrationFailed => Self::ObserverRegistrationFailed, SafeErrorCode::NativeLibraryLoadFailed => Self::NativeLibraryLoadFailed, + SafeErrorCode::AvailabilityInvalidInput => Self::AvailabilityInvalidInput, + SafeErrorCode::AvailabilityUnsupportedProfile => Self::AvailabilityUnsupportedProfile, + SafeErrorCode::AvailabilityScopeMismatch => Self::AvailabilityScopeMismatch, + SafeErrorCode::AvailabilityStaleQuery => Self::AvailabilityStaleQuery, + SafeErrorCode::AvailabilityCapacity => Self::AvailabilityCapacity, + SafeErrorCode::AvailabilityUnavailable => Self::AvailabilityUnavailable, } } } @@ -502,6 +514,25 @@ pub(crate) const fn error_policy( false, WireRecoveryAction::RestartApplication, ), + SafeErrorCode::AvailabilityInvalidInput => { + (WireErrorCategory::Input, false, WireRecoveryAction::None) + } + SafeErrorCode::AvailabilityUnsupportedProfile => ( + WireErrorCategory::Compatibility, + false, + WireRecoveryAction::None, + ), + SafeErrorCode::AvailabilityScopeMismatch | SafeErrorCode::AvailabilityStaleQuery => { + (WireErrorCategory::Conflict, false, WireRecoveryAction::None) + } + SafeErrorCode::AvailabilityCapacity => ( + WireErrorCategory::Lifecycle, + true, + WireRecoveryAction::Retry, + ), + SafeErrorCode::AvailabilityUnavailable => { + (WireErrorCategory::Network, true, WireRecoveryAction::Retry) + } } } @@ -696,6 +727,30 @@ mod tests { SafeErrorCode::NativeLibraryLoadFailed, WireErrorCode::NativeLibraryLoadFailed, ), + ( + SafeErrorCode::AvailabilityInvalidInput, + WireErrorCode::AvailabilityInvalidInput, + ), + ( + SafeErrorCode::AvailabilityUnsupportedProfile, + WireErrorCode::AvailabilityUnsupportedProfile, + ), + ( + SafeErrorCode::AvailabilityScopeMismatch, + WireErrorCode::AvailabilityScopeMismatch, + ), + ( + SafeErrorCode::AvailabilityStaleQuery, + WireErrorCode::AvailabilityStaleQuery, + ), + ( + SafeErrorCode::AvailabilityCapacity, + WireErrorCode::AvailabilityCapacity, + ), + ( + SafeErrorCode::AvailabilityUnavailable, + WireErrorCode::AvailabilityUnavailable, + ), ]; for (code, expected_wire_code) in cases { let dto = SafeErrorDto::from(safe_error(code)); @@ -825,4 +880,69 @@ mod tests { assert_eq!(ProfileLoadStateDto::from(source), expected); } } + + #[test] + fn availability_errors_have_exact_wire_codes_and_recovery_policy() { + use harvestcircle_domain::error::AvailabilityFailure; + + for (failure, code, category, retryable, recovery, message) in [ + ( + AvailabilityFailure::InvalidInput, + WireErrorCode::AvailabilityInvalidInput, + WireErrorCategory::Input, + false, + WireRecoveryAction::None, + "The availability request is invalid.", + ), + ( + AvailabilityFailure::UnsupportedProfile, + WireErrorCode::AvailabilityUnsupportedProfile, + WireErrorCategory::Compatibility, + false, + WireRecoveryAction::None, + "This availability profile is unsupported.", + ), + ( + AvailabilityFailure::ScopeMismatch, + WireErrorCode::AvailabilityScopeMismatch, + WireErrorCategory::Conflict, + false, + WireRecoveryAction::None, + "The availability request belongs to another scope.", + ), + ( + AvailabilityFailure::StaleQuery, + WireErrorCode::AvailabilityStaleQuery, + WireErrorCategory::Conflict, + false, + WireRecoveryAction::None, + "The availability query is stale.", + ), + ( + AvailabilityFailure::Capacity, + WireErrorCode::AvailabilityCapacity, + WireErrorCategory::Lifecycle, + true, + WireRecoveryAction::Retry, + "The availability operation reached its capacity.", + ), + ( + AvailabilityFailure::Unavailable, + WireErrorCode::AvailabilityUnavailable, + WireErrorCategory::Network, + true, + WireRecoveryAction::Retry, + "Availability discovery is unavailable.", + ), + ] { + let dto = SafeErrorDto::from(SafeError::from(failure)); + assert_eq!(dto.code, code); + assert_eq!( + (dto.category, dto.retryable, dto.recovery_action), + (category, retryable, recovery) + ); + assert_eq!(dto.message, message); + assert!(!format!("{dto:?}").contains("HCAV_PRIVATE_REMOTE_PAYLOAD")); + } + } } diff --git a/core/crates/harvestcircle_ffi/src/lib.rs b/core/crates/harvestcircle_ffi/src/lib.rs @@ -60,7 +60,7 @@ mod tests { assert_eq!(env!("CARGO_PKG_VERSION"), "0.1.0-alpha"); assert_eq!(super::FFI_CONTRACT_ID, "harvestcircle-desktop-ffi-v4"); assert_eq!(super::FFI_CONTRACT_MAJOR, 4); - assert_eq!(super::FFI_CONTRACT_MINOR, 3); + assert_eq!(super::FFI_CONTRACT_MINOR, 4); assert_eq!(super::SNAPSHOT_SCHEMA_VERSION, 1); assert_eq!( super::PRODUCT_COORDINATE_DIGEST, diff --git a/radroots.lib.source-lock.v1.toml b/radroots.lib.source-lock.v1.toml @@ -6,4 +6,4 @@ workspace_catalog_sha256 = "ee295f2352e2577a4052d980624415aec9871197d4fc9910a4c2 version = "0.1.0-alpha" source_archive_sha256 = "c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240" lockfile = "core/Cargo.lock" -lockfile_sha256 = "8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6" +lockfile_sha256 = "3adc3bd3370fcb21821fd7e9be45554258e89088a791781a798fc39a4bdfcc31" diff --git a/tools/xtask/src/lib.rs b/tools/xtask/src/lib.rs @@ -1159,7 +1159,7 @@ fn provenance_check(root: &Path, inventory: &Inventory, findings: &mut Vec<Strin "version = \"0.1.0-alpha\"\n", "source_archive_sha256 = \"c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240\"\n", "lockfile = \"core/Cargo.lock\"\n", - "lockfile_sha256 = \"8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6\"\n", + "lockfile_sha256 = \"3adc3bd3370fcb21821fd7e9be45554258e89088a791781a798fc39a4bdfcc31\"\n", ); let source_lock_bytes = match bounded_no_follow_bytes(root, Path::new(SOURCE_LOCK_PATH), MAX_SOURCE_LOCK_BYTES) { @@ -2434,7 +2434,7 @@ mod tests { "version = \"0.1.0-alpha\"\n", "source_archive_sha256 = \"c648a3ab993d10253b9073e7e86db7b8970863bdf1d394d9fc30d66825695240\"\n", "lockfile = \"core/Cargo.lock\"\n", - "lockfile_sha256 = \"8f31db666b29a3864a006d318e44e14c246f7aeda60921f56f914de9dca62ed6\"\n", + "lockfile_sha256 = \"3adc3bd3370fcb21821fd7e9be45554258e89088a791781a798fc39a4bdfcc31\"\n", ), ); write(&root, "core/Cargo.toml", "");