use super::hint_page::PageOffsetHintTable;
use super::hint_shared::SharedObjectHintTable;
use flate2::write::ZlibEncoder;
use flate2::Compression;
use std::io::Write;
pub struct HintStreamBuilder {
buf: Vec<u8>,
pending_bits: u32,
pending_byte: u8,
}
impl HintStreamBuilder {
pub fn new() -> Self {
Self {
buf: Vec::new(),
pending_bits: 0,
pending_byte: 0,
}
}
pub fn write_bits(&mut self, value: u64, bits: u32) {
if bits == 0 {
return;
}
let mut remaining = bits;
while remaining > 0 {
let free = 8 - self.pending_bits;
if remaining >= free {
let shift = remaining - free;
let mask_u64: u64 = if free >= 64 {
u64::MAX
} else {
(1u64 << free) - 1
};
let chunk = ((value >> shift) & mask_u64) as u8;
self.pending_byte |= chunk;
self.buf.push(self.pending_byte);
self.pending_byte = 0;
self.pending_bits = 0;
remaining -= free;
} else {
let shift = free - remaining;
let mask_u64: u64 = if remaining >= 64 {
u64::MAX
} else {
(1u64 << remaining) - 1
};
let chunk = (value & mask_u64) as u8;
self.pending_byte |= chunk << shift;
self.pending_bits += remaining;
remaining = 0;
}
}
}
pub fn align_to_byte(&mut self) {
if self.pending_bits > 0 {
self.buf.push(self.pending_byte);
self.pending_byte = 0;
self.pending_bits = 0;
}
}
pub fn finish(mut self) -> Vec<u8> {
self.align_to_byte();
self.buf
}
pub fn byte_len(&self) -> usize {
self.buf.len()
}
}
impl Default for HintStreamBuilder {
fn default() -> Self {
Self::new()
}
}
pub struct HintStreamBytes {
pub uncompressed: Vec<u8>,
pub compressed: Vec<u8>,
pub shared_section_offset_in_uncompressed: usize,
}
fn write_bits_checked(
b: &mut HintStreamBuilder,
value: u64,
slot_bits: u32,
field_name: &str,
) -> crate::Result<()> {
let max = if slot_bits >= 64 {
u64::MAX
} else {
(1u64 << slot_bits) - 1
};
if value > max {
return Err(crate::Error::Unsupported(format!(
"hint stream: {field_name} value {value} does not fit in {slot_bits}-bit Annex F slot \
(max {max}) — file likely exceeds 4 GiB or has a malformed plan"
)));
}
b.write_bits(value, slot_bits);
Ok(())
}
fn encode_page_offset_header(
b: &mut HintStreamBuilder,
t: &PageOffsetHintTable,
) -> crate::Result<()> {
let h = &t.header;
write_bits_checked(b, h.least_object_count as u64, 32, "least_object_count")?;
write_bits_checked(b, h.location_of_first_page, 32, "location_of_first_page")?;
write_bits_checked(
b,
h.bits_object_count_delta as u64,
16,
"bits_object_count_delta",
)?;
write_bits_checked(b, h.least_page_length, 32, "least_page_length")?;
write_bits_checked(
b,
h.bits_page_length_delta as u64,
16,
"bits_page_length_delta",
)?;
write_bits_checked(b, h.least_content_offset, 32, "least_content_offset")?;
write_bits_checked(
b,
h.bits_content_offset_delta as u64,
16,
"bits_content_offset_delta",
)?;
write_bits_checked(b, h.least_content_length, 32, "least_content_length")?;
write_bits_checked(
b,
h.bits_content_length_delta as u64,
16,
"bits_content_length_delta",
)?;
write_bits_checked(
b,
h.bits_shared_object_count as u64,
16,
"bits_shared_object_count",
)?;
write_bits_checked(
b,
h.bits_shared_object_id as u64,
16,
"bits_shared_object_id",
)?;
write_bits_checked(b, h.bits_numerator as u64, 16, "bits_numerator")?;
write_bits_checked(b, h.denominator as u64, 16, "denominator")?;
Ok(())
}
fn encode_page_offset_entries(b: &mut HintStreamBuilder, t: &PageOffsetHintTable) {
let h = &t.header;
for entry in &t.entries {
b.write_bits(
entry.object_count_minus_least as u64,
h.bits_object_count_delta,
);
}
b.align_to_byte();
for entry in &t.entries {
b.write_bits(entry.page_length_minus_least, h.bits_page_length_delta);
}
b.align_to_byte();
for entry in &t.entries {
b.write_bits(entry.shared_object_count as u64, h.bits_shared_object_count);
}
b.align_to_byte();
for entry in &t.entries {
for &id in &entry.shared_object_ids {
b.write_bits(id as u64, h.bits_shared_object_id);
}
}
b.align_to_byte();
for entry in &t.entries {
for &num in &entry.shared_object_numerators {
b.write_bits(num as u64, h.bits_numerator);
}
}
b.align_to_byte();
for entry in &t.entries {
b.write_bits(entry.content_stream_offset, h.bits_content_offset_delta);
}
b.align_to_byte();
for entry in &t.entries {
b.write_bits(entry.content_stream_length, h.bits_content_length_delta);
}
b.align_to_byte();
}
fn encode_shared_object_header(
b: &mut HintStreamBuilder,
t: &SharedObjectHintTable,
) -> crate::Result<()> {
let h = &t.header;
write_bits_checked(
b,
h.first_object_number as u64,
32,
"shared.first_object_number",
)?;
write_bits_checked(b, h.location, 32, "shared.location")?;
write_bits_checked(
b,
h.first_page_entries as u64,
32,
"shared.first_page_entries",
)?;
write_bits_checked(b, h.section_entries as u64, 32, "shared.section_entries")?;
write_bits_checked(
b,
h.bits_group_object_count as u64,
16,
"shared.bits_group_object_count",
)?;
write_bits_checked(b, h.least_length, 32, "shared.least_length")?;
write_bits_checked(
b,
h.bits_length_delta as u64,
16,
"shared.bits_length_delta",
)?;
Ok(())
}
fn encode_shared_object_groups(b: &mut HintStreamBuilder, t: &SharedObjectHintTable) {
let h = &t.header;
for group in &t.groups {
b.write_bits(group.object_count as u64, h.bits_group_object_count);
}
}
fn encode_shared_object_entries(b: &mut HintStreamBuilder, t: &SharedObjectHintTable) {
let h = &t.header;
for entry in &t.objects {
b.write_bits(entry.length_minus_least as u64, h.bits_length_delta);
}
b.align_to_byte();
for entry in &t.objects {
b.write_bits(if entry.signature_present { 1 } else { 0 }, 1);
if entry.signature_present {
if let Some(sig) = &entry.signature {
for &byte in sig {
b.write_bits(byte as u64, 8);
}
}
}
}
b.align_to_byte();
for entry in &t.objects {
b.write_bits(entry.nobjects_minus_one as u64, h.bits_group_object_count);
}
b.align_to_byte();
}
pub fn encode_hint_stream(
page_offset: &PageOffsetHintTable,
shared_object: &SharedObjectHintTable,
) -> crate::Result<HintStreamBytes> {
let mut builder = HintStreamBuilder::new();
encode_page_offset_header(&mut builder, page_offset)?;
builder.align_to_byte();
encode_page_offset_entries(&mut builder, page_offset);
builder.align_to_byte();
let shared_section_offset = builder.byte_len();
encode_shared_object_header(&mut builder, shared_object)?;
builder.align_to_byte();
encode_shared_object_groups(&mut builder, shared_object);
builder.align_to_byte();
encode_shared_object_entries(&mut builder, shared_object);
builder.align_to_byte();
let uncompressed = builder.finish();
let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
encoder
.write_all(&uncompressed)
.expect("ZlibEncoder::write_all on Vec<u8> must not fail");
let compressed = encoder
.finish()
.expect("ZlibEncoder::finish on Vec<u8> must not fail");
Ok(HintStreamBytes {
uncompressed,
compressed,
shared_section_offset_in_uncompressed: shared_section_offset,
})
}
#[cfg(test)]
mod tests {
use super::*;
use crate::linearization::hint_page::PageOffsetHintTable;
use crate::linearization::hint_shared::SharedObjectHintTable;
use crate::linearization::plan::{LinearizationPlan, PageHintEntry, SharedObjectHintEntry};
use crate::linearization::renumber::RenumberMap;
use crate::ObjectRef;
fn single_page_plan() -> LinearizationPlan {
LinearizationPlan {
part2_objects: vec![
ObjectRef::new(3, 0),
ObjectRef::new(2, 0),
ObjectRef::new(1, 0),
],
total_object_count: 3,
page_hints: vec![PageHintEntry {
page_ref: ObjectRef::new(3, 0),
first_object_index: 0,
object_count: 3,
byte_length: 0,
}],
..Default::default()
}
}
fn two_page_plan_with_shared() -> LinearizationPlan {
LinearizationPlan {
part2_objects: vec![ObjectRef::new(3, 0), ObjectRef::new(6, 0)],
part3_objects: vec![ObjectRef::new(5, 0), ObjectRef::new(8, 0)],
part4_other_pages_private: vec![ObjectRef::new(4, 0), ObjectRef::new(7, 0)],
total_object_count: 8,
page_hints: vec![
PageHintEntry {
page_ref: ObjectRef::new(3, 0),
first_object_index: 0,
object_count: 3,
byte_length: 0,
},
PageHintEntry {
page_ref: ObjectRef::new(4, 0),
first_object_index: 0,
object_count: 5,
byte_length: 0,
},
],
shared_hints: vec![
SharedObjectHintEntry {
object_ref: ObjectRef::new(5, 0),
referencing_pages: vec![0, 1],
},
SharedObjectHintEntry {
object_ref: ObjectRef::new(8, 0),
referencing_pages: vec![0, 1],
},
],
..Default::default()
}
}
#[test]
fn builder_write_zero_bits_is_noop() {
let mut b = HintStreamBuilder::new();
b.write_bits(0xFF, 0); let out = b.finish();
assert!(out.is_empty(), "write_bits(x, 0) must be a no-op");
}
#[test]
fn builder_write_8_bits_produces_one_byte() {
let mut b = HintStreamBuilder::new();
b.write_bits(0xAB, 8);
let out = b.finish();
assert_eq!(out, vec![0xAB]);
}
#[test]
fn builder_write_16_bits_produces_two_bytes() {
let mut b = HintStreamBuilder::new();
b.write_bits(0xABCD, 16);
let out = b.finish();
assert_eq!(out, vec![0xAB, 0xCD]);
}
#[test]
fn builder_write_4_plus_4_bits() {
let mut b = HintStreamBuilder::new();
b.write_bits(0b1010, 4); b.write_bits(0b0101, 4); let out = b.finish();
assert_eq!(out, vec![0xA5]);
}
#[test]
fn builder_write_1_bit_msb_first() {
let mut b = HintStreamBuilder::new();
b.write_bits(1, 1);
b.write_bits(0, 1);
b.write_bits(1, 1);
b.write_bits(0, 1);
b.write_bits(0, 1);
b.write_bits(0, 1);
b.write_bits(0, 1);
b.write_bits(0, 1);
let out = b.finish();
assert_eq!(out, vec![0xA0]);
}
#[test]
fn builder_align_to_byte_pads_with_zeros() {
let mut b = HintStreamBuilder::new();
b.write_bits(1, 1); b.align_to_byte();
let out = b.finish();
assert_eq!(out, vec![0x80]);
}
#[test]
fn builder_align_on_boundary_is_noop() {
let mut b = HintStreamBuilder::new();
b.write_bits(0xAB, 8); b.align_to_byte(); let out = b.finish();
assert_eq!(out, vec![0xAB]);
}
#[test]
fn builder_cross_byte_boundary() {
let mut b = HintStreamBuilder::new();
b.write_bits(0b1100_1010_0011, 12);
let out = b.finish();
assert_eq!(out, vec![0xCA, 0x30]);
}
#[test]
fn builder_write_32_bits() {
let mut b = HintStreamBuilder::new();
b.write_bits(0xDEAD_BEEF, 32);
let out = b.finish();
assert_eq!(out, vec![0xDE, 0xAD, 0xBE, 0xEF]);
}
#[test]
fn builder_sequence_3_bits_then_5_bits() {
let mut b = HintStreamBuilder::new();
b.write_bits(0b101, 3);
b.write_bits(0b10110, 5);
let out = b.finish();
assert_eq!(out, vec![0b1011_0110]); }
#[test]
fn single_page_encode_does_not_panic() {
let plan = single_page_plan();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let _ = encode_hint_stream(&po, &so).expect("encode"); }
#[test]
fn single_page_shared_section_offset_is_positive() {
let plan = single_page_plan();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(
result.shared_section_offset_in_uncompressed > 0,
"shared section must start after the page offset section"
);
}
#[test]
fn single_page_compressed_starts_with_zlib_header() {
let plan = single_page_plan();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(
result.compressed.len() >= 2,
"compressed output must have at least 2 bytes (zlib header)"
);
assert_eq!(
result.compressed[0], 0x78,
"first byte must be 0x78 (zlib CMF)"
);
assert!(
result.compressed[1] == 0x9C
|| result.compressed[1] == 0xDA
|| result.compressed[1] == 0x01,
"second byte must be a valid zlib FLG (0x9C, 0xDA, or 0x01), got 0x{:02X}",
result.compressed[1]
);
}
#[test]
fn single_page_shared_section_within_uncompressed() {
let plan = single_page_plan();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(
result.shared_section_offset_in_uncompressed <= result.uncompressed.len(),
"shared section offset must be within the uncompressed stream"
);
}
#[test]
fn two_page_encode_does_not_panic() {
let plan = two_page_plan_with_shared();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let _ = encode_hint_stream(&po, &so).expect("encode");
}
#[test]
fn two_page_shared_section_offset_is_positive() {
let plan = two_page_plan_with_shared();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(result.shared_section_offset_in_uncompressed > 0);
}
#[test]
fn two_page_compressed_starts_with_zlib_header() {
let plan = two_page_plan_with_shared();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(result.compressed.len() >= 2);
assert_eq!(result.compressed[0], 0x78);
}
#[test]
fn two_page_uncompressed_larger_than_single_page() {
let single_plan = single_page_plan();
let renumber_s = RenumberMap::from_plan(&single_plan);
let po_s = PageOffsetHintTable::from_plan(&single_plan, &renumber_s);
let so_s = SharedObjectHintTable::from_plan(&single_plan, &renumber_s);
let single_result = encode_hint_stream(&po_s, &so_s).expect("encode");
let two_plan = two_page_plan_with_shared();
let renumber_t = RenumberMap::from_plan(&two_plan);
let po_t = PageOffsetHintTable::from_plan(&two_plan, &renumber_t);
let so_t = SharedObjectHintTable::from_plan(&two_plan, &renumber_t);
let two_result = encode_hint_stream(&po_t, &so_t).expect("encode");
assert!(
two_result.uncompressed.len() > single_result.uncompressed.len(),
"two-page plan with shared objects must produce a larger stream"
);
}
#[test]
fn no_shared_encode_succeeds() {
let plan = single_page_plan(); let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert!(result.shared_section_offset_in_uncompressed > 0);
assert!(!result.uncompressed.is_empty());
assert!(!result.compressed.is_empty());
}
#[test]
fn page_offset_header_size_is_36_bytes() {
let plan = single_page_plan();
let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert_eq!(
result.shared_section_offset_in_uncompressed, 36,
"single-page plan with all-zero bit widths: shared section must start at byte 36"
);
}
#[test]
fn shared_object_header_total_size() {
let plan = single_page_plan(); let renumber = RenumberMap::from_plan(&plan);
let po = PageOffsetHintTable::from_plan(&plan, &renumber);
let so = SharedObjectHintTable::from_plan(&plan, &renumber);
let result = encode_hint_stream(&po, &so).expect("encode");
assert_eq!(
result.uncompressed.len(),
60,
"single-page no-shared plan: uncompressed stream must be 60 bytes (36 + 24)"
);
}
}