Struct FileHeader 

pub struct FileHeader {
    pub app_version: String,
    pub format_version: u16,
    pub original_filename: String,
    pub original_size: u64,
    pub original_checksum: String,
    pub output_checksum: String,
    pub processing_steps: Vec<ProcessingStep>,
    pub chunk_size: u32,
    pub chunk_count: u32,
    pub processed_at: DateTime<Utc>,
    pub pipeline_id: String,
    pub metadata: HashMap<String, String>,
}

File header for Adaptive Pipeline processed files (.adapipe format)

This header contains all information needed to:

1. Recover the original document (filename, size, processing steps)
2. Verify integrity of the processed output file we created
3. Validate the restored input file matches the original exactly

Adaptive Pipeline File Format (.adapipe)

[CHUNK_DATA][JSON_HEADER][HEADER_LENGTH][FORMAT_VERSION][MAGIC_BYTES]

Note: This is NOT a general binary file format like .png or .exe. This is specifically for files processed by the Adaptive Pipeline system that have been compressed and/or encrypted with restoration metadata.

Recovery Process

Fields

app_version: String

Application version that created this file

format_version: u16

File format version for backward compatibility

original_filename: String

Original input filename (for restoration)

original_size: u64

Original file size in bytes (for validation)

original_checksum: String

SHA256 checksum of original input file (for validation)

output_checksum: String

SHA256 checksum of this output file (for integrity verification)

processing_steps: Vec<ProcessingStep>

Processing pipeline information (for restoration)

chunk_size: u32

Chunk size used for processing

chunk_count: u32

Number of chunks in the processed file

processed_at: DateTime<Utc>

Processing timestamp (RFC3339)

pipeline_id: String

Pipeline ID that processed this file

metadata: HashMap<String, String>

Additional metadata for debugging/auditing

Implementations

impl FileHeader

pub fn new( original_filename: String, original_size: u64, original_checksum: String, ) -> Self

Creates a new file header with default values

Purpose

Creates a FileHeader for tracking processing metadata and enabling file recovery. The header stores all information needed to validate and restore processed files.

Why

File headers provide:

• Recovery information to restore original files
• Integrity verification through checksums
• Processing history for debugging and auditing
• Version management for backward compatibility

Arguments

• original_filename - Name of the original input file (for restoration)
• original_size - Size of the original file in bytes (for validation)
• original_checksum - SHA256 checksum of original file (for validation)

Returns

FileHeader with default values:

• app_version: Current package version from Cargo.toml
• format_version: Current format version (1)
• chunk_size: 1MB default
• processed_at: Current timestamp
• Empty processing steps, pipeline ID, and metadata

Examples

pub fn add_compression_step(self, algorithm: &str, level: u32) -> Self

Adds a compression step to the processing pipeline

Purpose

Records a compression operation in the processing steps. This information is used during file recovery to decompress the data.

Arguments

• algorithm - Name of compression algorithm (e.g., “brotli”, “gzip”, “zstd”, “lz4”)
• level - Compression level (algorithm-specific, typically 1-9)

Returns

Updated FileHeader with compression step added (builder pattern)

Examples

pub fn add_encryption_step( self, algorithm: &str, key_derivation: &str, key_size: u32, nonce_size: u32, ) -> Self

Adds an encryption step

pub fn add_custom_step( self, step_name: &str, algorithm: &str, parameters: HashMap<String, String>, ) -> Self

Adds a custom processing step

pub fn add_processing_step(self, descriptor: ProcessingStepDescriptor) -> Self

Adds a processing step using domain-driven ProcessingStepDescriptor This is the preferred method that respects DIP and uses Value Objects

pub fn add_checksum_step(self, algorithm: &str) -> Self

Adds a checksum processing step

pub fn add_passthrough_step(self, algorithm: &str) -> Self

Adds a pass-through processing step

pub fn with_chunk_info(self, chunk_size: u32, chunk_count: u32) -> Self

Sets chunk processing information

pub fn with_pipeline_id(self, pipeline_id: String) -> Self

Sets pipeline ID

pub fn with_output_checksum(self, checksum: String) -> Self

Sets output file checksum (call after processing is complete)

pub fn with_metadata(self, key: String, value: String) -> Self

Adds metadata

pub fn to_footer_bytes(&self) -> Result<Vec<u8>, PipelineError>

Serializes the header to binary format for file footer

Purpose

Converts the header to the binary footer format that is appended to processed files. The footer allows reading metadata from the end of files without scanning the entire file.

Why

Storing metadata at the end provides:

• Efficient metadata access without reading full file
• Streaming-friendly format (header written after data)
• Simple format detection via magic bytes at end

Binary Format

[JSON_HEADER][HEADER_LENGTH (4 bytes)][FORMAT_VERSION (2 bytes)][MAGIC_BYTES (8 bytes)]

Returns

• Ok(Vec<u8>) - Serialized footer bytes
• Err(PipelineError::SerializationError) - JSON serialization failed

Errors

Returns PipelineError::SerializationError if JSON serialization fails.

Examples

pub fn from_footer_bytes( file_data: &[u8], ) -> Result<(Self, usize), PipelineError>

Deserializes the header from file footer bytes

Purpose

Extracts and parses the file header from the footer at the end of a processed file. This is the primary method for reading metadata from .adapipe files.

Why

Reading from the footer enables:

• Quick metadata access without processing entire file
• Format validation before attempting recovery
• Backward compatibility checking

Arguments

• file_data - Complete file data including footer

Returns

• Ok((FileHeader, usize)) - Parsed header and total footer size in bytes
• Err(PipelineError) - Validation or parsing error

Errors

Returns PipelineError when:

• File too short (< 14 bytes minimum footer size)
• Invalid magic bytes (not an .adapipe file)
• Unsupported format version
• Incomplete footer data
• Invalid UTF-8 in JSON header
• JSON deserialization fails

Examples

pub fn verify_output_integrity( &self, file_data: &[u8], ) -> Result<bool, PipelineError>

Verifies the integrity of the processed output file

Purpose

Validates that the processed file data has not been corrupted or tampered with by comparing its SHA256 checksum against the stored checksum.

Why

Integrity verification provides:

• Detection of file corruption during storage or transmission
• Protection against data tampering
• Confidence in file recovery operations

Arguments

• file_data - Complete processed file data (including footer)

Returns

• Ok(true) - File integrity verified, checksum matches
• Ok(false) - File corrupted, checksum mismatch
• Err(PipelineError::ValidationError) - No checksum available

Errors

Returns PipelineError::ValidationError if output_checksum is empty.

Examples

pub fn get_restoration_steps(&self) -> Vec<&ProcessingStep>

Gets the processing steps in reverse order for file restoration

Purpose

Returns processing steps in the order they must be reversed to restore the original file. For example, if compression then encryption was applied, restoration must decrypt then decompress.

Why

Processing operations must be reversed in opposite order:

• Apply: Compress → Encrypt
• Restore: Decrypt → Decompress

Returns

Vector of processing steps sorted by descending order (highest order first)

Examples

pub fn validate_restored_file( &self, restored_data: &[u8], ) -> Result<bool, PipelineError>

Validates a restored file against original specifications

Purpose

Verifies that a restored file matches the original file exactly by checking both size and SHA256 checksum. This ensures complete recovery fidelity.

Why

Restoration validation provides:

• Confidence that recovery was successful
• Detection of processing errors or data loss
• Verification of processing reversibility

Arguments

• restored_data - The restored/recovered file data

Returns

• Ok(true) - Restored file matches original (size and checksum)
• Ok(false) - Restored file does not match original

Examples

pub fn get_processing_summary(&self) -> String

Gets information about what processing was applied

pub fn is_compressed(&self) -> bool

Checks if the file uses compression

pub fn is_encrypted(&self) -> bool

Checks if the file uses encryption

pub fn compression_algorithm(&self) -> Option<&str>

Gets the compression algorithm if used

pub fn encryption_algorithm(&self) -> Option<&str>

Gets the encryption algorithm if used

pub fn validate(&self) -> Result<(), PipelineError>

Validates the header for consistency

Trait Implementations

impl Clone for FileHeader

fn clone(&self) -> FileHeader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FileHeader

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

Formats the value using the given formatter.

impl Default for FileHeader

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for FileHeader

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for FileHeader

fn eq(&self, other: &FileHeader) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for FileHeader

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for FileHeader