cacher

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

0.2.2 — 2026-08-07

Fixed

• dir download could not restore a tree containing read-only directories — which the Go module cache is throughout (0555 dirs, 0444 files). Extraction applied each archived mode as the entry landed, so the first file written into a restored 0555 directory failed with permission denied. Directories are now created writable and their recorded mode applied once extraction finishes, files are written writable and chmod'ed afterwards, and a read-only file left by an earlier restore is replaced instead of erroring. Caught by this repo's own CI on the first cache HIT of the new gomod/*.tar.zst key (build #295).

0.2.1 — 2026-08-07

Fixed

• install.sh verified the download with sha256sum -c --ignore-missing, a coreutils extension busybox rejects — so on Alpine, which is what several manifests using this run on, the bootstrap aborted with a bogus "checksum mismatch". The hash is now compared as a plain string, which busybox, coreutils and macOS shasum all handle.
• install.sh stages the binary inside the target directory and renames it into place, so installing over a cacher that is currently running can't fail with ETXTBSY.

0.2.0 — 2026-08-07

Added

• --exec <script> on download, dir download and docker download — on a cache miss the script runs through sh -c and its result seeds the cache. Generalises the --url and --pull fallbacks to anything expressible as a shell command, which collapses the restore-or-build if/fi block CI manifests repeat per cache:

  cacher dir download "gomod/{hash}.tar.zst" ~/go/pkg/mod \
    --hash-from go.sum --exec 'go mod download'
  

  The destination directory is created before the script runs; the seed upload is best-effort; a failing script is fatal and propagates its own exit status.

• --optional on download and dir download — a cache miss exits 0 instead of 1/3, so set -e manifests no longer need a trailing || echo "cache miss".

• install.sh, published next to the binaries: detects the platform, verifies against checksums.txt, installs into ~/.local/bin and, on builds.sr.ht, appends the PATH export to ~/.buildenv. Reduces the bootstrap task to curl -sSL https://bigbes.pages.srht.bigb.es/ci-cacher/install.sh | sh.

0.1.2 — 2026-05-26

Changed

• Landing page: widen body max-width from 44rem to 55rem.

0.1.1 — 2026-05-26

Added

• cacher docker download --pull — on cache miss, falls back to docker pull <image:tag> and seeds the S3 cache. Mirrors the --url fallback on file download; collapses the if/else cache-or-pull bash dance in CI manifests to a single command.

Changed

• Runtime errors (cache miss, key not found) no longer dump the cobra Usage block; the short error line is enough for scripted callers. Argument-validation errors still show usage.

0.1.0 — 2026-05-26

First public release. Replaces the s3_cache_or_curl / s3_cache_docker_image shell helpers in tarantool-protobuf/.builds/lib/ci-lib.sh with a single static Go binary.

Added

• cacher init / cacher doctor — persist config to ~/.config/cacher/config.toml and smoke-test S3 credentials (HEAD bucket
  • 1-byte canary write/read/delete).
• cacher download / upload / exists / list / delete for single files. Download falls back to --url on cache miss and back-fills the cache. Optional --sha256 verifies the fetched content.
• cacher docker {exists,download,upload} — streamed docker save | zstd → S3 multipart upload (and inverse). Pure-Go zstd via klauspost/compress, no external zstd binary on the host.
• cacher dir {download,upload} — tar+zstd of a directory tree keyed by content hash. Closes the gap left by the shell version, which only cached single files.
• cacher key — resolve a key template (substituting {hash}) for shell scripting.
• --hash-from <path> (repeatable; files or directories) on every command. For a single file path the digest exactly matches sha256sum file | cut -c1-N, so existing keys migrate without recomputation.
• --arch-suffix opt-in to suffix every key with -<goos>-<goarch>.
• list --recursive for flat listing; list --root to ignore the configured prefix and list at bucket root. Default output style mirrors aws s3 ls (delimited by /).
• Garage-compatible defaults: path-style addressing, signature v4, request/response checksum calculation set to when_required (Garage doesn't implement boto3 1.36+ trailing CRC32 checksums).
• End-to-end test suite (go test -tags=e2e) against a real Garage container via testcontainers-go using dxflrs/garage:v2.3.0's --single-node --default-bucket mode.
• builds.sr.ht CI: unit.yml (every push), e2e.yml (every push, with Docker), publish.yml (tags only, ships cross-platform binaries via goreleaser to pages.sr.ht and as build artifacts).
• Static landing page at bigbes.pages.srht.bigb.es/ci-cacher/.

Fixed

• doctor uses ListObjectsV2 (1-key) instead of HeadBucket — Garage rejects HeadBucket with 403 even for valid credentials.
• Config path is ~/.config/cacher/config.toml on every platform (previously fell into ~/Library/Application Support/cacher on macOS via os.UserConfigDir). cacher is a CI tool; dev-macs and Linux runners must look in the same place.