Struct Segment 

pub struct Segment { /* private fields */ }

A single log segment: the .log data file paired with its sparse .index (offset → byte position) and .timeindex (timestamp → relative offset) sidecars.

A segment is identified by its base_offset: the absolute offset of its first record, encoded into the segment’s 20-digit zero-padded filename. Segments are created via Segment::create (new active segment) or opened via Segment::open (read-only sealed segment) or Segment::open_active (active segment with tail recovery).

Implementations

impl Segment

pub fn create(dir: &Path, base_offset: i64) -> Result<Self, LogError>

Create a fresh active segment at the given base offset. Fails if the .log file already exists.

pub fn open_active( dir: &Path, base_offset: i64, validate: bool, ) -> Result<Self, LogError>

Open as the active segment, scanning from the last-indexed position to EOF when validate is true. A partial trailing batch (or one that fails to decode) is truncated; cleanly decoded batches update last_offset and max_timestamp.

pub fn open(dir: &Path, base_offset: i64) -> Result<Self, LogError>

Open an existing segment for reading. Lightweight — no full scan. Open an existing segment for reading. The log and index files must already exist on disk; the segment is initialized with last_offset = base_offset - 1 and max_timestamp = i64::MIN until tail recovery (via Segment::open_active) populates them.

pub fn base_offset(&self) -> i64

Absolute offset of the first record this segment can hold.

pub fn txn_index_path(&self) -> PathBuf

Path to this segment’s .txnindex file (may not exist yet).

pub fn leader_epoch_checkpoint_path(&self) -> PathBuf

Path to the per-partition .leader-epoch-checkpoint file in this segment’s directory. The checkpoint is shared across all segments in a partition — epoch history accumulates over the log’s lifetime.

pub fn last_offset(&self) -> i64

Highest absolute offset (inclusive) of any batch appended to this segment. Returns base_offset - 1 for an empty segment.

pub fn size_bytes(&self) -> u64

Current .log file size in bytes.

pub fn max_timestamp(&self) -> i64

Highest timestamp observed across all batches in this segment. Returns i64::MIN for an empty segment.

pub fn offset_for_timestamp(&self, target_ts: i64) -> Option<(i64, i64)>

Absolute offset and record timestamp of the first record in this segment whose timestamp is >= target_ts. Uses the sparse time index for a floor position, then scans .log batches forward (the index is sparse, so an exact answer needs the post-index scan — matching Kafka’s LogSegment.findOffsetByTimestamp). Returns None when no record in this segment qualifies.

pub fn offset_of_max_timestamp(&self) -> Option<(i64, i64)>

Absolute offset and timestamp of the record carrying this segment’s max_timestamp. Ties resolve to the earliest offset (Kafka). Returns None for an empty segment. Uses the time index’s floor for the max to start the scan, then scans forward for the first record whose timestamp equals the segment max.

pub fn is_sealed(&self) -> bool

true once the segment has been sealed via Segment::seal; sealed segments reject appends.

pub fn read( &self, offset: i64, max_bytes: usize, ) -> Result<Vec<RecordBatch>, LogError>

Read batches starting at or just before offset, up to roughly max_bytes of .log data. Returns an empty Vec when offset is past last_offset.

pub fn read_raw( &self, fetch_offset: i64, limit_offset: i64, max_bytes: usize, ) -> Result<RawSegmentRead, LogError>

Read a contiguous run of complete, verbatim record-batch bytes beginning at the batch containing fetch_offset, including only batches whose base_offset < limit_offset, up to roughly max_bytes (always at least one batch — Kafka’s anti-stall rule). No record decoding: only fixed batch headers are read to find boundaries.

pub fn append( &mut self, batch: &RecordBatch, index_interval_bytes: u32, ) -> Result<u64, LogError>

Append a record batch. Returns the byte position where the batch starts.

Side effects:

• Updates log_size, max_timestamp, last_offset.
• Adds sparse index entries when bytes-since-last-entry exceeds index_interval_bytes (or for the first batch).

pub fn seal(&mut self)

Mark this segment as sealed. No more appends.

pub fn dir(&self) -> &Path

Directory holding this segment’s .log/.index/.timeindex files. Used by the compactor to read the underlying .log file directly, bypassing the Segment::read path which depends on the in-memory last_offset (which is stale for sealed segments loaded via Segment::open).

pub fn flush(&mut self) -> Result<(), LogError>

Force-sync everything to disk.

pub fn truncate_to_relative(&mut self, rel: u32) -> Result<(), LogError>

Truncate .log and indexes so no batches at relative_offset >= rel remain. Used by Log::truncate_to. Leaves the segment unsealed.

Trait Implementations

impl Debug for Segment

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.