Achieve Static Resource Compression
Created November 6, 2026 · Updated November 6, 2026 · Achieve 3.1.0 · Qualified runtime: Node.js 24.22.2
Achieve can maintain gzip and deflate representations of eligible static resources. The design keeps compression work off the request's critical response path: a missing or stale artifact normally causes an identity response while one background job prepares a later compressed representation.
Configuration and eligibility
achieve.setCompress(true);
Compression is disabled by default. When enabled, ordinary static resources with text/* or application/* MIME types are eligible. Media-streaming resources and servlet output are not automatically compressed. Client selection rules are documented in Content Negotiation.
Artifact generation
Artifacts are stored beneath .compression-cache in the application space, preserving the source-relative path and using separate gzip and deflate suffixes. Generation streams the source through Node's zlib pipeline to a temporary file. Publication uses rename so readers see either the previous complete artifact or the new complete artifact, not partial output.
Concurrent requests for the same source and coding share one in-progress job. Pipeline, temporary-file, or publication failures are logged and cleaned up; they do not turn an otherwise available identity response into a failed request. A later request can retry generation.
Freshness and source consistency
An existing artifact is reusable only when its modification time is at least both the source modification time and source change time. This catches ordinary edits and same-size changes whose modification time was restored, without adding another filesystem operation.
Background generation captures the source's modification time, change time, size, device, and file identity before compression and compares all five with the existing post-compression source statistics. If any value changed, Achieve discards the temporary output rather than publishing an artifact made from an obsolete source.
Serving and fallback
A reusable artifact is opened and described as the selected representation. Its content length, modification metadata, and strong entity tag describe the compressed bytes. If it disappears or cannot be opened, Achieve falls back to identity when identity is acceptable; response metadata is reset to the representation actually sent.
Protected internal storage
The compression-cache directory is internal. Direct HTTP access is forbidden, including access through exact and subtree route maps. The Node process needs filesystem permission to create and replace artifacts, but applications should not publish or edit them as source resources.
Verification and limits
Compression tests cover artifact selection and bytes, asynchronous generation, job deduplication, freshness, same-size source edits, source replacement, changes during compression, atomic publication, failures, retries, cleanup, identity fallback, protected routes, and unchanged-artifact reuse.
The freshness strategy is metadata-based rather than a content hash. It materially improves change detection without rereading the file solely to hash it, but it cannot mathematically distinguish different bytes if every participating filesystem attribute is deliberately or unusually reproduced.
