@@ -603,7 +603,7 @@
Compress Middleware
File Handler
- Preloaded or cached → direct ctx.SetBody() fast path · brotli/gzip sidecar negotiation · miss → stat → read →
+ Preloaded or cached → direct ctx.SetBody() fast path · brotli/zstd/gzip sidecar negotiation · miss → stat → read →
cache
diff --git a/go.mod b/go.mod
index 1cced69..4d8a872 100644
--- a/go.mod
+++ b/go.mod
@@ -5,11 +5,11 @@ go 1.26
require (
github.com/BurntSushi/toml v1.6.0
github.com/hashicorp/golang-lru/v2 v2.0.7
+ github.com/klauspost/compress v1.18.4
github.com/valyala/fasthttp v1.69.0
)
require (
github.com/andybalholm/brotli v1.2.0 // indirect
- github.com/klauspost/compress v1.18.2 // indirect
github.com/valyala/bytebufferpool v1.0.0 // indirect
)
diff --git a/go.sum b/go.sum
index bcd2077..19fa8d4 100644
--- a/go.sum
+++ b/go.sum
@@ -4,9 +4,11 @@ github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwTo
github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
-github.com/klauspost/compress v1.18.2 h1:iiPHWW0YrcFgpBYhsA6D1+fqHssJscY/Tm/y2Uqnapk=
-github.com/klauspost/compress v1.18.2/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZyVI=
github.com/valyala/fasthttp v1.69.0/go.mod h1:4wA4PfAraPlAsJ5jMSqCE2ug5tqUPwKXxVj8oNECGcw=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
diff --git a/internal/cache/cache.go b/internal/cache/cache.go
index 206a6c1..a0c7a38 100644
--- a/internal/cache/cache.go
+++ b/internal/cache/cache.go
@@ -34,6 +34,8 @@ type CachedFile struct {
GzipData []byte
// BrData is the pre-compressed brotli content, or nil if unavailable.
BrData []byte
+ // ZstdData is the pre-compressed zstd content, or nil if unavailable.
+ ZstdData []byte
// ETag is the first 16 hex characters of sha256(Data), without quotes.
ETag string
// ETagFull is the pre-formatted weak ETag ready for use in HTTP headers,
@@ -150,7 +152,7 @@ func matchesImmutable(urlPath, pattern string) bool {
// totalSize returns the approximate byte footprint of the entry.
func (f *CachedFile) totalSize() int64 {
- return int64(len(f.Data)+len(f.GzipData)+len(f.BrData)) + cacheOverhead
+ return int64(len(f.Data)+len(f.GzipData)+len(f.BrData)+len(f.ZstdData)) + cacheOverhead
}
// CacheStats holds runtime statistics for the cache.
diff --git a/internal/compress/compress.go b/internal/compress/compress.go
index 7ac527a..19882af 100644
--- a/internal/compress/compress.go
+++ b/internal/compress/compress.go
@@ -11,6 +11,7 @@ import (
"sync"
"github.com/BackendStack21/static-web/internal/config"
+ "github.com/klauspost/compress/zstd"
"github.com/valyala/fasthttp"
)
@@ -230,3 +231,43 @@ func (bw *byteWriter) Write(p []byte) (int, error) {
*bw.buf = append(*bw.buf, p...)
return len(p), nil
}
+
+// zstdWriterPool pools zstd.Encoders to amortise allocation costs.
+var zstdWriterPool = sync.Pool{
+ New: func() any {
+ w, _ := zstd.NewWriter(io.Discard, zstd.WithEncoderLevel(zstd.SpeedDefault))
+ return w
+ },
+}
+
+// zstdBufPool pools bytes.Buffers used for on-the-fly zstd output.
+var zstdBufPool = sync.Pool{
+ New: func() any {
+ return &bytes.Buffer{}
+ },
+}
+
+// ZstdBytes compresses src with the default zstd level and returns the result.
+// Used during cache population to pre-compress file contents.
+func ZstdBytes(src []byte) ([]byte, error) {
+ return ZstdBytesLevel(src, zstd.SpeedDefault)
+}
+
+// ZstdBytesLevel compresses src with the specified zstd level and returns the result.
+// The level can be zstd.SpeedFastest, zstd.SpeedDefault, zstd.SpeedBetter, or zstd.SpeedBest.
+func ZstdBytesLevel(src []byte, level zstd.EncoderLevel) ([]byte, error) {
+ out := make([]byte, 0, len(src)/2+512)
+ bw := &byteWriter{buf: &out}
+
+ w, err := zstd.NewWriter(bw, zstd.WithEncoderLevel(level))
+ if err != nil {
+ return nil, err
+ }
+ if _, err := w.Write(src); err != nil {
+ return nil, err
+ }
+ if err := w.Close(); err != nil {
+ return nil, err
+ }
+ return *bw.buf, nil
+}
diff --git a/internal/compress/compress_test.go b/internal/compress/compress_test.go
index f88901e..0143741 100644
--- a/internal/compress/compress_test.go
+++ b/internal/compress/compress_test.go
@@ -10,6 +10,7 @@ import (
"github.com/BackendStack21/static-web/internal/compress"
"github.com/BackendStack21/static-web/internal/config"
+ "github.com/klauspost/compress/zstd"
"github.com/valyala/fasthttp"
)
@@ -352,6 +353,133 @@ func TestGzipBytes_InvalidLevel(t *testing.T) {
}
}
+// ---------------------------------------------------------------------------
+// ZStandard compression tests
+// ---------------------------------------------------------------------------
+
+func TestZstdBytes(t *testing.T) {
+ src := []byte(strings.Repeat("Hello, ZStandard! ", 100))
+ compressed, err := compress.ZstdBytes(src)
+ if err != nil {
+ t.Fatalf("ZstdBytes error: %v", err)
+ }
+ if len(compressed) == 0 {
+ t.Fatal("ZstdBytes returned empty result")
+ }
+ if len(compressed) >= len(src) {
+ t.Errorf("compressed (%d) should be smaller than original (%d)", len(compressed), len(src))
+ }
+
+ // Decompress and verify.
+ br, err := zstd.NewReader(bytes.NewReader(compressed))
+ if err != nil {
+ t.Fatalf("zstd.NewReader: %v", err)
+ }
+ got, err := io.ReadAll(br)
+ if err != nil {
+ t.Fatalf("io.ReadAll: %v", err)
+ }
+ br.Close()
+ if !bytes.Equal(got, src) {
+ t.Error("decompressed content does not match original")
+ }
+}
+
+func TestZstdBytesLevel(t *testing.T) {
+ src := []byte(strings.Repeat("ZStandard compression levels ", 100))
+
+ levels := []zstd.EncoderLevel{
+ zstd.SpeedFastest,
+ zstd.SpeedDefault,
+ zstd.SpeedBetterCompression,
+ zstd.SpeedBestCompression,
+ }
+
+ for _, level := range levels {
+ t.Run(level.String(), func(t *testing.T) {
+ compressed, err := compress.ZstdBytesLevel(src, level)
+ if err != nil {
+ t.Fatalf("ZstdBytesLevel(%s) error: %v", level, err)
+ }
+ if len(compressed) == 0 {
+ t.Fatal("ZstdBytesLevel returned empty result")
+ }
+
+ // Decompress and verify roundtrip.
+ br, err := zstd.NewReader(bytes.NewReader(compressed))
+ if err != nil {
+ t.Fatalf("zstd.NewReader: %v", err)
+ }
+ got, err := io.ReadAll(br)
+ if err != nil {
+ t.Fatalf("io.ReadAll: %v", err)
+ }
+ br.Close()
+ if !bytes.Equal(got, src) {
+ t.Error("decompressed content does not match original")
+ }
+ })
+ }
+}
+
+func TestZstdBytes_EmptyInput(t *testing.T) {
+ src := []byte{}
+ compressed, err := compress.ZstdBytes(src)
+ if err != nil {
+ t.Fatalf("ZstdBytes empty error: %v", err)
+ }
+ // Empty input may produce empty or minimal output
+ if len(compressed) == 0 {
+ t.Log("ZstdBytes produced empty output for empty input (valid zstd behavior)")
+ return
+ }
+
+ // If there is output, try to decompress and verify.
+ br, err := zstd.NewReader(bytes.NewReader(compressed))
+ if err != nil {
+ t.Fatalf("zstd.NewReader: %v", err)
+ }
+ got, err := io.ReadAll(br)
+ if err != nil {
+ t.Fatalf("io.ReadAll: %v", err)
+ }
+ br.Close()
+ if len(got) != 0 {
+ t.Errorf("decompressed empty should be empty, got %d bytes", len(got))
+ }
+}
+
+func TestZstdBytes_AlreadyCompressed(t *testing.T) {
+ // Zstandard of already-compressed data should still work.
+ compressed1, err := compress.ZstdBytes([]byte(strings.Repeat("test ", 100)))
+ if err != nil {
+ t.Fatalf("first compression error: %v", err)
+ }
+
+ // Compress again
+ compressed2, err := compress.ZstdBytes(compressed1)
+ if err != nil {
+ t.Fatalf("second compression error: %v", err)
+ }
+
+ // Should be able to decompress the second compression to get the first
+ br, err := zstd.NewReader(bytes.NewReader(compressed2))
+ if err != nil {
+ t.Fatalf("zstd.NewReader: %v", err)
+ }
+ got, err := io.ReadAll(br)
+ if err != nil {
+ t.Fatalf("io.ReadAll: %v", err)
+ }
+ br.Close()
+
+ // Compare with first compression
+ if !bytes.Equal(got, compressed1) {
+ t.Errorf("double-compressed data (%d bytes) does not match single-compressed (%d bytes)",
+ len(got), len(compressed1))
+ }
+}
+
// TestAcceptsEncoding_MultipleValues covers more Accept-Encoding negotiation cases.
func TestAcceptsEncoding_MultipleValues(t *testing.T) {
cases := []struct {
diff --git a/internal/handler/file.go b/internal/handler/file.go
index f207db3..5055eec 100644
--- a/internal/handler/file.go
+++ b/internal/handler/file.go
@@ -226,10 +226,14 @@ func (h *FileHandler) negotiateEncoding(ctx *fasthttp.RequestCtx, f *cache.Cache
return f.Data, ""
}
- // Brotli preferred over gzip when available.
+ // Brotli preferred (best compression), then zstd (fastest decompression),
+ // then gzip (universally supported fallback).
if f.BrData != nil && compress.AcceptsEncoding(ctx, "br") {
return f.BrData, "br"
}
+ if f.ZstdData != nil && compress.AcceptsEncoding(ctx, "zstd") {
+ return f.ZstdData, "zstd"
+ }
if f.GzipData != nil && compress.AcceptsEncoding(ctx, "gzip") {
return f.GzipData, "gzip"
}
@@ -295,6 +299,7 @@ func (h *FileHandler) serveFromDisk(ctx *fasthttp.RequestCtx, absPath, urlPath s
compress.IsCompressible(ct) && len(data) >= h.cfg.Compression.MinSize {
cached.GzipData = loadSidecar(absPath + ".gz")
cached.BrData = loadSidecar(absPath + ".br")
+ cached.ZstdData = loadSidecar(absPath + ".zst")
}
// Generate on-the-fly gzip if no sidecar and content is compressible.
@@ -305,6 +310,14 @@ func (h *FileHandler) serveFromDisk(ctx *fasthttp.RequestCtx, absPath, urlPath s
}
}
+ // Generate on-the-fly zstd if no sidecar and content is compressible.
+ if cached.ZstdData == nil && h.cfg.Compression.Enabled &&
+ compress.IsCompressible(ct) && len(data) >= h.cfg.Compression.MinSize {
+ if zst, err := compress.ZstdBytes(data); err == nil {
+ cached.ZstdData = zst
+ }
+ }
+
// Pre-format headers for the fast serving path.
cached.InitHeaders()
cached.InitCacheControl(urlPath, h.cfg.Headers.HTMLMaxAge, h.cfg.Headers.StaticMaxAge, h.cfg.Headers.ImmutablePattern)
diff --git a/internal/handler/file_test.go b/internal/handler/file_test.go
index 8a50718..d0b99ab 100644
--- a/internal/handler/file_test.go
+++ b/internal/handler/file_test.go
@@ -869,6 +869,50 @@ func BenchmarkHandler_CacheHitGzip(b *testing.B) {
})
}
+// BenchmarkHandler_CacheHitZstd measures cache-hit throughput when the client
+// accepts zstd and on-the-fly zstd compression is generated and cached.
+func BenchmarkHandler_CacheHitZstd(b *testing.B) {
+ log.SetOutput(io.Discard)
+ b.Cleanup(func() { log.SetOutput(os.Stderr) })
+
+ root := b.TempDir()
+ content := strings.Repeat("body { color: red; } ", 100)
+ if err := os.WriteFile(filepath.Join(root, "bench.css"), []byte(content), 0644); err != nil {
+ b.Fatal(err)
+ }
+
+ cfg := &config.Config{}
+ cfg.Files.Root = root
+ cfg.Files.Index = "index.html"
+ cfg.Cache.Enabled = true
+ cfg.Cache.MaxBytes = 64 * 1024 * 1024
+ cfg.Cache.MaxFileSize = 10 * 1024 * 1024
+ cfg.Compression.Enabled = true
+ cfg.Compression.MinSize = 1
+ cfg.Compression.Level = 5
+ cfg.Compression.Precompressed = false // use on-the-fly zstd
+ cfg.Security.BlockDotfiles = true
+ cfg.Headers.StaticMaxAge = 3600
+
+ c := cache.NewCache(cfg.Cache.MaxBytes)
+ h := handler.BuildHandler(cfg, c)
+
+ // Warm — zstd variant is generated and cached on first request.
+ warmCtx := newTestCtx("GET", "/bench.css")
+ warmCtx.Request.Header.Set("Accept-Encoding", "zstd")
+ h(warmCtx)
+
+ b.ResetTimer()
+ b.ReportAllocs()
+ b.RunParallel(func(pb *testing.PB) {
+ for pb.Next() {
+ ctx := newTestCtx("GET", "/bench.css")
+ ctx.Request.Header.Set("Accept-Encoding", "zstd")
+ h(ctx)
+ }
+ })
+}
+
// BenchmarkHandler_CacheHitQuiet measures the cache-hit path with request logging disabled.
func BenchmarkHandler_CacheHitQuiet(b *testing.B) {
log.SetOutput(io.Discard)