Skip to main content

object_log/
blob.rs

1//! The object-storage port and the bundled adapters.
2
3use crate::ObjectLogError;
4use async_trait::async_trait;
5use bytes::{Bytes, BytesMut};
6use std::collections::BTreeMap;
7use std::io::{Read, Seek, SeekFrom, Write};
8use std::ops::Range;
9use std::os::unix::io::AsRawFd;
10use std::path::{Path, PathBuf};
11use std::sync::atomic::{AtomicU64, Ordering};
12use std::sync::{Arc, Mutex, OnceLock};
13use std::time::{Instant, SystemTime, UNIX_EPOCH};
14
15/// Result of [`BlobStore::compare_and_swap`].
16#[derive(Clone, Debug, PartialEq, Eq)]
17pub enum CasOutcome {
18    /// `new_value` is now the object's contents.
19    Stored,
20    /// The object did not match `expected`. `current` is the value observed
21    /// after the failed update (`None` if the key is absent).
22    Conflict {
23        /// Bytes present after the rejected update.
24        current: Option<Bytes>,
25    },
26}
27
28/// Durable-media accounting for the flush budget controller (TD-004).
29#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
30pub struct MediaOpStats {
31    /// File/dir fsyncs or billable durable requests performed since last take.
32    pub media_ops: u64,
33    /// Bytes written through durable (or memory) put paths since last take.
34    pub bytes: u64,
35}
36
37/// Suffix for in-flight temp files written by [`LocalBlobStore`]; keys ending in
38/// it are skipped by [`list`](BlobStore::list).
39const TMP_SUFFIX: &str = ".olog-tmp";
40
41fn diagnostic_unix_us() -> u128 {
42    SystemTime::now()
43        .duration_since(UNIX_EPOCH)
44        .unwrap_or_default()
45        .as_micros()
46}
47
48fn object_class(key: &str) -> &'static str {
49    if key.starts_with("fwlog/") {
50        "segment"
51    } else if key.starts_with("fwmeta/manifest/") {
52        "manifest"
53    } else {
54        "metadata"
55    }
56}
57
58/// Physical store join id for opt-in publication traces.
59///
60/// Workload stores live at `shard-N/{log,projection.db}`. Object keys and
61/// queue ids are shared across those physical stores.
62fn diagnostic_store_tag(path: &Path) -> String {
63    let mut fallback = None;
64    for component in path.components() {
65        let name = component.as_os_str().to_string_lossy();
66        if let Some(rest) = name.strip_prefix("shard-")
67            && !rest.is_empty()
68            && rest.bytes().all(|b| b.is_ascii_digit())
69        {
70            return name.into_owned();
71        }
72        if !matches!(
73            name.as_ref(),
74            "log" | "fwlog" | "fwmeta" | "manifest" | "projection.db" | "/" | "."
75        ) {
76            fallback = Some(name.into_owned());
77        }
78    }
79    fallback
80        .filter(|name| !name.is_empty())
81        .unwrap_or_else(|| "unknown".into())
82}
83
84/// A minimal async object store over immutable, string-keyed blobs.
85///
86/// This is the storage *port* the log engine is built on. Implement it for your
87/// backend (e.g. S3) to store the log there. Data objects are written once under
88/// a unique key. Partition index objects use
89/// [`compare_and_swap`](BlobStore::compare_and_swap).
90///
91/// Durability: [`put`](BlobStore::put) is **durable-on-return** for crash-durable
92/// adapters ([`LocalBlobStore`], an S3 adapter) — once it resolves `Ok`, the bytes
93/// survive a crash, so a caller may treat `Ok` as a durability barrier.
94/// [`MemoryBlobStore`] is a test/dev backend and is **not** crash-durable.
95#[async_trait]
96pub trait BlobStore: Send + Sync {
97    /// Durably store `value` at `key` (see the trait-level durability note).
98    /// `value` may be arbitrarily large; a network adapter should chunk it
99    /// (e.g. S3 multipart) rather than rely on a single request.
100    async fn put(&self, key: &str, value: Bytes) -> Result<(), ObjectLogError>;
101
102    /// Durably store a logical object assembled from immutable byte chunks.
103    ///
104    /// The default implementation concatenates chunks and delegates to
105    /// [`put`](BlobStore::put). Object-store adapters can override this to stream
106    /// or multipart-upload chunks without materializing the full object twice.
107    async fn put_chunks(&self, key: &str, chunks: Vec<Bytes>) -> Result<(), ObjectLogError> {
108        match chunks.len() {
109            0 => self.put(key, Bytes::new()).await,
110            1 => self.put(key, chunks.into_iter().next().unwrap()).await,
111            _ => {
112                let total = chunks.iter().map(Bytes::len).sum();
113                let mut value = BytesMut::with_capacity(total);
114                for chunk in chunks {
115                    value.extend_from_slice(&chunk);
116                }
117                self.put(key, value.freeze()).await
118            }
119        }
120    }
121
122    /// Fetch the whole object at `key`, or `None` if absent.
123    async fn get(&self, key: &str) -> Result<Option<Bytes>, ObjectLogError>;
124
125    /// Read a byte sub-range of an object without fetching the whole thing.
126    /// `None` if the key is absent. `range.end > len` or `range.start > range.end`
127    /// is [`ObjectLogError::RangeOutOfBounds`]; an empty `n..n` returns
128    /// `Ok(Some(<empty>))`. No integrity check is performed — payloads are opaque.
129    async fn get_range(
130        &self,
131        key: &str,
132        range: Range<u64>,
133    ) -> Result<Option<Bytes>, ObjectLogError>;
134
135    /// List keys beginning with `prefix`.
136    async fn list(&self, prefix: &str) -> Result<Vec<String>, ObjectLogError>;
137
138    /// Delete an object; deleting a missing key is a no-op success.
139    async fn delete(&self, key: &str) -> Result<(), ObjectLogError>;
140
141    /// Replace `key` only when its current bytes equal `expected`.
142    ///
143    /// `expected == None` succeeds only when the key is absent (create-only).
144    /// The default reads and then [`put`](BlobStore::put)s, which is not atomic
145    /// across processes. [`MemoryBlobStore`], [`LocalBlobStore`], and the S3
146    /// adapter override it with a real conditional update.
147    async fn compare_and_swap(
148        &self,
149        key: &str,
150        expected: Option<Bytes>,
151        new_value: Bytes,
152    ) -> Result<CasOutcome, ObjectLogError> {
153        let current = self.get(key).await?;
154        let matches = match (&expected, &current) {
155            (None, None) => true,
156            (Some(expected), Some(current)) => expected == current,
157            _ => false,
158        };
159        if !matches {
160            return Ok(CasOutcome::Conflict { current });
161        }
162        self.put(key, new_value).await?;
163        Ok(CasOutcome::Stored)
164    }
165
166    /// Snapshot and reset media-op counters since the previous take.
167    ///
168    /// Adapters that can count exact durable units (fsyncs, S3 PUTs) should
169    /// implement this. The default returns [`None`]; the engine then treats each
170    /// successful [`put`](BlobStore::put) / [`put_chunks`](BlobStore::put_chunks)
171    /// as **one** media op (documented fallback).
172    fn take_media_op_stats(&self) -> Option<MediaOpStats> {
173        None
174    }
175}
176
177/// Slice `bytes` by `range`, applying the [`BlobStore::get_range`] bounds rules.
178fn slice_range(bytes: &Bytes, range: Range<u64>) -> Result<Bytes, ObjectLogError> {
179    if range.start > range.end {
180        return Err(ObjectLogError::RangeOutOfBounds(format!(
181            "start {} > end {}",
182            range.start, range.end
183        )));
184    }
185    let len = bytes.len() as u64;
186    if range.end > len {
187        return Err(ObjectLogError::RangeOutOfBounds(format!(
188            "end {} > len {len}",
189            range.end
190        )));
191    }
192    Ok(bytes.slice(range.start as usize..range.end as usize))
193}
194
195/// In-process [`BlobStore`] backed by a map. For tests and development; state is
196/// lost on drop and is **not** crash-durable.
197#[derive(Clone, Default)]
198pub struct MemoryBlobStore {
199    objects: Arc<Mutex<BTreeMap<String, Bytes>>>,
200    bytes_written: Arc<AtomicU64>,
201}
202
203impl MemoryBlobStore {
204    /// Create an empty store.
205    pub fn new() -> Self {
206        Self::default()
207    }
208
209    /// Number of stored objects (lets tests assert PUT-count / cost invariants).
210    pub fn object_count(&self) -> usize {
211        self.objects.lock().expect("poisoned").len()
212    }
213
214    /// Total stored bytes across all objects.
215    pub fn total_bytes(&self) -> usize {
216        self.objects
217            .lock()
218            .expect("poisoned")
219            .values()
220            .map(|v| v.len())
221            .sum()
222    }
223}
224
225#[async_trait]
226impl BlobStore for MemoryBlobStore {
227    async fn put(&self, key: &str, value: Bytes) -> Result<(), ObjectLogError> {
228        self.bytes_written
229            .fetch_add(value.len() as u64, Ordering::Relaxed);
230        self.objects
231            .lock()
232            .expect("poisoned")
233            .insert(key.to_string(), value);
234        Ok(())
235    }
236
237    async fn compare_and_swap(
238        &self,
239        key: &str,
240        expected: Option<Bytes>,
241        new_value: Bytes,
242    ) -> Result<CasOutcome, ObjectLogError> {
243        let mut objects = self.objects.lock().expect("poisoned");
244        let current = objects.get(key).cloned();
245        let matches = match (&expected, &current) {
246            (None, None) => true,
247            (Some(expected), Some(current)) => expected == current,
248            _ => false,
249        };
250        if !matches {
251            return Ok(CasOutcome::Conflict { current });
252        }
253        self.bytes_written
254            .fetch_add(new_value.len() as u64, Ordering::Relaxed);
255        objects.insert(key.to_string(), new_value);
256        Ok(CasOutcome::Stored)
257    }
258
259    async fn get(&self, key: &str) -> Result<Option<Bytes>, ObjectLogError> {
260        Ok(self.objects.lock().expect("poisoned").get(key).cloned())
261    }
262
263    async fn get_range(
264        &self,
265        key: &str,
266        range: Range<u64>,
267    ) -> Result<Option<Bytes>, ObjectLogError> {
268        let object = self.objects.lock().expect("poisoned").get(key).cloned();
269        match object {
270            Some(bytes) => Ok(Some(slice_range(&bytes, range)?)),
271            None => Ok(None),
272        }
273    }
274
275    async fn list(&self, prefix: &str) -> Result<Vec<String>, ObjectLogError> {
276        Ok(self
277            .objects
278            .lock()
279            .expect("poisoned")
280            .keys()
281            .filter(|k| k.starts_with(prefix))
282            .cloned()
283            .collect())
284    }
285
286    async fn delete(&self, key: &str) -> Result<(), ObjectLogError> {
287        self.objects.lock().expect("poisoned").remove(key);
288        Ok(())
289    }
290
291    fn take_media_op_stats(&self) -> Option<MediaOpStats> {
292        // Memory has no crash-durable media cost.
293        Some(MediaOpStats {
294            media_ops: 0,
295            bytes: self.bytes_written.swap(0, Ordering::Relaxed),
296        })
297    }
298}
299
300/// Filesystem-backed [`BlobStore`] rooted at a directory.
301///
302/// Single-node. Writes are **durable-on-return**: each `put` / `put_chunks`:
303/// 1. write a temp file in the same directory as the final key  
304/// 2. [`std::fs::File::sync_data`] (fdatasync on Unix) so payload bytes are durable  
305/// 3. `rename` into place  
306/// 4. `fsync` the parent directory so the directory entry survives power loss  
307///
308/// (On macOS, true device durability may need `F_FULLFSYNC`; Linux `sync_data` /
309/// dir `sync_all` is the intended contract.)
310#[derive(Clone)]
311pub struct LocalBlobStore {
312    root: Arc<PathBuf>,
313    media_ops: Arc<AtomicU64>,
314    bytes_written: Arc<AtomicU64>,
315}
316
317impl LocalBlobStore {
318    /// Create a store rooted at `root` (created lazily on first write).
319    pub fn new(root: impl Into<PathBuf>) -> Self {
320        Self {
321            root: Arc::new(root.into()),
322            media_ops: Arc::new(AtomicU64::new(0)),
323            bytes_written: Arc::new(AtomicU64::new(0)),
324        }
325    }
326
327    fn path_for(&self, key: &str) -> Result<PathBuf, ObjectLogError> {
328        if key.is_empty() || key.contains('\0') || key.split('/').any(|p| p == "..") {
329            return Err(ObjectLogError::InvalidObjectKey(key.to_string()));
330        }
331        Ok(self.root.join(key))
332    }
333
334    /// Durable publish: temp → sync_data → rename → dir fsync. No full pre-merge
335    /// of `chunks` (streams them to the temp file).
336    fn durable_publish_chunks(
337        path: PathBuf,
338        chunks: Vec<Bytes>,
339        key: &str,
340    ) -> std::io::Result<u64> {
341        // Opt-in diagnostic only: preserve the exact publication operations and
342        // ordering. No paths or payloads are emitted. Failed puts remain errors;
343        // phase records below describe successful publications only.
344        static TRACE: OnceLock<bool> = OnceLock::new();
345        let trace =
346            *TRACE.get_or_init(|| std::env::var_os("OBJECT_LOG_LOCAL_PUBLISH_TRACE").is_some());
347        let started = trace.then(Instant::now);
348        let started_unix_us = trace.then(diagnostic_unix_us);
349        let mut phase = started;
350        let mut elapsed = || {
351            phase.map_or(0, |before| {
352                let now = Instant::now();
353                phase = Some(now);
354                now.duration_since(before).as_micros()
355            })
356        };
357        let parent = path.parent().expect("object path has a parent");
358        std::fs::create_dir_all(parent)?;
359        let mkdir_us = elapsed();
360        let mut tmp = path.clone().into_os_string();
361        tmp.push(TMP_SUFFIX);
362        let tmp = PathBuf::from(tmp);
363        let mut byte_len = 0u64;
364        let (create_us, write_us, data_sync_us);
365        {
366            let mut f = std::fs::File::create(&tmp)?;
367            create_us = elapsed();
368            for chunk in &chunks {
369                f.write_all(chunk)?;
370                byte_len += chunk.len() as u64;
371            }
372            write_us = elapsed();
373            // fdatasync on Unix: data durable; dir fsync below covers the name.
374            f.sync_data()?;
375            data_sync_us = elapsed();
376        }
377        std::fs::rename(&tmp, &path)?;
378        let rename_us = elapsed(); // Includes closing the data file.
379        let directory = std::fs::File::open(parent)?;
380        let dir_open_us = elapsed();
381        directory.sync_all()?;
382        let dir_sync_us = elapsed();
383        if let (Some(started), Some(started_unix_us)) = (started, started_unix_us) {
384            eprintln!(
385                "local_publish bytes={byte_len} mkdir_us={mkdir_us} create_us={create_us} write_us={write_us} data_sync_us={data_sync_us} rename_us={rename_us} dir_open_us={dir_open_us} dir_sync_us={dir_sync_us} total_us={} class={} store={} started_unix_us={started_unix_us}",
386                started.elapsed().as_micros(),
387                object_class(key),
388                diagnostic_store_tag(&path),
389            );
390        }
391        Ok(byte_len)
392    }
393
394    fn record_put(&self, byte_len: u64) {
395        // Two media ops: file data sync + parent directory sync.
396        self.media_ops.fetch_add(2, Ordering::Relaxed);
397        self.bytes_written.fetch_add(byte_len, Ordering::Relaxed);
398    }
399
400    async fn publish_async(
401        &self,
402        path: PathBuf,
403        chunks: Vec<Bytes>,
404        key: String,
405    ) -> Result<u64, ObjectLogError> {
406        let run = move || {
407            Self::durable_publish_chunks(path, chunks, &key)
408                .map_err(|e| ObjectLogError::StorageUnavailable(e.to_string()))
409        };
410        match tokio::runtime::Handle::try_current() {
411            // Multi-thread worker: avoid spawn_blocking queue (flush path uses this).
412            Ok(h) if h.runtime_flavor() == tokio::runtime::RuntimeFlavor::MultiThread => {
413                tokio::task::block_in_place(run)
414            }
415            // Current-thread runtime (many unit tests): must not block_in_place.
416            Ok(_) => tokio::task::spawn_blocking(run)
417                .await
418                .map_err(|e| ObjectLogError::StorageUnavailable(e.to_string()))?,
419            Err(_) => run(),
420        }
421    }
422}
423
424#[async_trait]
425impl BlobStore for LocalBlobStore {
426    async fn put(&self, key: &str, value: Bytes) -> Result<(), ObjectLogError> {
427        let path = self.path_for(key)?;
428        let byte_len = self
429            .publish_async(path, vec![value], key.to_string())
430            .await?;
431        self.record_put(byte_len);
432        Ok(())
433    }
434
435    async fn put_chunks(&self, key: &str, chunks: Vec<Bytes>) -> Result<(), ObjectLogError> {
436        match chunks.len() {
437            0 => self.put(key, Bytes::new()).await,
438            1 => self.put(key, chunks.into_iter().next().unwrap()).await,
439            _ => {
440                let path = self.path_for(key)?;
441                let byte_len = self.publish_async(path, chunks, key.to_string()).await?;
442                self.record_put(byte_len);
443                Ok(())
444            }
445        }
446    }
447
448    async fn get(&self, key: &str) -> Result<Option<Bytes>, ObjectLogError> {
449        let path = self.path_for(key)?;
450        match tokio::fs::read(&path).await {
451            Ok(v) => Ok(Some(Bytes::from(v))),
452            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
453            Err(e) => Err(e.into()),
454        }
455    }
456
457    async fn get_range(
458        &self,
459        key: &str,
460        range: Range<u64>,
461    ) -> Result<Option<Bytes>, ObjectLogError> {
462        if range.start > range.end {
463            return Err(ObjectLogError::RangeOutOfBounds(format!(
464                "start {} > end {}",
465                range.start, range.end
466            )));
467        }
468        let path = self.path_for(key)?;
469        tokio::task::spawn_blocking(move || -> Result<Option<Bytes>, ObjectLogError> {
470            let mut f = match std::fs::File::open(&path) {
471                Ok(f) => f,
472                Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
473                Err(e) => return Err(e.into()),
474            };
475            let len = f.metadata()?.len();
476            if range.end > len {
477                return Err(ObjectLogError::RangeOutOfBounds(format!(
478                    "end {} > len {len}",
479                    range.end
480                )));
481            }
482            let count = (range.end - range.start) as usize;
483            let mut buf = vec![0u8; count];
484            f.seek(SeekFrom::Start(range.start))?;
485            f.read_exact(&mut buf)?;
486            Ok(Some(Bytes::from(buf)))
487        })
488        .await
489        .map_err(|e| ObjectLogError::StorageUnavailable(e.to_string()))?
490    }
491
492    async fn list(&self, prefix: &str) -> Result<Vec<String>, ObjectLogError> {
493        let root = self.root.clone();
494        let prefix = prefix.to_string();
495        let keys = tokio::task::spawn_blocking(move || -> std::io::Result<Vec<String>> {
496            let mut out = Vec::new();
497            collect_files(&root, &root, &mut out)?;
498            Ok(out)
499        })
500        .await
501        .map_err(|e| ObjectLogError::StorageUnavailable(e.to_string()))??;
502        Ok(keys
503            .into_iter()
504            .filter(|k| k.starts_with(&prefix))
505            .collect())
506    }
507
508    async fn delete(&self, key: &str) -> Result<(), ObjectLogError> {
509        let path = self.path_for(key)?;
510        match tokio::fs::remove_file(&path).await {
511            Ok(()) => Ok(()),
512            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
513            Err(e) => Err(e.into()),
514        }
515    }
516
517    async fn compare_and_swap(
518        &self,
519        key: &str,
520        expected: Option<Bytes>,
521        new_value: Bytes,
522    ) -> Result<CasOutcome, ObjectLogError> {
523        let path = self.path_for(key)?;
524        let key = key.to_string();
525        let byte_len = new_value.len() as u64;
526        let outcome = tokio::task::spawn_blocking(move || {
527            local_compare_and_swap(&path, &key, expected, new_value)
528        })
529        .await
530        .map_err(|e| ObjectLogError::StorageUnavailable(e.to_string()))??;
531        if matches!(outcome, CasOutcome::Stored) {
532            self.record_put(byte_len);
533        }
534        Ok(outcome)
535    }
536
537    fn take_media_op_stats(&self) -> Option<MediaOpStats> {
538        Some(MediaOpStats {
539            media_ops: self.media_ops.swap(0, Ordering::Relaxed),
540            bytes: self.bytes_written.swap(0, Ordering::Relaxed),
541        })
542    }
543}
544
545fn local_compare_and_swap(
546    path: &Path,
547    key: &str,
548    expected: Option<Bytes>,
549    new_value: Bytes,
550) -> Result<CasOutcome, ObjectLogError> {
551    if let Some(parent) = path.parent() {
552        std::fs::create_dir_all(parent)?;
553    }
554    let mut lock_name = path.as_os_str().to_os_string();
555    lock_name.push(".caslock");
556    let lock = std::fs::OpenOptions::new()
557        .create(true)
558        .truncate(false)
559        .read(true)
560        .write(true)
561        .open(lock_name)?;
562    flock_exclusive(&lock)?;
563    let current = match std::fs::read(path) {
564        Ok(bytes) => Some(Bytes::from(bytes)),
565        Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
566        Err(error) => {
567            let _ = flock_unlock(&lock);
568            return Err(error.into());
569        }
570    };
571    let matches = match (&expected, &current) {
572        (None, None) => true,
573        (Some(expected), Some(current)) => expected == current,
574        _ => false,
575    };
576    if !matches {
577        let _ = flock_unlock(&lock);
578        return Ok(CasOutcome::Conflict { current });
579    }
580    let published =
581        LocalBlobStore::durable_publish_chunks(path.to_path_buf(), vec![new_value], key);
582    let _ = flock_unlock(&lock);
583    published?;
584    Ok(CasOutcome::Stored)
585}
586
587fn flock_exclusive(file: &std::fs::File) -> std::io::Result<()> {
588    let rc = unsafe { flock(file.as_raw_fd(), 2) };
589    if rc == 0 {
590        Ok(())
591    } else {
592        Err(std::io::Error::last_os_error())
593    }
594}
595
596fn flock_unlock(file: &std::fs::File) -> std::io::Result<()> {
597    let rc = unsafe { flock(file.as_raw_fd(), 8) };
598    if rc == 0 {
599        Ok(())
600    } else {
601        Err(std::io::Error::last_os_error())
602    }
603}
604
605unsafe extern "C" {
606    fn flock(fd: i32, operation: i32) -> i32;
607}
608
609fn collect_files(root: &Path, dir: &Path, out: &mut Vec<String>) -> std::io::Result<()> {
610    if !dir.exists() {
611        return Ok(());
612    }
613    for entry in std::fs::read_dir(dir)? {
614        let entry = entry?;
615        let path = entry.path();
616        if path.is_dir() {
617            collect_files(root, &path, out)?;
618        } else if !path.to_string_lossy().ends_with(TMP_SUFFIX)
619            && !path.to_string_lossy().ends_with(".caslock")
620            && let Ok(rel) = path.strip_prefix(root)
621        {
622            out.push(rel.to_string_lossy().replace('\\', "/"));
623        }
624    }
625    Ok(())
626}
627
628#[cfg(test)]
629mod tests {
630    use super::*;
631
632    #[test]
633    fn diagnostic_store_tag_prefers_workload_shard_directory() {
634        assert_eq!(
635            diagnostic_store_tag(Path::new(
636                "/tmp/run/shard-12/log/fwlog/00000000000000000001"
637            )),
638            "shard-12"
639        );
640        assert_eq!(
641            diagnostic_store_tag(Path::new("/data/shard-0/projection.db")),
642            "shard-0"
643        );
644        assert_eq!(object_class("fwlog/1"), "segment");
645        assert_eq!(object_class("fwmeta/manifest/1"), "manifest");
646        assert_eq!(object_class("fwmeta/high-water/1"), "metadata");
647    }
648}