use zerocopy::{
FromBytes, Immutable, IntoBytes, KnownLayout, Unaligned,
little_endian::{U32, U64},
};
use crate::db::LogPosition;
use crate::error::Error;
use crate::sector::LogId;
pub const SPOOL_CURSOR_MAGIC: [u8; 4] = *b"SPC1";
pub const SPOOL_CURSOR_VERSION: u8 = 1;
pub const CURSOR_RECORD_SIZE: usize = 60;
const CURSOR_CRC_COVERAGE: usize = CURSOR_RECORD_SIZE - 4;
pub const CURSOR_SECTORS: u8 = 2;
const CURSOR_CRC: crc::Crc<u32> = crc::Crc::<u32>::new(&crc::CRC_32_ISCSI);
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum CursorKind {
Intent,
Commit,
}
pub const CURSOR_KIND_INTENT: u8 = 0xA1;
pub const CURSOR_KIND_COMMIT: u8 = 0xC0;
impl CursorKind {
fn from_raw(raw: u8) -> Option<Self> {
match raw {
CURSOR_KIND_INTENT => Some(Self::Intent),
CURSOR_KIND_COMMIT => Some(Self::Commit),
_ => None,
}
}
fn to_raw(self) -> u8 {
match self {
Self::Intent => CURSOR_KIND_INTENT,
Self::Commit => CURSOR_KIND_COMMIT,
}
}
}
#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned, Clone, Copy)]
#[repr(C, packed)]
pub struct SpoolCursorWire {
pub magic: [u8; 4],
pub version: u8,
pub kind: u8,
pub reserved: [u8; 2],
pub source_log_id: U32,
pub source_epoch: U32,
pub batch_id: U32,
pub from_sequence: U32,
pub from_offset: U32,
pub upto_sequence: U32,
pub upto_offset: U32,
pub entry_count: U32,
pub dest_sequence: U32,
pub dest_offset: U32,
pub last_timestamp: U64,
pub record_crc: U32,
}
impl SpoolCursorWire {
#[allow(clippy::too_many_arguments)]
pub fn new(
kind: CursorKind,
source_log_id: Option<LogId>,
source_epoch: u32,
batch_id: u32,
from: LogPosition,
upto: LogPosition,
entry_count: u32,
dest: LogPosition,
last_timestamp: u64,
) -> Self {
let mut record = Self {
magic: SPOOL_CURSOR_MAGIC,
version: SPOOL_CURSOR_VERSION,
kind: kind.to_raw(),
reserved: [0; 2],
source_log_id: U32::new(source_log_id.map_or(0, LogId::get)),
source_epoch: U32::new(source_epoch),
batch_id: U32::new(batch_id),
from_sequence: U32::new(from.sequence),
from_offset: U32::new(from.offset),
upto_sequence: U32::new(upto.sequence),
upto_offset: U32::new(upto.offset),
entry_count: U32::new(entry_count),
dest_sequence: U32::new(dest.sequence),
dest_offset: U32::new(dest.offset),
last_timestamp: U64::new(last_timestamp),
record_crc: U32::new(0),
};
record.record_crc = U32::new(record.compute_crc());
record
}
fn compute_crc(&self) -> u32 {
CURSOR_CRC.checksum(&self.as_bytes()[..CURSOR_CRC_COVERAGE])
}
pub fn is_valid(&self) -> bool {
self.magic == SPOOL_CURSOR_MAGIC
&& self.version == SPOOL_CURSOR_VERSION
&& CursorKind::from_raw(self.kind).is_some()
&& self.record_crc.get() == self.compute_crc()
}
pub fn kind(&self) -> Option<CursorKind> {
CursorKind::from_raw(self.kind)
}
pub fn from(&self) -> LogPosition {
LogPosition {
sequence: self.from_sequence.get(),
offset: self.from_offset.get(),
}
}
pub fn upto(&self) -> LogPosition {
LogPosition {
sequence: self.upto_sequence.get(),
offset: self.upto_offset.get(),
}
}
pub fn dest(&self) -> LogPosition {
LogPosition {
sequence: self.dest_sequence.get(),
offset: self.dest_offset.get(),
}
}
pub fn resume_point(&self) -> LogPosition {
match self.kind() {
Some(CursorKind::Commit) => self.upto(),
_ => self.from(),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct CursorRegion {
base: u32,
sector_size: u32,
page_size: u32,
}
impl CursorRegion {
pub fn new(base: u32, sector_size: u32, page_size: u32) -> Result<Self, Error> {
if page_size < CURSOR_RECORD_SIZE as u32
|| sector_size == 0
|| page_size == 0
|| !sector_size.is_multiple_of(page_size)
|| sector_size / page_size < 2
{
return Err(Error::InvalidConfig);
}
let span = sector_size
.checked_mul(CURSOR_SECTORS as u32)
.ok_or(Error::Overflow)?;
base.checked_add(span).ok_or(Error::Overflow)?;
Ok(Self {
base,
sector_size,
page_size,
})
}
pub fn slots_per_sector(&self) -> u32 {
self.sector_size / self.page_size
}
pub fn total_size(&self) -> u32 {
self.sector_size * CURSOR_SECTORS as u32
}
pub fn base(&self) -> u32 {
self.base
}
pub fn end(&self) -> u32 {
self.base + self.total_size()
}
pub fn sector_offset(&self, sector: u8) -> u32 {
(sector % CURSOR_SECTORS) as u32 * self.sector_size
}
pub fn sector_range(&self, sector: u8) -> (u32, u32) {
let from = self.sector_offset(sector);
(from, from + self.sector_size)
}
pub fn slot_offset(&self, sector: u8, slot: u32) -> u32 {
self.sector_offset(sector) + slot * self.page_size
}
pub fn slots(&self) -> impl Iterator<Item = SlotAddress> + '_ {
let region = *self;
(0..CURSOR_SECTORS).flat_map(move |sector| {
(0..region.slots_per_sector()).map(move |slot| SlotAddress {
sector,
slot,
offset: region.slot_offset(sector, slot),
})
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct SlotAddress {
pub sector: u8,
pub slot: u32,
pub offset: u32,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn record_size_matches_the_constant() {
assert_eq!(CURSOR_RECORD_SIZE, core::mem::size_of::<SpoolCursorWire>());
}
fn sample(kind: CursorKind) -> SpoolCursorWire {
SpoolCursorWire::new(
kind,
LogId::new(0xABCD),
7,
42,
LogPosition {
sequence: 3,
offset: 100,
},
LogPosition {
sequence: 3,
offset: 500,
},
17,
LogPosition {
sequence: 9,
offset: 28,
},
123_456,
)
}
#[test]
fn round_trips_through_bytes() {
let record = sample(CursorKind::Commit);
let bytes = record.as_bytes().to_vec();
let parsed = SpoolCursorWire::read_from_bytes(&bytes).unwrap();
assert!(parsed.is_valid());
assert_eq!(parsed.kind(), Some(CursorKind::Commit));
assert_eq!(parsed.batch_id.get(), 42);
assert_eq!(parsed.source_epoch.get(), 7);
assert_eq!(parsed.from().offset, 100);
assert_eq!(parsed.upto().offset, 500);
assert_eq!(parsed.dest().sequence, 9);
assert_eq!(parsed.last_timestamp.get(), 123_456);
}
#[test]
fn a_single_flipped_bit_fails_the_crc() {
let record = sample(CursorKind::Commit);
let mut bytes = record.as_bytes().to_vec();
bytes[20] ^= 0x01;
let parsed = SpoolCursorWire::read_from_bytes(&bytes).unwrap();
assert!(!parsed.is_valid(), "a torn record must not be trusted");
}
#[test]
fn an_erased_page_is_not_a_record() {
let bytes = [0xFFu8; CURSOR_RECORD_SIZE];
let parsed = SpoolCursorWire::read_from_bytes(&bytes).unwrap();
assert!(!parsed.is_valid());
assert_eq!(parsed.kind(), None);
}
#[test]
fn a_zeroed_page_is_not_a_record() {
let bytes = [0x00u8; CURSOR_RECORD_SIZE];
let parsed = SpoolCursorWire::read_from_bytes(&bytes).unwrap();
assert!(!parsed.is_valid());
}
#[test]
fn resume_point_trusts_commits_and_distrusts_intents() {
let commit = sample(CursorKind::Commit);
assert_eq!(commit.resume_point(), commit.upto());
let intent = sample(CursorKind::Intent);
assert_eq!(
intent.resume_point(),
intent.from(),
"an intent proves only where the batch started"
);
}
#[test]
fn region_rejects_geometry_that_cannot_hold_records() {
assert!(CursorRegion::new(0, 4096, 32).is_err());
assert!(CursorRegion::new(0, 4000, 256).is_err());
assert!(CursorRegion::new(0, 256, 256).is_err());
assert!(CursorRegion::new(u32::MAX - 1024, 4096, 256).is_err());
}
#[test]
fn region_addresses_are_laid_out_as_documented() {
let region = CursorRegion::new(0x1000, 4096, 256).unwrap();
assert_eq!(region.slots_per_sector(), 16);
assert_eq!(region.total_size(), 8192);
assert_eq!(region.base(), 0x1000);
assert_eq!(region.end(), 0x1000 + 8192);
assert_eq!(region.sector_offset(0), 0);
assert_eq!(region.sector_offset(1), 4096);
assert_eq!(region.slot_offset(0, 0), 0);
assert_eq!(region.slot_offset(0, 3), 3 * 256);
assert_eq!(region.slot_offset(1, 15), 4096 + 15 * 256);
assert!(region.base() + region.slot_offset(1, 15) < region.end());
}
#[test]
fn a_sector_range_covers_exactly_one_cursor_sector() {
let region = CursorRegion::new(0x1000, 4096, 256).unwrap();
assert_eq!(region.sector_range(0), (0, 4096));
assert_eq!(region.sector_range(1), (4096, 8192));
assert_eq!(region.sector_range(1).1, region.total_size());
}
#[test]
fn the_slot_iterator_visits_every_slot_once_in_address_order() {
let region = CursorRegion::new(0x1000, 4096, 256).unwrap();
let mut visited = 0u32;
let mut previous: Option<SlotAddress> = None;
for at in region.slots() {
assert_eq!(at.offset, region.slot_offset(at.sector, at.slot));
if let Some(before) = previous {
assert!(before.offset < at.offset);
}
previous = Some(at);
visited += 1;
}
assert_eq!(visited, 2 * region.slots_per_sector());
assert_eq!(
region.slots().next().unwrap(),
SlotAddress {
sector: 0,
slot: 0,
offset: 0
}
);
assert_eq!(
previous.unwrap(),
SlotAddress {
sector: 1,
slot: 15,
offset: 4096 + 15 * 256
}
);
}
}