ci(image): add multi-arch GHCR container image workflow

Add .github/workflows/image.yml to build and publish the
hypercache-server Docker image for linux/amd64 and linux/arm64
via buildx + QEMU.

Trigger behaviour:
- pull_request: build-only (no push) to catch Dockerfile regressions
- push to main: publish :main and :sha-<short>
- semver tag push (v*.*.*): publish :v1.2.3, :1.2.3, :1.2, :1, :latest

:latest is intentionally restricted to semver tag pushes so
production deployments pinning :latest always resolve to a stable
release rather than an in-flight main commit. GHA layer caching
keeps re-builds fast when only Go source has changed.

Also replace stdlib encoding/json with github.com/goccy/go-json in
dist_memory.go and integration tests, update CHANGELOG.md, and add
buildx to the cspell allow-list.

Author: hyp3rd

.github/workflows/image.yml

@@ -0,0 +1,97 @@
+---
+name: image
+
+# Build (and on the right refs, publish) the hypercache-server
+# container image. Three trigger shapes:
+#   * pull_request — build only, never push (catches Dockerfile
+#     regressions without polluting the registry).
+#   * push to main — build + push as `:main` and `:sha-<short>`
+#     so consumers can pin to either.
+#   * tag push (v*.*.*) — build + push semver-flavored tags
+#     (`:v1.2.3`, `:1.2.3`, `:1.2`, `:1`, `:latest`) for stable
+#     pinning.
+# Multi-arch linux/amd64 + linux/arm64 via buildx + qemu so
+# operators on Apple Silicon (or k8s nodes on Graviton) get a
+# native binary without emulation.
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+    tags: [ "v*.*.*" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/hypercache-server
+
+jobs:
+  build:
+    name: build${{ github.event_name == 'pull_request' && ' (no push)' || ' + push'
+      }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      # Login is gated on non-PR events. Forks running PR workflows
+      # don't have access to GITHUB_TOKEN with packages:write, and
+      # we never push from a PR anyway — so skipping the login step
+      # avoids an avoidable failure on those events.
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # docker/metadata-action computes the tag set + OCI labels
+      # from the triggering ref. The semver patterns only match
+      # when the ref is a `v*.*.*` tag; on branch/PR pushes they
+      # produce no tags and the type=ref/type=sha entries take over.
+      # `:latest` is restricted to semver tag pushes — production
+      # operators pinning to `:latest` get the highest stable
+      # release, never an in-flight main commit. The `latest=false`
+      # flavor disables the metadata-action default behavior that
+      # would otherwise tag `:latest` on every default-branch push.
+      - name: Compute tags and labels
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha,format=short
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable=${{ github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v') }}
+          flavor: |
+            latest=false
+
+      - name: Build${{ github.event_name == 'pull_request' && '' || ' + push' }}
+        uses: docker/build-push-action@v7.1.0
+        with:
+          context: .
+          file: cmd/hypercache-server/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # GHA cache speeds re-builds when only Go source changed
+          # (the dependency-download layer stays warm).
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

CHANGELOG.md

@@ -39,6 +39,18 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   (replica path), `json.RawMessage` (non-owner-GET path), and the
   base64-heuristic length floors. Runs without docker for tight
   feedback during development.
+- **Multi-arch container image workflow** —
+  [.github/workflows/image.yml](.github/workflows/image.yml) builds
+  the `hypercache-server` Docker image for `linux/amd64` and
+  `linux/arm64` via buildx + QEMU, publishing to GHCR
+  (`ghcr.io/<owner>/<repo>/hypercache-server`). PR triggers
+  build-only (no registry pollution), `main` pushes publish
+  `:main` and `:sha-<short>`, semver tag pushes (`v*.*.*`)
+  publish `:v1.2.3`, `:1.2.3`, `:1.2`, `:1`, and `:latest`.
+  `:latest` is **deliberately restricted to semver tag pushes** —
+  production deployments pinning `:latest` always get a stable
+  release, never an in-flight `main` commit. GHA cache speeds
+  re-builds when only Go source has changed.
 
 ### Fixed
 

cspell.config.yaml

@@ -46,6 +46,7 @@ words:
   - bitnami
   - bodyclose
   - bufbuild
+  - buildx
   - cacheerrors
   - cachev
   - calledback

pkg/backend/dist_memory.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"crypto/rand"
 	"crypto/sha256"
-	"encoding/json"
 	"errors"
 	"hash"
 	"hash/fnv"
@@ -17,6 +16,7 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/goccy/go-json"
 	"github.com/hyp3rd/ewrap"
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/codes"
@@ -1443,7 +1443,8 @@ func (dm *DistMemory) Drain(_ context.Context) error {
 
 	dm.metrics.drains.Add(1)
 
-	dm.logger.Info("dist node draining",
+	dm.logger.Info(
+		"dist node draining",
 		slog.String("addr", dm.nodeAddr),
 	)
 

tests/dist_drain_test.go

@@ -21,7 +21,8 @@ func newDrainNode(t *testing.T) *backend.DistMemory {
 
 	addr := AllocatePort(t)
 
-	bi, err := backend.NewDistMemory(context.Background(),
+	bi, err := backend.NewDistMemory(
+		context.Background(),
 		backend.WithDistNode("drain-A", addr),
 		backend.WithDistReplication(1),
 	)

tests/dist_http_compression_test.go

@@ -24,7 +24,7 @@ func valueAsBytes(v any) ([]byte, bool) {
 
 	case string:
 		// Try base64 first — that's how []byte serializes through
-		// encoding/json. Fall back to the raw string bytes for
+		// github.com/goccy/go-json. Fall back to the raw string bytes for
 		// values that were always-string.
 		decoded, err := base64.StdEncoding.DecodeString(x)
 		if err == nil {

tests/dist_keys_cursor_test.go

@@ -80,7 +80,8 @@ func newKeysCursorNode(t *testing.T) *backend.DistMemory {
 
 	addr := AllocatePort(t)
 
-	bi, err := backend.NewDistMemory(context.Background(),
+	bi, err := backend.NewDistMemory(
+		context.Background(),
 		backend.WithDistNode("keys-A", addr),
 		backend.WithDistReplication(1),
 	)

tests/integration/dist_phase1_test.go

@@ -3,12 +3,13 @@ package integration
 import (
 	"context"
 	"encoding/base64"
-	"encoding/json"
 	"fmt"
 	"net"
 	"testing"
 	"time"
 
+	"github.com/goccy/go-json"
+
 	"github.com/hyp3rd/hypercache/pkg/backend"
 	cache "github.com/hyp3rd/hypercache/pkg/cache/v2"
 )

tests/integration/dist_seed_spec_test.go

@@ -51,7 +51,8 @@ func buildSeedSpecCluster(t *testing.T) *seedSpecCluster {
 	}
 
 	mkNode := func(id, addr string) *backend.DistMemory {
-		bm, err := backend.NewDistMemory(ctx,
+		bm, err := backend.NewDistMemory(
+			ctx,
 			backend.WithDistNode(id, addr),
 			backend.WithDistSeeds(seedsFor(id)),
 			backend.WithDistReplication(3),