rustensor 0.1.0

Small Rust-native checkpoint format for model metadata and tensor weights.
Documentation
//! RTEN binary format definitions.
//!
//! This module defines the fixed 48-byte `.rten` header, format constants,
//! encoding and defensive decoding rules.
use std::ops::Range;

use crate::error::{Result, RustensorError};

pub const MAGIC_BYTES: [u8; 4] = *b"RTEN";
pub const FORMAT_VERSION: u16 = 1;

// Flags are reserved for future format capabilities.
// Bit 0: reserved, future compression flag.
// Bit 1: reserved, future encrypted payload flag.
// Bits 2-15: reserved.
// In format v1 all flags must be zero.
pub const FLAGS_NONE: u16 = 0;

pub const HEADER_SIZE: usize = 48;
pub const CHECKSUM_SIZE: usize = 32;
pub const MAX_PAYLOAD_SIZE: u64 = 64 * 1024 * 1024;

pub const MAGIC_RANGE: Range<usize> = 0..4;
pub const VERSION_RANGE: Range<usize> = 4..6;
pub const FLAGS_RANGE: Range<usize> = 6..8;
pub const PAYLOAD_LENGTH_RANGE: Range<usize> = 8..16;
pub const CHECKSUM_RANGE: Range<usize> = 16..48;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RtenHeader {
    pub version: u16,
    pub flags: u16,
    pub payload_length: u64,
    pub checksum: [u8; CHECKSUM_SIZE],
}

impl RtenHeader {
    pub fn new(payload_length: u64, checksum: [u8; CHECKSUM_SIZE]) -> Result<Self> {
        if payload_length > MAX_PAYLOAD_SIZE {
            return Err(RustensorError::PayloadTooLarge {
                found: payload_length,
                max: MAX_PAYLOAD_SIZE,
            });
        }

        Ok(Self {
            version: FORMAT_VERSION,
            flags: FLAGS_NONE,
            payload_length,
            checksum,
        })
    }

    pub fn encode(&self) -> Result<[u8; HEADER_SIZE]> {
        if self.version != FORMAT_VERSION {
            return Err(RustensorError::UnsupportedVersion {
                found: self.version,
                supported: FORMAT_VERSION,
            });
        }

        if self.flags != FLAGS_NONE {
            return Err(RustensorError::InvalidFlags { found: self.flags });
        }

        if self.payload_length > MAX_PAYLOAD_SIZE {
            return Err(RustensorError::PayloadTooLarge {
                found: self.payload_length,
                max: MAX_PAYLOAD_SIZE,
            });
        }

        let mut bytes = [0u8; HEADER_SIZE];

        bytes[MAGIC_RANGE].copy_from_slice(MAGIC_BYTES.as_slice());
        bytes[VERSION_RANGE].copy_from_slice(&self.version.to_le_bytes());
        bytes[FLAGS_RANGE].copy_from_slice(&self.flags.to_le_bytes());
        bytes[PAYLOAD_LENGTH_RANGE].copy_from_slice(&self.payload_length.to_le_bytes());
        bytes[CHECKSUM_RANGE].copy_from_slice(&self.checksum);

        Ok(bytes)
    }

    pub fn decode(bytes: &[u8]) -> Result<Self> {
        if bytes.len() < HEADER_SIZE {
            return Err(RustensorError::InvalidHeader);
        }

        if &bytes[MAGIC_RANGE] != MAGIC_BYTES.as_slice() {
            return Err(RustensorError::InvalidMagic);
        }

        let version = u16::from_le_bytes(
            bytes[VERSION_RANGE]
                .try_into()
                .map_err(|_| RustensorError::InvalidHeader)?,
        );

        if version != FORMAT_VERSION {
            return Err(RustensorError::UnsupportedVersion {
                found: version,
                supported: FORMAT_VERSION,
            });
        }

        let flags = u16::from_le_bytes(
            bytes[FLAGS_RANGE]
                .try_into()
                .map_err(|_| RustensorError::InvalidHeader)?,
        );

        if flags != FLAGS_NONE {
            return Err(RustensorError::InvalidFlags { found: flags });
        }

        let payload_length = u64::from_le_bytes(
            bytes[PAYLOAD_LENGTH_RANGE]
                .try_into()
                .map_err(|_| RustensorError::InvalidHeader)?,
        );

        if payload_length > MAX_PAYLOAD_SIZE {
            return Err(RustensorError::PayloadTooLarge {
                found: payload_length,
                max: MAX_PAYLOAD_SIZE,
            });
        }

        let mut checksum = [0u8; CHECKSUM_SIZE];
        checksum.copy_from_slice(&bytes[CHECKSUM_RANGE]);

        Ok(Self {
            version,
            flags,
            payload_length,
            checksum,
        })
    }
}