Merge pull request #344 from tinyhumansai/png-optimize-feature

feat(harness): make PNG re-compression an opt-in png-optimize feature

Author: senamakel

.github/workflows/ci.yml

@@ -107,6 +107,8 @@ jobs:
             features: "--no-default-features --features tools"
           - name: multimodal
             features: "--no-default-features --features multimodal"
+          - name: png-optimize
+            features: "--no-default-features --features png-optimize"
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:

README.md

@@ -29,7 +29,7 @@ TinyAgents is a Cargo workspace, not one crate. Depend on the pieces you need:
   middleware, structured output, streaming, usage/cost accounting, retries,
   caching, and a Claude Code CLI model adapter with stream-json,
   session, authentication, and MCP endpoint support. Features: `sqlite`,
-  `tools`, `multimodal`, `tracing`.
+  `tools`, `multimodal`, `png-optimize` (opt-in PNG re-compression), `tracing`.
 - **`tinyagents-graph`** — a LangGraph-style durable, typed state graph:
   `START`/`END`, nodes, conditional edges, `Send` fanout, reducers/channels,
   checkpoints, interrupts, subgraphs, and time travel. Features: `sqlite`,

crates/tinyagents-harness/Cargo.toml

@@ -58,7 +58,11 @@ storage-drivers = ["dep:tinystoragedrivers-core"]
 # still spell out the old name keep compiling.
 tools = ["builtin-tools"]
 builtin-tools = ["dep:chrono-tz"]
-multimodal = ["dep:flate2", "dep:reqwest", "dep:tar", "dep:zip", "dep:oxipng"]
+multimodal = ["dep:flate2", "dep:reqwest", "dep:tar", "dep:zip"]
+# Lossless PNG re-compression (`multimodal::optimize_png_lossless`) through
+# `oxipng`. Off by default: without it the helper returns `None` and callers
+# keep the original bytes, and `oxipng`/`libdeflater` (a C build) are not linked.
+png-optimize = ["multimodal", "dep:oxipng"]
 # Image and video generation tools over tinyinference-image / -video.
 media = ["dep:tinyinference-image", "dep:tinyinference-video"]
 # Gates the Claude Code CLI and Claude Agent SDK provider adapters, which are

crates/tinyagents-harness/src/multimodal/README.md

@@ -145,6 +145,8 @@ PNG derivatives use `optimize_png_lossless`: it changes only IDAT compression
 and filtering, preserving pixel format, hidden RGB, interlacing and every other
 chunk byte-for-byte. Animated, malformed and oversized inputs are skipped; the
 caller retains the original and decides where to store the optional smaller copy.
+The optimizer (`oxipng`) is behind the opt-in `png-optimize` feature; without it
+`optimize_png_lossless` always returns `None`, i.e. the original is kept as is.
 
 ZIP admission conservatively rejects footer signature bytes in central-directory
 metadata or archive comments, even where ZIP permits those bytes. This prevents

crates/tinyagents-harness/src/multimodal/png.rs

@@ -8,6 +8,16 @@
 /// color metadata) remain byte-for-byte unchanged. The input is never modified.
 /// Work is bounded to 32 MiB of input and 16 million pixels; hosts may enforce
 /// tighter upload limits. This helper neither decodes nor changes other formats.
+///
+/// Requires the `png-optimize` feature. Without it this always returns `None`
+/// ("no saving"), so callers keep the original bytes and any size limit they
+/// apply to the original is enforced exactly as when optimization fails.
+#[cfg(not(feature = "png-optimize"))]
+pub fn optimize_png_lossless(_bytes: &[u8]) -> Option<Vec<u8>> {
+    None
+}
+
+#[cfg(feature = "png-optimize")]
 pub fn optimize_png_lossless(bytes: &[u8]) -> Option<Vec<u8>> {
     if bytes.len() > 32 * 1024 * 1024 || bytes.get(..8)? != b"\x89PNG\r\n\x1a\n" {
         return None;
@@ -40,6 +50,7 @@ pub fn optimize_png_lossless(bytes: &[u8]) -> Option<Vec<u8>> {
     Some(optimized)
 }
 
+#[cfg(feature = "png-optimize")]
 // Even if an optimizer starts rewriting a metadata chunk in a future release,
 // the derivative is admitted only when every non-IDAT chunk stays identical.
 fn unchanged_chunks(bytes: &[u8]) -> Option<Vec<&[u8]>> {

crates/tinyagents-harness/src/multimodal/png_tests.rs

@@ -1,5 +1,6 @@
 use super::*;
 
+#[cfg(feature = "png-optimize")]
 fn fixture() -> Vec<u8> {
     let mut out = Vec::new();
     {
@@ -23,6 +24,7 @@ fn fixture() -> Vec<u8> {
     out
 }
 
+#[cfg(feature = "png-optimize")]
 fn decoded(bytes: &[u8]) -> Vec<u8> {
     let mut reader = ::png::Decoder::new(std::io::Cursor::new(bytes))
         .read_info()
@@ -33,6 +35,7 @@ fn decoded(bytes: &[u8]) -> Vec<u8> {
     pixels
 }
 
+#[cfg(feature = "png-optimize")]
 #[test]
 fn png_derivative_is_smaller_preserves_hidden_rgb_and_metadata_and_original() {
     let original = fixture();
@@ -55,6 +58,7 @@ fn png_derivative_is_smaller_preserves_hidden_rgb_and_metadata_and_original() {
     assert!(optimize_png_lossless(&optimized).is_none());
 }
 
+#[cfg(feature = "png-optimize")]
 #[test]
 fn animation_malformed_non_png_and_excessive_dimensions_are_skipped() {
     assert!(optimize_png_lossless(b"jpeg").is_none());
@@ -77,3 +81,26 @@ fn animation_malformed_non_png_and_excessive_dimensions_are_skipped() {
     giant[16..20].copy_from_slice(&u32::MAX.to_be_bytes());
     assert!(optimize_png_lossless(&giant).is_none());
 }
+
+#[test]
+fn non_png_input_is_skipped_in_every_configuration() {
+    assert!(optimize_png_lossless(b"jpeg").is_none());
+    assert!(optimize_png_lossless(b"\x89PNG\r\n\x1a\n").is_none());
+}
+
+// Without `png-optimize` the helper is a passthrough signal: `None` even for a
+// valid, compressible PNG, so callers keep (and size-check) the original.
+#[cfg(not(feature = "png-optimize"))]
+#[test]
+fn valid_png_is_passed_through_without_the_feature() {
+    let mut out = Vec::new();
+    {
+        let mut encoder = ::png::Encoder::new(&mut out, 64, 64);
+        encoder.set_color(::png::ColorType::Rgba);
+        encoder.set_depth(::png::BitDepth::Eight);
+        encoder.set_compression(::png::Compression::Fast);
+        let mut writer = encoder.write_header().unwrap();
+        writer.write_image_data(&vec![0u8; 64 * 64 * 4]).unwrap();
+    }
+    assert!(optimize_png_lossless(&out).is_none());
+}