Skip to main content

object_log/blob/
authority.rs

1//! Strict metadata authority. Legacy whole-object operations are not fallbacks.
2use super::*;
3use crate::AppendOwner;
4use std::os::unix::fs::MetadataExt;
5
6#[cfg(test)]
7pub(crate) struct LocalMetadataHook {
8    entered: std::sync::mpsc::Sender<()>,
9    release: Mutex<std::sync::mpsc::Receiver<()>>,
10    panic: bool,
11}
12#[cfg(test)]
13impl LocalBlobStore {
14    pub(crate) fn take_metadata_swap_calls(&self) -> u64 {
15        self.authority_swap_calls.swap(0, Ordering::Relaxed)
16    }
17    pub(crate) fn lose_next_metadata_reply(&self, key: &str) {
18        *self.authority_lost_reply.lock().unwrap() = Some(key.to_owned());
19    }
20    pub(crate) fn pause_metadata_swap(
21        &self,
22        panic: bool,
23    ) -> (std::sync::mpsc::Receiver<()>, std::sync::mpsc::Sender<()>) {
24        let (entered, started) = std::sync::mpsc::channel();
25        let (release, wait) = std::sync::mpsc::channel();
26        *self.authority_hook.lock().unwrap() = Some(Arc::new(LocalMetadataHook {
27            entered,
28            release: Mutex::new(wait),
29            panic,
30        }));
31        (started, release)
32    }
33}
34
35#[derive(Clone, Debug, PartialEq, Eq)]
36pub(crate) struct LocalVersion {
37    device: u64,
38    inode: u64,
39    size: u64,
40    modified: (i64, i64),
41    changed: (i64, i64),
42}
43impl From<&std::fs::Metadata> for LocalVersion {
44    fn from(value: &std::fs::Metadata) -> Self {
45        Self {
46            device: value.dev(),
47            inode: value.ino(),
48            size: value.len(),
49            modified: (value.mtime(), value.mtime_nsec()),
50            changed: (value.ctime(), value.ctime_nsec()),
51        }
52    }
53}
54#[derive(Clone, Debug, PartialEq, Eq)]
55pub(crate) enum MetadataVersion {
56    Local(Option<LocalVersion>),
57    #[cfg(feature = "s3")]
58    S3(Option<String>),
59}
60/// Separate ownership of in-flight physical work and retained observation bytes.
61/// Returned snapshots retain only `retained`; upload/request sources retain both.
62#[derive(Clone)]
63pub struct MetadataOwners {
64    /// Keeps payload/key/version allocation admission through last observation.
65    pub retained: AppendOwner,
66    /// Keeps operation admission through actual request/source completion.
67    pub physical: AppendOwner,
68}
69impl MetadataOwners {
70    #[cfg(feature = "s3")]
71    pub(crate) fn source(&self) -> AppendOwner {
72        Arc::new(self.clone())
73    }
74}
75/// An opaque observation binding one adapter instance, literal key and version.
76/// Payload ownership remains with the snapshot; callers reserve payload, key,
77/// token and transport scratch before invoking the physical operation.
78#[derive(Clone)]
79pub struct MetadataSnapshot {
80    pub(crate) inner: Arc<MetadataObservation>,
81}
82pub(crate) struct MetadataObservation {
83    pub(crate) owner: Arc<()>,
84    pub(crate) key: String,
85    pub(crate) bytes: Option<Bytes>,
86    pub(crate) version: MetadataVersion,
87    // Last: release payload/key/version allocations before their lifetime owner.
88    pub(crate) _retained: AppendOwner,
89}
90impl std::fmt::Debug for MetadataSnapshot {
91    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
92        f.debug_struct("MetadataSnapshot")
93            .field("key", &self.inner.key)
94            .field("payload_bytes", &self.inner.bytes.as_ref().map(Bytes::len))
95            .field("version", &self.inner.version)
96            .finish_non_exhaustive()
97    }
98}
99impl MetadataSnapshot {
100    /// Exact borrowed bytes, or absence. Cloning the snapshot retains its owner;
101    /// raw Bytes aliases cannot escape that lifetime through this accessor.
102    ///
103    /// ```
104    /// use object_log::MetadataSnapshot;
105    /// fn borrow(snapshot: &MetadataSnapshot) -> Option<&[u8]> { snapshot.bytes() }
106    /// ```
107    /// ```compile_fail
108    /// use object_log::MetadataSnapshot;
109    /// fn escape(snapshot: MetadataSnapshot) -> bytes::Bytes {
110    ///     snapshot.bytes().unwrap().clone()
111    /// }
112    /// ```
113    pub fn bytes(&self) -> Option<&[u8]> {
114        self.inner.bytes.as_deref()
115    }
116    pub(crate) fn validate(&self, owner: &Arc<()>, key: &str) -> Result<(), ObjectLogError> {
117        if !Arc::ptr_eq(&self.inner.owner, owner) || self.inner.key != key {
118            return Err(ObjectLogError::InvalidConfig(
119                "metadata token belongs to another provider or literal key".into(),
120            ));
121        }
122        Ok(())
123    }
124}
125/// A definite metadata conditional-write outcome. Transport errors can follow
126/// durable publication and must never be interpreted as definite rejection.
127#[derive(Debug)]
128pub enum MetadataSwap {
129    /// The proposed bytes were durably stored. The snapshot is exactly what was
130    /// stored, carrying the new version token, so a caller can issue its next
131    /// conditional write without rereading.
132    Stored(MetadataSnapshot),
133    /// The observed version did not match; contains a bounded fresh observation.
134    Conflict(MetadataSnapshot),
135}
136/// Explicit source-memory limits for both reads and conditional writes.
137/// Transport/header-parser allocations require separate qualification.
138#[derive(Clone, Copy, Debug, PartialEq, Eq)]
139pub struct MetadataLimits {
140    /// Maximum complete payload bytes, including conflict observations.
141    pub payload_bytes: usize,
142    /// Maximum opaque version-token bytes. Tokens are preserved verbatim.
143    /// Local metadata needs 56 bytes for its fixed version identity.
144    pub version_bytes: usize,
145}
146impl MetadataLimits {
147    pub(crate) fn validate(self) -> Result<(), ObjectLogError> {
148        if self.payload_bytes == 0 || self.version_bytes == 0 {
149            return Err(ObjectLogError::InvalidConfig(
150                "metadata source limit is zero".into(),
151            ));
152        }
153        Ok(())
154    }
155    pub(crate) fn validate_local(self) -> Result<(), ObjectLogError> {
156        self.validate()?;
157        if self.version_bytes < 56 {
158            return Err(ObjectLogError::BudgetExceeded(
159                "local metadata version exceeds admitted bound".into(),
160            ));
161        }
162        Ok(())
163    }
164}
165/// Required bounded authority operations, independent of legacy BlobStore.
166/// There are deliberately no default implementations. `limits` bounds every
167/// retained payload and token, including conflict observations; transport/header and
168/// operation ownership require separate caller admission. Cancellation does not
169/// prove a conditional write had no effects. Owners must drive and drain it.
170/// Input/output source buffers retain the supplied lifetime owner. This does not
171/// attest to all SDK transport allocations or provider-side effects after an
172/// ambiguous request; those require separate transport/durability qualification.
173#[async_trait]
174pub trait BoundedMetadataStore: Send + Sync {
175    /// Read one complete object within the admitted bound, with an opaque CAS
176    /// token. Oversize/malformed responses fail before whole-body collection.
177    async fn read_metadata(
178        &self,
179        key: &str,
180        limits: MetadataLimits,
181        owners: MetadataOwners,
182    ) -> Result<MetadataSnapshot, ObjectLogError>;
183    /// Conditional durable replacement of exactly the observed provider/key/
184    /// version. No automatic conditional-write retry. Oversized input is rejected
185    /// before I/O; failed conflict rereads are errors, never definite rejection.
186    async fn swap_metadata(
187        &self,
188        key: &str,
189        observed: MetadataSnapshot,
190        new_value: Bytes,
191        limits: MetadataLimits,
192        owners: MetadataOwners,
193    ) -> Result<MetadataSwap, ObjectLogError>;
194}
195pub(crate) fn validate_budget(max_bytes: usize, size: usize) -> Result<(), ObjectLogError> {
196    if max_bytes == 0 {
197        return Err(ObjectLogError::InvalidConfig(
198            "metadata budget is zero".into(),
199        ));
200    }
201    if size > max_bytes {
202        return Err(ObjectLogError::BudgetExceeded(
203            "metadata exceeds admitted payload bound".into(),
204        ));
205    }
206    Ok(())
207}
208fn read_local(
209    path: &Path,
210    owner: Arc<()>,
211    key: String,
212    max_bytes: usize,
213    retained: AppendOwner,
214) -> Result<MetadataSnapshot, ObjectLogError> {
215    let mut file = match std::fs::File::open(path) {
216        Ok(file) => file,
217        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
218            return Ok(MetadataSnapshot {
219                inner: Arc::new(crate::blob::authority::MetadataObservation {
220                    _retained: retained,
221                    owner,
222                    key,
223                    bytes: None,
224                    version: MetadataVersion::Local(None),
225                }),
226            });
227        }
228        Err(error) => return Err(error.into()),
229    };
230    let metadata = file.metadata()?;
231    if !metadata.is_file() {
232        return Err(ObjectLogError::StorageUnavailable(
233            "metadata is not a file".into(),
234        ));
235    }
236    let size = usize::try_from(metadata.len())
237        .map_err(|_| ObjectLogError::BudgetExceeded("metadata exceeds address space".into()))?;
238    validate_budget(max_bytes, size)?;
239    let version = LocalVersion::from(&metadata);
240    let mut bytes = vec![0; size];
241    file.read_exact(&mut bytes)?;
242    let mut extra = [0];
243    if file.read(&mut extra)? != 0 || LocalVersion::from(&file.metadata()?) != version {
244        return Err(ObjectLogError::StorageUnavailable(
245            "metadata changed during read".into(),
246        ));
247    }
248    Ok(MetadataSnapshot {
249        inner: Arc::new(crate::blob::authority::MetadataObservation {
250            _retained: retained,
251            owner,
252            key,
253            bytes: Some(Bytes::from(bytes)),
254            version: MetadataVersion::Local(Some(version)),
255        }),
256    })
257}
258impl LocalBlobStore {
259    /// An observation of absence made without I/O. A conditional write against it
260    /// is create-only: it conflicts, with the current object, if the key exists.
261    pub(crate) fn absent_metadata(&self, key: &str, retained: AppendOwner) -> MetadataSnapshot {
262        MetadataSnapshot {
263            inner: Arc::new(MetadataObservation {
264                _retained: retained,
265                owner: Arc::clone(&self.authority_identity),
266                key: key.to_owned(),
267                bytes: None,
268                version: MetadataVersion::Local(None),
269            }),
270        }
271    }
272}
273#[async_trait]
274impl BoundedMetadataStore for LocalBlobStore {
275    async fn read_metadata(
276        &self,
277        key: &str,
278        limits: MetadataLimits,
279        owners: MetadataOwners,
280    ) -> Result<MetadataSnapshot, ObjectLogError> {
281        limits.validate_local()?;
282        let max_bytes = limits.payload_bytes;
283        let path = self.path_for(key)?;
284        let physical = owners;
285        let owner = Arc::clone(&self.authority_identity);
286        let key = key.to_owned();
287        tokio::task::spawn_blocking(move || {
288            let _physical = physical;
289            let path = path;
290            read_local(
291                &path,
292                owner,
293                key,
294                max_bytes,
295                Arc::clone(&_physical.retained),
296            )
297        })
298        .await
299        .map_err(|error| ObjectLogError::StorageUnavailable(error.to_string()))?
300    }
301    async fn swap_metadata(
302        &self,
303        key: &str,
304        observed: MetadataSnapshot,
305        new_value: Bytes,
306        limits: MetadataLimits,
307        owners: MetadataOwners,
308    ) -> Result<MetadataSwap, ObjectLogError> {
309        #[cfg(test)]
310        self.authority_swap_calls.fetch_add(1, Ordering::Relaxed);
311        limits.validate_local()?;
312        let max_bytes = limits.payload_bytes;
313        observed.validate(&self.authority_identity, key)?;
314        validate_budget(max_bytes, new_value.len())?;
315        validate_budget(
316            max_bytes,
317            observed.inner.bytes.as_ref().map_or(0, Bytes::len),
318        )?;
319        #[cfg(test)]
320        let lose_reply = {
321            let mut requested = self.authority_lost_reply.lock().unwrap();
322            if requested.as_deref() == Some(key) {
323                requested.take();
324                true
325            } else {
326                false
327            }
328        };
329        let path = self.path_for(key)?;
330        let physical = owners;
331        let owner = Arc::clone(&self.authority_identity);
332        let key = key.to_owned();
333        let size = new_value.len() as u64;
334        #[cfg(test)]
335        let hook = self.authority_hook.lock().unwrap().take();
336        let result =
337            tokio::task::spawn_blocking(move || -> Result<MetadataSwap, ObjectLogError> {
338                let _physical = physical;
339                let path = path;
340                let key = key;
341                let observed = observed;
342                let new_value = new_value;
343                if let Some(parent) = path.parent() {
344                    std::fs::create_dir_all(parent)?;
345                }
346                let mut lock_name = path.as_os_str().to_os_string();
347                lock_name.push(".caslock");
348                let lock = std::fs::OpenOptions::new()
349                    .create(true)
350                    .truncate(false)
351                    .read(true)
352                    .write(true)
353                    .open(lock_name)?;
354                flock_exclusive(&lock)?;
355                // Closing the file releases flock on every error/panic path.
356                let current = read_local(
357                    &path,
358                    owner,
359                    key.clone(),
360                    max_bytes,
361                    Arc::clone(&_physical.retained),
362                )?;
363                if current.inner.version != observed.inner.version
364                    || current.inner.bytes != observed.inner.bytes
365                {
366                    return Ok(MetadataSwap::Conflict(current));
367                }
368                #[cfg(test)]
369                if let Some(hook) = hook {
370                    hook.entered.send(()).unwrap();
371                    hook.release.lock().unwrap().recv().unwrap();
372                    assert!(!hook.panic, "injected physical metadata panic");
373                }
374                let stored = new_value.clone();
375                LocalBlobStore::durable_publish_chunks(path.clone(), vec![new_value], &key)?;
376                // Still under the CAS lock: this stat is the version a reread would see.
377                let version = LocalVersion::from(&std::fs::metadata(&path)?);
378                Ok(MetadataSwap::Stored(MetadataSnapshot {
379                    inner: Arc::new(crate::blob::authority::MetadataObservation {
380                        _retained: Arc::clone(&_physical.retained),
381                        owner: current.inner.owner.clone(),
382                        key,
383                        bytes: Some(stored),
384                        version: MetadataVersion::Local(Some(version)),
385                    }),
386                }))
387            })
388            .await
389            .map_err(|error| ObjectLogError::StorageUnavailable(error.to_string()))??;
390        if matches!(result, MetadataSwap::Stored(_)) {
391            self.record_put(size);
392            #[cfg(test)]
393            if lose_reply {
394                return Err(ObjectLogError::StorageUnavailable(
395                    "injected lost durable metadata reply".into(),
396                ));
397            }
398        }
399        Ok(result)
400    }
401}