Compression and Images

压缩与图片 / Compression and Images

SPACK 的 pipeline 支持压缩变体和图片变体。它既能识别前端构建工具预生成的 sidecar，也能在运行时 lazy 或 warmup 生成变体。

The SPACK pipeline supports compression and image variants. It can recognize pre-generated sidecars from frontend build tools and can also generate variants lazily or during warmup.

压缩策略 / Compression Strategy

flowchart TB
    Asset["source asset"] --> Eligible{"text-like and size >= min_size?"}
    Eligible -->|no| Identity["identity only"]
    Eligible -->|yes| Sidecar{"sidecar exists?"}
    Sidecar -->|yes| RegisterSidecar["register source sidecar"]
    Sidecar -->|no| Mode{"compression mode"}
    Mode -->|off| Identity
    Mode -->|lazy| FirstRequest["serve identity first<br/>enqueue generation"]
    Mode -->|warmup| Warmup["generate during startup/warmup"]
    FirstRequest --> Artifact["generated artifact"]
    Warmup --> Artifact
    RegisterSidecar --> Variant["catalog variant"]
    Artifact --> Variant
    Variant --> Prepared["prepared snapshot"]

Loading

支持编码：

• br
• zstd
• gzip

Supported encodings:

• br
• zstd
• gzip

Lazy 与 Warmup / Lazy vs Warmup

Mode	中文说明	English
lazy	首次请求可能返回 identity，同时异步生成压缩文件。适合启动快、访问分布不确定的服务。	First request may return identity while generation runs asynchronously. Good for fast startup and uncertain access patterns.
warmup	启动或预热阶段生成候选变体。适合资源集合稳定、希望首个用户请求直接命中压缩版本的服务。	Generates variants during startup/warmup. Good for stable asset sets where first user requests should hit compressed variants.
off	不生成压缩变体，但仍可使用已扫描的 source sidecar。	Does not generate compressed variants, but scanned source sidecars can still be used.

Sidecar 识别 / Sidecar Recognition

SPACK 会识别以下形式：

SPACK recognizes files such as:

app.js.br
app.js.zst
app.js.gz
style.css.br
payload.json.zst

前提是原始文件存在，例如 app.js.br 需要对应 app.js。

The original asset must exist. For example, app.js.br requires app.js.

行为：

• sidecar 注册为 source variant。
• sidecar 不被 artifact janitor 删除。
• 请求必须包含相应 Accept-Encoding 才会返回 sidecar。
• 如果 Vite 插件已经生成压缩文件，SPACK 不需要再次生成同一编码变体。

Behavior:

• Sidecars are registered as source variants.
• Sidecars are not removed by the artifact janitor.
• Requests must include matching Accept-Encoding.
• If a Vite plugin already generated compressed files, SPACK does not need to generate the same encoding variant again.

请求协商 / Request Negotiation

示例：

curl.exe -I -H "Accept-Encoding: br,zstd,gzip" http://127.0.0.1/assets/app.js

可能响应：

Content-Encoding: br
Vary: Accept-Encoding

如果浏览器请求如下：

Accept: */*

但没有 Accept-Encoding，不会返回压缩版本。Accept 控制 media type，Accept-Encoding 才控制 gzip/br/zstd。

If a browser sends Accept: */* but no Accept-Encoding, SPACK will not return a compressed version. Accept negotiates media type; Accept-Encoding negotiates gzip/br/zstd.

Text-Like Media Types

压缩默认面向 text-like assets，例如：

Compression targets text-like assets, for example:

• text/*
• JavaScript
• JSON and manifest JSON
• XML and XHTML
• SVG
• media types containing json but not image types

图片类资源通常不走通用 HTTP content-coding 压缩，而是使用图片变体 pipeline。

Image resources usually do not use generic HTTP content-coding compression. They use the image variant pipeline instead.

图片变体 / Image Variants

flowchart LR
    Request["image request"] --> Query{"query params?"}
    Query -->|w=640| Width["resize width"]
    Query -->|format=jpeg/png| Format["convert format"]
    Query -->|none| Accept["Accept negotiation"]
    Accept --> Format
    Width --> Generate["generate variant"]
    Format --> Generate
    Generate --> Artifact["artifact store"]
    Artifact --> Catalog["catalog variant"]
    Catalog --> Prepared["prepared snapshot"]

Loading

配置：

• SPACK_IMAGE_ENABLE=true
• SPACK_IMAGE_WIDTHS=640,1280,1920
• SPACK_IMAGE_FORMATS=
• SPACK_IMAGE_JPEG_QUALITY=78

请求：

/assets/hero.jpg?w=640
/assets/hero.jpg?format=png
/assets/hero.jpg?w=640&format=jpeg

English:

• image.widths defines accepted resize widths.
• image.formats controls warmup/default output formats.
• Request-time Accept negotiation can still select supported formats when enabled.

Artifact Lifecycle

生成物受 artifact policy 控制：

Generated artifacts are controlled by artifact policies:

• compression.max_age
• compression.encoding_max_age
• compression.image_max_age
• compression.max_cache_bytes
• compression.encoding_max_cache_bytes
• compression.image_max_cache_bytes

flowchart TB
    Artifact["generated artifact"] --> Age{"older than max age?"}
    Artifact --> Budget{"namespace over byte budget?"}
    Age -->|yes| Delete["remove artifact"]
    Budget -->|yes| Delete
    Delete --> Catalog["remove catalog variant"]
    Catalog --> Snapshot["rebuild prepared snapshot"]

Loading

中文：artifact janitor 只处理运行时生成物，不删除用户 source tree 中的源文件和 sidecar。

English: The artifact janitor only manages runtime-generated artifacts. It does not delete user source files or source sidecars.