Struct LockObservation

Source

pub struct LockObservation { /* private fields */ }

Expand description

A bounded, read-only observation of one exact lock record.

This is the only evidence Core can prove about a record: the path, its exact bounded bytes, and whatever the known record format yields. There is no process liveness, age, or executable fact here, and none is inferred from the pathname.

Field values are exposed through accessors rather than public fields so the record format can stay an implementation detail.

Implementations§

Source §

impl LockObservation

Source

pub fn path(&self) -> &Path

Returns the observed lock record path.

Source

pub fn record(&self) -> &str

Returns the exact bounded record identity that was observed.

Recovery is authorized against this value, not against the pathname: if the object at the path changes, the authorization no longer applies.

Source

pub fn pid(&self) -> Option<u32>

Returns the recorded process id, when the known format supplies one.

This is a fact about the record, not about the current process table. Core never uses it as proof of staleness.

Examples found in repository ?

examples/stale_lock_recovery.rs (line 68)

57    fn classify(&self, observed: &LockObservation) -> StaleLockDecision {
58        // The record must belong to this consumer's domain before its fields
59        // mean anything. Core observed the bytes; attributing them is the
60        // caller's job.
61        if observed.product() != Some(self.evidence.product.as_str()) {
62            return StaleLockDecision::Unknown;
63        }
64        // An unrecognised record format carries no attributable evidence.
65        if !observed.format_known() {
66            return StaleLockDecision::Unknown;
67        }
68        let Some(pid) = observed.pid() else {
69            return StaleLockDecision::Unknown;
70        };
71        // A supervised process this consumer can still see is plainly active.
72        if self.evidence.alive.contains(&pid) {
73            return StaleLockDecision::Active;
74        }
75        // A pid this consumer never supervised is ambiguous: the number may now
76        // belong to an unrelated process entirely.
77        if !self.evidence.supervised.contains(&pid) {
78            return StaleLockDecision::Unknown;
79        }
80        // Conclusive only with the deployment's own out-of-band statement.
81        if self.evidence.declared_idle {
82            StaleLockDecision::ProvenStale
83        } else {
84            StaleLockDecision::Unknown
85        }
86    }

Source

pub fn nonce(&self) -> Option<u64>

Returns the recorded per-process nonce, when the known format supplies one.

Source

pub fn product(&self) -> Option<&str>

Returns the recorded product identity, when the known format supplies one.

Examples found in repository ?

examples/stale_lock_recovery.rs (line 61)

57    fn classify(&self, observed: &LockObservation) -> StaleLockDecision {
58        // The record must belong to this consumer's domain before its fields
59        // mean anything. Core observed the bytes; attributing them is the
60        // caller's job.
61        if observed.product() != Some(self.evidence.product.as_str()) {
62            return StaleLockDecision::Unknown;
63        }
64        // An unrecognised record format carries no attributable evidence.
65        if !observed.format_known() {
66            return StaleLockDecision::Unknown;
67        }
68        let Some(pid) = observed.pid() else {
69            return StaleLockDecision::Unknown;
70        };
71        // A supervised process this consumer can still see is plainly active.
72        if self.evidence.alive.contains(&pid) {
73            return StaleLockDecision::Active;
74        }
75        // A pid this consumer never supervised is ambiguous: the number may now
76        // belong to an unrelated process entirely.
77        if !self.evidence.supervised.contains(&pid) {
78            return StaleLockDecision::Unknown;
79        }
80        // Conclusive only with the deployment's own out-of-band statement.
81        if self.evidence.declared_idle {
82            StaleLockDecision::ProvenStale
83        } else {
84            StaleLockDecision::Unknown
85        }
86    }

Source

pub fn release(&self) -> Option<&str>

Returns the recorded release identity, when the known format supplies one.

Source

pub fn format_known(&self) -> bool

Returns whether the record matched the known bounded format.

A record from an older or unknown format is still observable and still byte-identifiable, but it carries no parsed evidence, so a caller that needs fields cannot prove staleness from it.

Examples found in repository ?

examples/stale_lock_recovery.rs (line 65)

57    fn classify(&self, observed: &LockObservation) -> StaleLockDecision {
58        // The record must belong to this consumer's domain before its fields
59        // mean anything. Core observed the bytes; attributing them is the
60        // caller's job.
61        if observed.product() != Some(self.evidence.product.as_str()) {
62            return StaleLockDecision::Unknown;
63        }
64        // An unrecognised record format carries no attributable evidence.
65        if !observed.format_known() {
66            return StaleLockDecision::Unknown;
67        }
68        let Some(pid) = observed.pid() else {
69            return StaleLockDecision::Unknown;
70        };
71        // A supervised process this consumer can still see is plainly active.
72        if self.evidence.alive.contains(&pid) {
73            return StaleLockDecision::Active;
74        }
75        // A pid this consumer never supervised is ambiguous: the number may now
76        // belong to an unrelated process entirely.
77        if !self.evidence.supervised.contains(&pid) {
78            return StaleLockDecision::Unknown;
79        }
80        // Conclusive only with the deployment's own out-of-band statement.
81        if self.evidence.declared_idle {
82            StaleLockDecision::ProvenStale
83        } else {
84            StaleLockDecision::Unknown
85        }
86    }