cache2 0.2.3

Performance-first bounded RAM and NVMe hybrid cache
Documentation
// Copyright 2026 ScopeDB, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! One owned-buffer Region span submission for the data path.
//!
//! A successful write completion advances only the written prefix. The
//! disposable-cache protocol establishes durability once, when publishing a
//! CLEAN image, and deliberately has no per-span sync.

use std::fmt;
use std::io;

use crate::io_backend::{DIRECT_IO_ALIGNMENT, WritePoint};
use crate::io_engine::{
    BoundedIoRequest, IoBuffer, IoEngine, IoOperation, OperationKind, RequestId, submit_cache_io,
};
use crate::recovery::{DATA_REGION_AREA_OFFSET, DataGeometry};
use crate::region_manager::RegionWriteSpan;

pub(crate) struct RegionSpanSubmitError {
    pub(crate) error: io::Error,
    pub(crate) span: RegionWriteSpan,
    pub(crate) buffer: Option<IoBuffer>,
}

impl fmt::Debug for RegionSpanSubmitError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("RegionSpanSubmitError")
            .field("error", &self.error)
            .field("span", &self.span)
            .field("buffer_returned", &self.buffer.is_some())
            .finish()
    }
}

impl fmt::Display for RegionSpanSubmitError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.error.fmt(formatter)
    }
}

impl std::error::Error for RegionSpanSubmitError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.error)
    }
}

pub(crate) struct RegionSpanFlight {
    span: RegionWriteSpan,
    expected_len: usize,
    request_id: RequestId,
    request: BoundedIoRequest,
}

pub(crate) struct RegionSpanCompletion {
    pub(crate) span: RegionWriteSpan,
    pub(crate) result: io::Result<()>,
    pub(crate) buffer: Option<IoBuffer>,
}

impl RegionSpanFlight {
    pub(crate) fn wait(self, engine: &dyn IoEngine) -> RegionSpanCompletion {
        let completion = match self.request.wait(engine) {
            Ok(completion) => completion,
            Err(timeout) => {
                let (error, buffer) = timeout.into_buffer();
                return RegionSpanCompletion {
                    span: self.span,
                    result: Err(error),
                    buffer,
                };
            }
        };
        let identity_valid =
            completion.request_id == self.request_id && completion.kind == OperationKind::Write;
        let bytes_transferred = completion.bytes_transferred;
        let (io_result, buffer) = completion.into_io_result();
        let result = io_result.and_then(|completed| {
            if !identity_valid {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "Region span completion identity does not match its request",
                ));
            }
            if completed != self.expected_len || bytes_transferred != self.expected_len {
                return Err(io::Error::new(
                    io::ErrorKind::UnexpectedEof,
                    "Region span write completed with the wrong byte count",
                ));
            }
            let Some(buffer) = buffer.as_ref() else {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "Region span completion did not return its owned buffer",
                ));
            };
            if buffer.len() != self.expected_len {
                return Err(io::Error::new(
                    io::ErrorKind::InvalidData,
                    "Region span completion returned a buffer with the wrong length",
                ));
            }
            Ok(())
        });
        RegionSpanCompletion {
            span: self.span,
            result,
            buffer,
        }
    }
}

// The error returns the owned aligned buffer without another fallible
// allocation; boxing it would violate that overload-path property.
#[allow(clippy::result_large_err)]
pub(crate) fn submit_span(
    engine: &dyn IoEngine,
    geometry: DataGeometry,
    span: RegionWriteSpan,
    buffer: IoBuffer,
    absolute: u64,
) -> Result<RegionSpanFlight, RegionSpanSubmitError> {
    let (expected_len, expected_absolute) = match validate_span(geometry, span) {
        Ok(validated) => validated,
        Err(error) => {
            return Err(RegionSpanSubmitError {
                error,
                span,
                buffer: Some(buffer),
            });
        }
    };
    if buffer.len() != expected_len || absolute != expected_absolute {
        return Err(RegionSpanSubmitError {
            error: io::Error::new(
                io::ErrorKind::InvalidInput,
                "staging job does not match its Region span",
            ),
            span,
            buffer: Some(buffer),
        });
    }
    let buffer_is_direct_aligned = buffer.as_slice().is_ok_and(|bytes| {
        (bytes.as_ptr() as usize).is_multiple_of(DIRECT_IO_ALIGNMENT)
            && bytes.len() % DIRECT_IO_ALIGNMENT == 0
    });
    if !buffer_is_direct_aligned {
        return Err(RegionSpanSubmitError {
            error: io::Error::new(
                io::ErrorKind::InvalidInput,
                "Region span buffer is not direct-I/O aligned",
            ),
            span,
            buffer: Some(buffer),
        });
    }
    let request = match submit_cache_io(
        engine,
        IoOperation::write(WritePoint::Record, buffer, absolute),
    ) {
        Ok(request) => request,
        Err(error) => {
            let (error, buffer) = error.into_buffer();
            return Err(RegionSpanSubmitError {
                error,
                span,
                buffer,
            });
        }
    };
    Ok(RegionSpanFlight {
        span,
        expected_len,
        request_id: request.id(),
        request,
    })
}

fn validate_span(geometry: DataGeometry, span: RegionWriteSpan) -> io::Result<(usize, u64)> {
    if !geometry.is_valid()
        || span.region_id >= geometry.region_count
        || !span.start_offset.is_multiple_of(DIRECT_IO_ALIGNMENT as u64)
        || !span.end_offset.is_multiple_of(DIRECT_IO_ALIGNMENT as u64)
        || span.end_offset <= span.start_offset
        || span.end_offset > geometry.region_size
        || span.record_count == 0
    {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            "invalid Region write span",
        ));
    }
    let length = span
        .end_offset
        .checked_sub(span.start_offset)
        .and_then(|length| usize::try_from(length).ok())
        .filter(|length| *length != 0 && *length % DIRECT_IO_ALIGNMENT == 0)
        .ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "Region write span length is invalid",
            )
        })?;
    let absolute = u64::from(span.region_id)
        .checked_mul(geometry.region_size)
        .and_then(|offset| offset.checked_add(DATA_REGION_AREA_OFFSET))
        .and_then(|offset| offset.checked_add(span.start_offset))
        .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "write offset overflow"))?;
    let absolute_end = absolute
        .checked_add(length as u64)
        .ok_or_else(|| io::Error::new(io::ErrorKind::InvalidInput, "write end overflow"))?;
    if absolute % DIRECT_IO_ALIGNMENT as u64 != 0 || absolute_end > geometry.data_file_len {
        return Err(io::Error::new(
            io::ErrorKind::InvalidInput,
            "Region write span exceeds the data file",
        ));
    }
    Ok((length, absolute))
}

#[cfg(test)]
mod tests {
    use std::sync::{Arc, Mutex};

    use super::*;
    use crate::io_backend::{IoBackend, SyncMode, SyncPoint};
    use crate::io_engine::BackendIoEngine;
    use crate::resources::BufferLease;

    #[derive(Default)]
    struct RecordingBackend {
        writes: Mutex<Vec<(WritePoint, u64, Vec<u8>)>>,
    }

    impl IoBackend for RecordingBackend {
        fn len(&self) -> io::Result<u64> {
            Ok(u64::MAX)
        }

        fn set_len(&self, _len: u64) -> io::Result<()> {
            Ok(())
        }

        fn read_at(&self, _buffer: &mut [u8], _offset: u64) -> io::Result<usize> {
            Err(io::Error::new(io::ErrorKind::Unsupported, "read unused"))
        }

        fn write_at(&self, point: WritePoint, buffer: &[u8], offset: u64) -> io::Result<usize> {
            self.writes
                .lock()
                .unwrap_or_else(|poisoned| poisoned.into_inner())
                .push((point, offset, buffer.to_vec()));
            Ok(buffer.len())
        }

        fn sync(&self, _point: SyncPoint, _mode: SyncMode) -> io::Result<()> {
            Ok(())
        }

        fn try_lock_exclusive(&self) -> io::Result<()> {
            Ok(())
        }

        fn unlock(&self) -> io::Result<()> {
            Ok(())
        }
    }

    fn geometry() -> DataGeometry {
        let region_size = 64 * 1024;
        let region_count = 2;
        DataGeometry {
            data_file_len: DataGeometry::expected_file_len(region_size, region_count).unwrap(),
            region_size,
            region_count,
        }
    }

    fn span() -> RegionWriteSpan {
        RegionWriteSpan {
            shard_id: 0,
            region_id: 1,
            start_offset: 0,
            end_offset: 4096,
            record_count: 3,
            max_seqno: 21,
        }
    }

    #[test]
    fn span_write_preserves_owned_buffer_and_maps_region_offset_exactly() {
        let backend = Arc::new(RecordingBackend::default());
        let engine = BackendIoEngine::new(backend.clone(), 1).unwrap();
        let mut lease = BufferLease::try_fixed(4096).unwrap();
        lease.prepare(4096).unwrap().fill(0x5a);

        let buffer = IoBuffer::for_write(lease, 4096).unwrap();
        let absolute = DATA_REGION_AREA_OFFSET + geometry().region_size;
        let completion = submit_span(&engine, geometry(), span(), buffer, absolute)
            .unwrap()
            .wait(&engine);
        assert!(completion.result.is_ok());
        assert_eq!(completion.span, span());
        assert!(completion.buffer.is_some());
        drop(completion.buffer);

        let writes = backend
            .writes
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        assert_eq!(writes.len(), 1);
        assert_eq!(writes[0].0, WritePoint::Record);
        assert_eq!(
            writes[0].1,
            DATA_REGION_AREA_OFFSET + geometry().region_size
        );
        assert_eq!(writes[0].2, vec![0x5a; 4096]);
        drop(writes);
        engine.shutdown().unwrap();
    }

    #[test]
    fn invalid_span_returns_the_only_buffer_without_submitting_io() {
        let backend = Arc::new(RecordingBackend::default());
        let engine = BackendIoEngine::new(backend.clone(), 1).unwrap();
        let mut invalid = span();
        invalid.end_offset += 1;
        let buffer = IoBuffer::for_write(BufferLease::try_fixed(4096).unwrap(), 4096).unwrap();
        let error = match submit_span(&engine, geometry(), invalid, buffer, 0) {
            Err(error) => error,
            Ok(_) => panic!("unaligned span must not be submitted"),
        };
        assert_eq!(error.error.kind(), io::ErrorKind::InvalidInput);
        assert!(error.buffer.is_some());
        drop(error.buffer);
        assert!(
            backend
                .writes
                .lock()
                .unwrap_or_else(|poisoned| poisoned.into_inner())
                .is_empty()
        );
        engine.shutdown().unwrap();
    }
}