Images binding: allow setting headers on .response()

[Monark-Arkmon]

response() now accepts an optional headers option, so you can set Cache-Control (or any other header) without manually rebuilding the Response:

result.response({
  headers: { "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400" },
});

content-type is always taken from the transformed image and can't be overridden by a header you pass in.

Before: you had to intercept the response, spread its headers, and rebuild it just to add one header:

const result = await env.IMAGES.input(stream)
  .transform({ width: 800 })
  .output({ format: "image/webp" });

const response = result.response();
return new Response(response.body, {
  headers: {
    ...Object.fromEntries(response.headers),
    "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400",
  },
});

After: pass the header straight to response():

const result = await env.IMAGES.input(stream)
  .transform({ width: 800 })
  .output({ format: "image/webp" });

return result.response({
  headers: { "Cache-Control": "public, max-age=3600, stale-while-revalidate=86400" },
});

This pairs nicely with Workers Cache, now that Cache-Control on the response is all you need to get a transform cached at the edge, it was a bit annoying to have to hand-roll headers just to set that one thing.

Implemented as a generic headers?: HeadersInit passthrough rather than a Cache-Control-specific option, since the underlying problem (copying headers manually) applies to any header, not just cache-control.

[codspeed-hq]

Merging this PR will improve performance by 9.69%

⚡ 1 improved benchmark
✅ 71 untouched benchmarks
⏩ 129 skipped benchmarks¹

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	request[RegExpBenchmark]	4.5 ms	4.1 ms	+9.69%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing Monark-Arkmon:monark/images-response-headers (9c97ada) with main (03c396e)}

Footnotes

1. 129 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩