pdftract/notes/pdftract-6bxw.md

Verification Note: pdftract-6bxw - Object Stream (ObjStm) Parser

Task

Implement object stream (ObjStm) parser with decompress, cache, and /Extends chain.

Implementation Summary

Files

• crates/pdftract-core/src/parser/objstm.rs - Complete ObjStm parser implementation (1280 lines)
• crates/pdftract-core/src/parser/mod.rs - Re-exports ObjStm types

Implementation Details

The ObjectStmParser provides:

1. Decompression: Uses Phase 1.5's decode_stream() function to decompress ObjStm stream data
2. Caching: Arc<RwLock<HashMap<ObjRef, ObjStmCacheEntry>>> for thread-safe cached access
3. Extends chain: Recursive loading with cycle detection (HashSet in_progress) and depth limit (MAX_EXTENDS_DEPTH = 16)
4. API:
   • get_object(host_objstm_ref, embedded_index, source, resolve_fn) - Main API for xref type-2 entry resolution
   • load_object_stream(obj_stm_ref, stream, source, resolve_fn) - Bulk loading API
   • get_cached(obj_ref) - Check cache without loading
   • is_cached(obj_ref) - Check if cached
   • take_diagnostics() - Get accumulated diagnostics

Key Features

1. Object Stream Format:

   • Header: N pairs of (object_number, offset) in first /First bytes
   • Body: N embedded objects (no obj/endobj wrapper per spec)
   • Optional /Extends N G R for chain to parent ObjStm

2. Error Handling (ObjStmError enum):

   • MissingKey: Required /N or /First missing → DiagCode::StructMissingKey
   • InvalidFormat: Malformed header or data → DiagCode::StructInvalidObjstm
   • CircularRef: Cycle detected in /Extends chain → DiagCode::StructCircularRef
   • DepthExceeded: /Extends chain exceeds 16 levels → DiagCode::StructDepthExceeded
   • DecompressionFailed: Stream decompression failed → DiagCode::StreamDecodeError

3. Safety:

   • Decompression bomb limit enforced via doc_decompress_counter
   • Embedded streams rejected (spec violation) → STRUCT_INVALID_OBJSTM diagnostic
   • Thread-safe caching with Arc<Vec<...>> for concurrent reads
   • Cycle detection prevents infinite loops in /Extends chains

Acceptance Criteria Status

Criterion	Status	Test
Critical test: N=10 objects all dereference correctly	✅ PASS	test_parse_objstm_10_objects
/Extends chain: both ObjStms' objects dereference correctly	✅ PASS	test_objstm_extends_chain
Cyclic /Extends: emits STRUCT_CIRCULAR_REF, no infinite loop	✅ PASS	test_circular_ref_detection
Truncated ObjStm: partial objects + STRUCT_INVALID_OBJSTM	✅ PASS	test_truncated_objstm_body
Decompression bomb: emits STREAM_BOMB	✅ PASS	test_decompression_bomb_objstm
Cache hit: returns cached Arc (Arc::ptr_eq verified)	✅ PASS	test_cache_hit
Missing /N or /First: emits STRUCT_MISSING_KEY	✅ PASS	test_missing_key_n, test_missing_key_first
/Extends depth exceeded: emits STRUCT_DEPTH_EXCEEDED	✅ PASS	test_extends_depth_exceeded
Embedded stream rejected: emits STRUCT_INVALID_OBJSTM	✅ PASS	test_embedded_stream_rejected
get_object API for type-2 entries	✅ PASS	test_get_object_api

Test Results (2026-05-22)

running 16 tests
test parser::objstm::tests::test_max_extends_depth ... ok
test parser::objstm::tests::test_missing_key_first ... ok
test parser::objstm::tests::test_circular_ref_detection ... ok
test parser::objstm::tests::test_obj_stm_parser_default ... ok
test parser::objstm::tests::test_missing_key_n ... ok
test parser::objstm::tests::test_obj_stm_error_display ... ok
test parser::objstm::tests::test_obj_stm_parser_new ... ok
test parser::objstm::tests::test_decompression_bomb_objstm ... ok
test parser::objstm::tests::test_cache_hit ... ok
test parser::objstm::tests::test_get_object_api ... ok
test parser::objstm::tests::test_embedded_stream_rejected ... ok
test parser::objstm::tests::test_parse_simple_objstm ... ok
test parser::objstm::tests::test_truncated_objstm_body ... ok
test parser::objstm::tests::test_objstm_extends_chain ... ok
test parser::objstm::tests::test_parse_objstm_10_objects ... ok
test parser::objstm::tests::test_extends_depth_exceeded ... ok

test result: ok. 16 passed; 0 failed; 0 ignored; 0 measured; 442 filtered out

Integration Points

1. Phase 1.3 (xref): The get_object() method is designed to be called by the xref resolver when it encounters a type-2 (compressed) xref entry (XrefEntry::Compressed { obj_stm_nr, index }). The API signature accepts (host_objstm_ref, embedded_index) and returns PdfObject.

2. Phase 1.5 (stream decoder): Uses decode_stream() function to decompress the ObjStm stream data with full filter pipeline support (FlateDecode, ASCII85Decode, etc.).

3. Diagnostics: Emits diagnostics using the unified crate::diagnostics module with proper error codes (StructMissingKey, StructCircularRef, StructDepthExceeded, StructInvalidObjstm, StreamBomb).

References

• Plan section: Phase 1.2 line 1072 (object streams)
• PDF spec 7.5.7 (Object Streams)
• INV-8 (never panic, always return partial data on errors)