Skip to main content

object_log/
bounded_fetch.rs

1//! Metadata is planned before strict payload I/O. Caller admission remains owned
2//! by the embedding operation; soft packing targets are not hard byte limits.
3use crate::{
4    BlobStore, BoundedSequencer, FetchedBatch, IndexEntry, LogEngine, ObjectLogError, PartitionKey,
5    Sequencer,
6};
7use std::sync::{Arc, Weak};
8
9/// Unforgeable metadata page from one sequencer/blob authority. Reserve the
10/// declared metadata budget before constructing, then per-batch bytes before read.
11pub struct FetchPlan<S: Sequencer> {
12    entries: Vec<IndexEntry>,
13    sequencer: Weak<S>,
14    blob: Weak<dyn BlobStore>,
15}
16impl<S: Sequencer> FetchPlan<S> {
17    /// Borrow the bounded metadata entries without cloning object identifiers.
18    pub fn entries(&self) -> &[IndexEntry] {
19        &self.entries
20    }
21    /// Sum of planned payload bytes; reserve this or each batch before I/O.
22    pub fn payload_bytes(&self) -> u64 {
23        self.entries
24            .iter()
25            .map(|entry| u64::from(entry.location.byte_len))
26            .sum()
27    }
28}
29impl<S: BoundedSequencer + 'static> LogEngine<S> {
30    /// Plan a count/metadata-bounded page without reading payloads. The soft
31    /// target includes at least one batch; use a separate hard admitted bound.
32    pub fn plan_fetch(
33        &self,
34        partition: &PartitionKey,
35        offset: i64,
36        max_entries: usize,
37        max_metadata_bytes: usize,
38        target_payload_bytes: u64,
39    ) -> Result<FetchPlan<S>, ObjectLogError> {
40        if offset < 0 || target_payload_bytes == 0 {
41            return Err(ObjectLogError::InvalidConfig(
42                "invalid bounded fetch offset/target".into(),
43            ));
44        }
45        if offset < self.sequencer().log_start_offset(partition)? {
46            return Err(ObjectLogError::RangeOutOfBounds(
47                "fetch precedes retained history".into(),
48            ));
49        }
50        let mut entries =
51            self.sequencer()
52                .lookup_page(partition, offset, max_entries, max_metadata_bytes)?;
53        if entries.len() > max_entries {
54            return Err(ObjectLogError::Sequencer(
55                "bounded sequencer exceeded entry limit".into(),
56            ));
57        }
58        let mut previous = None;
59        for entry in &entries {
60            let end = crate::bounded_lookup::entry_end(entry)?;
61            if let Some(previous) = previous {
62                if entry.base_offset != previous {
63                    return Err(ObjectLogError::Sequencer(
64                        "fetch page ranges are not contiguous".into(),
65                    ));
66                }
67            } else if entry.base_offset > offset || end <= offset {
68                return Err(ObjectLogError::Sequencer(
69                    "fetch page does not cover requested offset".into(),
70                ));
71            }
72            previous = Some(end);
73        }
74        let mut bytes = 0u64;
75        let mut count = 0;
76        for entry in &entries {
77            if bytes >= target_payload_bytes && count > 0 {
78                break;
79            }
80            crate::bounded_lookup::entry_end(entry)?;
81            bytes = bytes
82                .checked_add(u64::from(entry.location.byte_len))
83                .ok_or_else(|| {
84                    ObjectLogError::RangeOutOfBounds("fetch payload sum overflow".into())
85                })?;
86            count += 1;
87        }
88        entries.truncate(count);
89        Ok(FetchPlan {
90            entries,
91            sequencer: Arc::downgrade(self.sequencer()),
92            blob: Arc::downgrade(self.blob_store()),
93        })
94    }
95    /// Caller admits `entry.location.byte_len` before this read. `max_bytes` is
96    /// a hard batch bound; a soft target may admit an oversized first batch.
97    pub async fn read_planned_batch(
98        &self,
99        plan: &FetchPlan<S>,
100        index: usize,
101        max_bytes: u64,
102    ) -> Result<FetchedBatch, ObjectLogError> {
103        let same_seq = plan
104            .sequencer
105            .upgrade()
106            .is_some_and(|seq| Arc::ptr_eq(&seq, self.sequencer()));
107        let same_blob = plan
108            .blob
109            .upgrade()
110            .is_some_and(|blob| Arc::ptr_eq(&blob, self.blob_store()));
111        if !same_seq || !same_blob {
112            return Err(ObjectLogError::InvalidConfig(
113                "fetch plan belongs to another authority".into(),
114            ));
115        }
116        let entry = plan.entries.get(index).ok_or_else(|| {
117            ObjectLogError::RangeOutOfBounds("fetch plan index outside page".into())
118        })?;
119        let count = u64::from(entry.location.byte_len);
120        if count > max_bytes {
121            return Err(ObjectLogError::BudgetExceeded(
122                "batch exceeds hard admitted byte limit".into(),
123            ));
124        }
125        let start = u64::from(entry.location.byte_start);
126        let end = start
127            .checked_add(count)
128            .ok_or_else(|| ObjectLogError::RangeOutOfBounds("batch range overflow".into()))?;
129        let payload = crate::engine::get_range_with_retries(
130            self.blob_store(),
131            &entry.location.object_id,
132            start..end,
133            crate::engine::RangeRead::Exact,
134        )
135        .await?
136        .ok_or_else(|| ObjectLogError::MissingObject(entry.location.object_id.clone()))?;
137        if payload.len() as u64 != count {
138            return Err(ObjectLogError::RangeOutOfBounds(
139                "strict adapter returned wrong batch length".into(),
140            ));
141        }
142        Ok(FetchedBatch {
143            base_offset: entry.base_offset,
144            record_count: entry.record_count,
145            payload,
146        })
147    }
148}