Reliability and Consistency Contract

Reliability and Consistency Contract

SPACK treats asset delivery as a protocol contract, not only as implementation unit tests.

Default CI gates

• task lint, task check, task test, and task build run on Ubuntu and Windows.
• task test:race runs on Linux CI.
• Fuzz targets are committed as normal Go fuzz tests, so their seed corpus runs during go test ./....
• task integration:container:smoke runs on Linux CI against the built container image.

Protocol coverage

The HTTP matrix covers:

• GET and HEAD.
• ETag and If-None-Match.
• Last-Modified and If-Modified-Since.
• Range partial content.
• Range plus Accept-Encoding, where Range requests must bypass encoded variants and preserve partial response headers.

Focused fuzz targets cover:

• request path normalization, including encoded traversal, backslashes, and UNC-like input.
• Accept-Encoding parsing.
• image Accept parsing.
• Range header handling at the HTTP boundary.

Run extended fuzzing with:

task test:fuzz:parsers

Source and cache consistency

Source rescan tests assert that file changes, deletes, and renames reconcile:

• catalog entries.
• source sidecar variants.
• generated artifact variants.
• memory cache entries.
• artifact files on disk.

The consistency rule is strict: a stale source asset must not keep a stale catalog record, memory cache entry, or generated artifact.

Compiler-generated artifact contract

Compression and image generation are build-time optimization steps. The runtime must be able to serve the original source asset or a precomputed artifact without invoking heavy generation logic on the request path.

The compiler should record enough metadata for the runtime to choose an already prepared response plan, including source bytes, output bytes, target encoding or image format, dimensions, and cache policy.

Image generation contract

The image engine is libvips. SPACK requires CGO and native libvips libraries for image generation.

• Image work is batched per source asset.
• A source image is opened and decoded once per batch.
• Width variants are generated from a pyramid so smaller widths can reuse the nearest larger resized image.
• Source byte, pixel, width, height, global estimated decoded-memory budget, and output variant limits are enforced before writing artifacts.
• Generated variant metadata records source bytes, source pixels, source dimensions, output bytes, output dimensions, saved bytes, saving ratio, target format, and engine name.
• Low-benefit variants are skipped and not written to disk.
• Native libvips runtime libraries must be available at compiler build and execution time.

Container black-box contract

The container smoke test starts the actual image with:

• read-only root filesystem.
• all Linux capabilities dropped.
• no-new-privileges.
• read-only asset volume.
• writable /tmp tmpfs for runtime temporary files.

It verifies /livez, /, /app.js, and a Range request against the running container.

Catalog stress testing

Large catalog scans are opt-in because they create many files.

task test:stress:catalog
SPACK_STRESS_ASSET_COUNT=1000000 task test:stress:catalog

The stress test records asset count, scan duration, source bytes, and heap deltas in test logs. Release qualification should persist those logs with the tested machine shape and image digest.