This is a work-in-progress reimplementation of a JPEG XL decoder in Rust, aiming to be conforming, safe, and fast.

We strive to decode all conformant JPEG XL bitstreams correctly. If you find an image that can be decoded with the reference implementation djxl (from libjxl) but is decoded incorrectly or not at all by jxl-rs, please report it by opening an issue.

For more information, including contributing instructions, refer to the libjxl repository.

This branch (develop) contains improvements being prepared for upstream contribution to libjxl/jxl-rs.

1. Zero Panic - Eliminate all potential panics from untrusted input; all errors should be recoverable
2. Fallible Allocation - Support environments where allocation can fail gracefully
3. JXL Parity - Pixel-perfect output matching the reference djxl implementation
4. Performance Parity - Match or exceed libjxl decode performance

All changes in this branch are released under the same BSD-style license as jxl-rs and are contributed under the Google CLA. These changes are intended to be upstreamed to the official libjxl/jxl-rs repository.

This branch adds comprehensive protection against "JXL bombs" - maliciously crafted files designed to exhaust memory or CPU. These features support the Zero Panic and Fallible Allocation goals.

The JxlDecoderLimits struct provides configurable limits for all decoder resource consumption:

use jxl::api::{JxlDecoderLimits, JxlDecoderOptions};

// For untrusted web content - restrictive limits
let options = JxlDecoderOptions {
    limits: JxlDecoderLimits::restrictive(),
    ..Default::default()
};

// For trusted local files - default limits
let options = JxlDecoderOptions::default();

// For maximum compatibility (use with caution)
let options = JxlDecoderOptions {
    limits: JxlDecoderLimits::unlimited(),
    ..Default::default()
};

All limits return Error::LimitExceeded with details when exceeded:

Error::LimitExceeded {
    resource: "pixels",      // Which limit was hit
    actual: 2_000_000_000,   // Attempted value
    limit: 1_073_741_824,    // Configured limit
}

When max_memory_bytes is set, the decoder tracks all significant allocations through a thread-safe MemoryTracker:

// Limit decoder to 512 MB total memory
let options = JxlDecoderOptions {
    limits: JxlDecoderLimits {
        max_memory_bytes: Some(512 * 1024 * 1024),
        ..Default::default()
    },
    ..Default::default()
};

How it works:

1. The MemoryTracker uses atomic operations for lock-free tracking
2. Clone is cheap (Arc-based) - all decoder components share the same counter
3. Allocations are checked before allocation, rolling back on failure
4. MemoryGuard RAII type ensures memory is released even on errors

Implementation details (util/memory_tracker.rs):

• try_allocate(bytes) - Attempt allocation, returns Error::LimitExceeded if over budget
• release(bytes) - Return memory to budget (called on deallocation)
• would_exceed(bytes) - Check without allocating (for early rejection)
• MemoryGuard - RAII guard that releases memory on drop

The util/vec_helpers.rs module provides fallible allocation for OOM-resistant decoding:

use jxl::util::vec_helpers::{NewWithCapacity, TryVecExt, AlignedVec};

// Fallible Vec creation (won't panic on OOM)
let vec: Vec<u8> = Vec::new_with_capacity(1024)?;

// Fallible element-filled vector
let zeros = Vec::<f32>::try_from_elem(0.0, 1024)?;

// SIMD-aligned allocation (64-byte for AVX-512)
let aligned: AlignedVec<f32> = aligned_vec_with_capacity(1024)?;
let zeroed: AlignedVec<f32> = aligned_vec_zeroed(1024)?;

Key types:

• NewWithCapacity trait - Fallible Vec/String allocation via try_reserve
• TryVecExt trait - Additional fallible operations (try_from_elem, try_extend_from_slice)
• AlignedVec<T> - 64-byte aligned vector for optimal SIMD performance
• All return TryReserveError on allocation failure instead of panicking

The CancellationToken enables cooperative cancellation for long-running decodes:

use jxl::api::CancellationToken;
use std::thread;
use std::time::Duration;

let token = CancellationToken::new();
let token_clone = token.clone();

// Cancel from another thread after timeout
thread::spawn(move || {
    thread::sleep(Duration::from_secs(5));
    token_clone.cancel();
});

// Decoder checks token at safe points and returns Error::Cancelled
let options = JxlDecoderOptions {
    cancellation_token: Some(token),
    ..Default::default()
};

API:

• cancel() - Signal cancellation (atomic, thread-safe)
• is_cancelled() - Check status
• reset() - Clear cancellation for reuse
• check() - Returns Error::Cancelled if cancelled

Against codec-corpus (184 JXL files with djxl reference output):

• 184/184 passing (100%)

All test images decode with pixel-exact or near-exact parity, including:

• Single-layer CMYK with ICC profiles
• Multi-layer CMYK with alpha blending (blending in CMYK space, then CMS conversion)
• All modular/VarDCT encoding modes
• Animation and layer compositing

See PARITY_INVESTIGATION.md for detailed bug investigation notes.

Against libjxl/conformance test suite (Level 5):

• 17/23 passing (74%)

# Run conformance tests (auto-fetches test data on first run)
cargo test --features cms conformance -- --ignored --nocapture

1. Animation frame iteration - Add API to decode individual frames for animation tests

   • Current API composites all frames into final output
   • Need next_frame() / is_last_frame() methods on decoder

2. Spot color output - Support outputting all channels including spot colors

   • spot test expects 6 channels (RGB + 2 spot colors)
   • Currently only outputting 4 channels (RGBA)

3. Investigate remaining decode bugs - Debug out-of-gamut/HDR value differences

   • bike_5 has 13 pixels with out-of-gamut (negative) values differing from reference
   • progressive_5 has many pixels with HDR (> 1.0) values differing from reference
   • May be related to XYB-to-RGB matrix or opsin inverse handling of extreme values

84 files changed, 8813 insertions(+), 664 deletions(-)

da0c8cc merge: integrate security features from fix/parity-tests-and-bugfixes
cd4d96a docs: update README with full changelog vs upstream
5095a2a fix: improve conformance test ICC handling, 16/23 -> 17/23 passing
7959f04 docs: add conformance test status and TODOs to README
3b42220 feat: auto-fetch conformance test data on first run
26cdc9e feat: add official JPEG XL conformance test infrastructure
b8cff3c fix: CMYK blending order - blend in CMYK space then convert to RGB
375c5ef chore: upgrade moxcms from 0.5 to 0.7

Security & Allocation Features:
ae7ce8f security: implement max_memory_bytes tracking and fallible allocations
362f109 security: wire up max_patches limit and add aligned allocation utilities
0c16e7a test: add limit enforcement and cancellation tests
1bd9b2f feat: enforce security limits and add cancellation support
4b3b659 feat: add CancellationToken and memory budget limit
0b7ebec security: add configurable JxlDecoderLimits API
325414b security: use checked arithmetic instead of saturating for limit calculations
a6ae2ad security: fix ICC tag and render builder overflow vulnerabilities
08d36ce security: fix integer overflow vulnerabilities in patches, splines, size

Earlier commits:
7eb846f fix: correct noise generation seeding for upsampled frames
590adb8 feat: add CMS-based CMYK to RGB conversion stage
c4ee8f1 feat: add BlackChannelStage for CMYK to RGB conversion
908170c fix: use extra channel's own bit_depth for modular-to-f32 conversion
4bad28f feat: add optional moxcms CMS integration
16ff26e feat: add UnpremultiplyAlphaStage for future alpha handling
f594118 fix: correct last_pass validation to require strictly increasing
b87a384 fix: detect grayscale from default pixel format, not output profile
9cfce3f fix: detect linear gamma from reference PNG gAMA chunk
6d49aee fix: extra channel format slots allocation
dfa374f fix: apply sRGB transfer function for XYB-encoded images
5d8e1ff fix: RCT transform overflow panic with wrapping arithmetic
... (earlier commits establishing test infrastructure)

The following PRs have been submitted to upstream jxl-rs: