feat(cache): support conditional requests on Cache.Open and Stat (#344)

## Summary

Unifies conditional-request handling into a single option set shared by
the client wire protocol, the cache backends, and the server handlers.
Previously `If-Match`/`If-None-Match` were only evaluated at the HTTP
layer (`httputil.ServeCacheHit`), and `Cache.Open`/`Stat` had no way to
express preconditions — so the `Remote` tier couldn't forward them
upstream and backends always read the body before a 304/412 could be
decided.

This pushes precondition evaluation down into the cache, establishing
the option plumbing for forthcoming **Range / If-Range** support.

## Changes

- **`client`**: replace the `http.Request`-based `RequestOption` with an
inspectable `RequestOptions` struct (`IfMatch`/`IfNoneMatch`) plus a
`Check(etag)` evaluator, so non-HTTP backends can evaluate preconditions
locally. The matching logic (`etagListMatches`) moves here from
`httputil`.
- **`internal/cache`**: `Cache.Open`/`Stat` accept variadic `Option`
args (an idiomatic alias of `client.RequestOption`).
`Disk`/`Memory`/`S3` short-circuit with
`ErrNotModified`/`ErrPreconditionFailed` *before* reading the body;
`Remote` forwards opts to upstream (zero translation — same type);
`Tiered` treats the sentinels as definitive (no backfill, headers
preserved for 304).
- **`internal/httputil`**: `ServeCacheHit`/`ServeCacheStat` now serve
the `Open`/`Stat` outcome, mapping sentinels to 304/412;
`CheckConditionals` delegates to the unified `client` logic (still used
by the git snapshot path).
- **handlers**: `apiv1` and the generic caching handler parse request
conditionals and push them into `Open`/`Stat`.

### Note on S3
S3's native conditional options (`SetMatchETag` etc.) match against S3's
object ETag, but cachew advertises a SHA256 **content-hash** ETag stored
in the companion `.meta` object — a different value. So preconditions
are evaluated locally against the stored ETag rather than delegated to
S3.

## Tests

- Reworked `httputil/conditional_test.go` for the outcome-based serve
helpers.
- Added a `Conditional` case to the shared cache suite, exercising
`If-Match`/`If-None-Match` on `Open` and `Stat` across all backends
(including `Remote` end-to-end).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alecthomas

.claude/rules/base.md

@@ -7,7 +7,6 @@ DO NOT ASSUME I AM RIGHT, VERIFY WHAT I ASSERT
 - When working on a list of tasks in a README.md bullet list `- [ ] ...`, pick the next incomplete one and implement that, mark it as complete, then stop.
 - If you are in read-only "Ask" mode, and are asked to modify something, immediately abort saying you can't modify anything.
 - Do exactly what I ask, no more. Don't add extra scripts, documentation, etc.
-- Always run tests to verify correctness.
 - Always write tests for updated/new code.
 - Be succinct.
 - Don't write comments if the related code itself is simple.

.claude/rules/go.md

@@ -16,7 +16,6 @@
 - Where it makes sense, update existing test rather than creating new ones.
 - ALWAYS run tests with `-timeout 30s` to ensure that wedged tests don't last forever.
 - Don't run tests with `-v` in general, as it produces a large amount of output.
-- Once the change is complete and working, run `golangci-lint run` and fix any linter errors introduced before adding the files to git. Do NOT EVER run `golangci-lint` on individual files.
 - For "unparam" linter warnings about "XXX is unused", remove the parameter unless the type is part of an interface implementation or callback system.
 - ALWAYS respect encapsulation of struct fields, even between types in the same package.
 - ALWAYS apply the Go proverb "align the happy path to the left", to avoid deep nesting. 

client/client.go

@@ -166,9 +166,7 @@ func (c *Client) Open(ctx context.Context, key Key, opts ...RequestOption) (io.R
 	if err != nil {
 		return nil, nil, errors.Wrap(err, "failed to create request")
 	}
-	for _, opt := range opts {
-		opt(req)
-	}
+	NewRequestOptions(opts...).applyToRequest(req)
 
 	resp, err := c.http.Do(req)
 	if err != nil {
@@ -204,9 +202,7 @@ func (c *Client) Stat(ctx context.Context, key Key, opts ...RequestOption) (http
 	if err != nil {
 		return nil, errors.Wrap(err, "failed to create request")
 	}
-	for _, opt := range opts {
-		opt(req)
-	}
+	NewRequestOptions(opts...).applyToRequest(req)
 
 	resp, err := c.http.Do(req)
 	if err != nil {

client/preconditions.go

@@ -2,33 +2,86 @@ package client
 
 import (
 	"net/http"
+	"strings"
 
 	"github.com/alecthomas/errors"
 )
 
-// ErrNotModified is returned when the server responds with 304 Not Modified,
-// indicating the resource has not changed since the ETag in If-None-Match.
+// ErrNotModified is returned when an If-None-Match precondition is satisfied,
+// indicating the resource has not changed since the supplied ETag. Over HTTP
+// this corresponds to 304 Not Modified.
 var ErrNotModified = errors.New("not modified")
 
-// ErrPreconditionFailed is returned when the server responds with 412
-// Precondition Failed, indicating an If-Match or If-None-Match condition was not met.
+// ErrPreconditionFailed is returned when an If-Match precondition is not met.
+// Over HTTP this corresponds to 412 Precondition Failed.
 var ErrPreconditionFailed = errors.New("precondition failed")
 
-// RequestOption configures conditional headers on an outgoing cache request.
-type RequestOption func(req *http.Request)
+// RequestOptions holds conditional-request parameters. It is the single
+// representation shared by the client wire protocol, the cache backends, and
+// the server handlers.
+type RequestOptions struct {
+	// IfMatch is the If-Match precondition. Evaluation fails with
+	// ErrPreconditionFailed if the stored ETag does not match.
+	IfMatch string
+	// IfNoneMatch is the If-None-Match precondition. Evaluation reports
+	// ErrNotModified when the stored ETag matches.
+	IfNoneMatch string
+}
+
+// RequestOption configures conditional request parameters.
+type RequestOption func(*RequestOptions)
 
-// IfMatch sets the If-Match header. The server will return 412 Precondition
-// Failed if the stored ETag does not match.
+// IfMatch sets the If-Match precondition.
 func IfMatch(etag string) RequestOption {
-	return func(req *http.Request) {
-		req.Header.Set("If-Match", etag)
-	}
+	return func(o *RequestOptions) { o.IfMatch = etag }
 }
 
-// IfNoneMatch sets the If-None-Match header. For GET/HEAD the server returns
-// 304 Not Modified when the ETag matches; for other methods it returns 412.
+// IfNoneMatch sets the If-None-Match precondition.
 func IfNoneMatch(etag string) RequestOption {
-	return func(req *http.Request) {
-		req.Header.Set("If-None-Match", etag)
+	return func(o *RequestOptions) { o.IfNoneMatch = etag }
+}
+
+// NewRequestOptions applies opts and returns the resulting RequestOptions.
+func NewRequestOptions(opts ...RequestOption) RequestOptions {
+	var o RequestOptions
+	for _, opt := range opts {
+		opt(&o)
+	}
+	return o
+}
+
+// Check evaluates the preconditions against the stored ETag. It returns
+// ErrNotModified for a satisfied If-None-Match, ErrPreconditionFailed for a
+// failed If-Match, or nil when all preconditions pass.
+func (o RequestOptions) Check(etag string) error {
+	if o.IfMatch != "" && (etag == "" || !etagListMatches(o.IfMatch, etag)) {
+		return ErrPreconditionFailed
+	}
+	if o.IfNoneMatch != "" && etag != "" && etagListMatches(o.IfNoneMatch, etag) {
+		return ErrNotModified
+	}
+	return nil
+}
+
+// applyToRequest sets the conditional headers on an outgoing request.
+func (o RequestOptions) applyToRequest(req *http.Request) {
+	if o.IfMatch != "" {
+		req.Header.Set("If-Match", o.IfMatch)
+	}
+	if o.IfNoneMatch != "" {
+		req.Header.Set("If-None-Match", o.IfNoneMatch)
+	}
+}
+
+// etagListMatches reports whether etag matches an If-Match / If-None-Match
+// header value, which may be a comma-separated list of ETags or the "*"
+// wildcard. Stored ETags are always strong, so weak comparison is not required.
+func etagListMatches(headerValue, etag string) bool {
+	for candidate := range strings.SplitSeq(headerValue, ",") {
+		candidate = strings.TrimSpace(candidate)
+		if candidate == "*" || candidate == etag {
+			return true
+		}
 	}
+	return false
 }

internal/cache/api.go

@@ -31,6 +31,25 @@ type Writer = client.CacheWriter
 // ErrNotFound is returned when a cache backend is not found.
 var ErrNotFound = errors.New("cache backend not found")
 
+// Option configures conditional parameters on a cache Open or Stat.
+type Option = client.RequestOption
+
+// IfMatch sets the If-Match precondition. Open/Stat return ErrPreconditionFailed
+// if the stored ETag does not match.
+func IfMatch(etag string) Option { return client.IfMatch(etag) }
+
+// IfNoneMatch sets the If-None-Match precondition. Open/Stat return
+// ErrNotModified when the stored ETag matches.
+func IfNoneMatch(etag string) Option { return client.IfNoneMatch(etag) }
+
+// ErrNotModified is returned by Open/Stat when an If-None-Match precondition is
+// satisfied.
+var ErrNotModified = client.ErrNotModified
+
+// ErrPreconditionFailed is returned by Open/Stat when an If-Match precondition
+// is not met.
+var ErrPreconditionFailed = client.ErrPreconditionFailed
+
 // ErrStatsUnavailable is returned when a cache backend cannot provide statistics.
 var ErrStatsUnavailable = client.ErrStatsUnavailable
 
@@ -133,13 +152,21 @@ type Cache interface {
 	//
 	// Expired files MUST not be returned.
 	// Must return os.ErrNotExist if the file does not exist.
-	Stat(ctx context.Context, key Key) (http.Header, error)
+	//
+	// Conditional opts are evaluated against the stored ETag: a satisfied
+	// If-None-Match returns ErrNotModified (with headers); a failed If-Match
+	// returns ErrPreconditionFailed.
+	Stat(ctx context.Context, key Key, opts ...Option) (http.Header, error)
 	// Open an existing file in the cache.
 	//
 	// Expired files MUST NOT be returned.
 	// The returned headers MUST include a Last-Modified header.
 	// Must return os.ErrNotExist if the file does not exist.
-	Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error)
+	//
+	// Conditional opts are evaluated against the stored ETag: a satisfied
+	// If-None-Match returns ErrNotModified (with headers, no body); a failed
+	// If-Match returns ErrPreconditionFailed.
+	Open(ctx context.Context, key Key, opts ...Option) (io.ReadCloser, http.Header, error)
 	// Create a new file in the cache.
 	//
 	// If "ttl" is zero, a maximum TTL MUST be used by the implementation.

internal/cache/cachetest/suite.go

@@ -79,6 +79,10 @@ func Suite(t *testing.T, newCache func(t *testing.T) cache.Cache) {
 	t.Run("ETag", func(t *testing.T) {
 		testETag(t, newCache(t))
 	})
+
+	t.Run("Conditional", func(t *testing.T) {
+		testConditional(t, newCache(t))
+	})
 }
 
 func testCreateAndOpen(t *testing.T, c cache.Cache) {
@@ -485,6 +489,61 @@ func testETag(t *testing.T, c cache.Cache) {
 	assert.Equal(t, expectedETag, statHeaders.Get("ETag"))
 }
 
+// testConditional verifies that Open and Stat honour If-Match / If-None-Match
+// preconditions against the stored ETag, returning the unified sentinel errors.
+func testConditional(t *testing.T, c cache.Cache) {
+	defer c.Close()
+	ctx := t.Context()
+
+	content := []byte("conditional content")
+	key := cache.NewKey("test-conditional")
+
+	w, err := c.Create(ctx, key, nil, time.Hour)
+	assert.NoError(t, err)
+	_, err = w.Write(content)
+	assert.NoError(t, err)
+	assert.NoError(t, w.Close())
+
+	sum := sha256.Sum256(content)
+	etag := `"` + hex.EncodeToString(sum[:]) + `"`
+
+	t.Run("IfNoneMatchHitReturnsNotModified", func(t *testing.T) {
+		_, headers, err := c.Open(ctx, key, cache.IfNoneMatch(etag))
+		assert.IsError(t, err, cache.ErrNotModified)
+		assert.Equal(t, etag, headers.Get("ETag")) // headers surfaced for the 304
+
+		headers, err = c.Stat(ctx, key, cache.IfNoneMatch(etag))
+		assert.IsError(t, err, cache.ErrNotModified)
+		assert.Equal(t, etag, headers.Get("ETag"))
+	})
+
+	t.Run("IfNoneMatchMissServesBody", func(t *testing.T) {
+		reader, _, err := c.Open(ctx, key, cache.IfNoneMatch(`"other"`))
+		assert.NoError(t, err)
+		defer reader.Close()
+		data, err := io.ReadAll(reader)
+		assert.NoError(t, err)
+		assert.Equal(t, content, data)
+	})
+
+	t.Run("IfMatchHitServesBody", func(t *testing.T) {
+		reader, _, err := c.Open(ctx, key, cache.IfMatch(etag))
+		assert.NoError(t, err)
+		defer reader.Close()
+		data, err := io.ReadAll(reader)
+		assert.NoError(t, err)
+		assert.Equal(t, content, data)
+	})
+
+	t.Run("IfMatchMissReturnsPreconditionFailed", func(t *testing.T) {
+		_, _, err := c.Open(ctx, key, cache.IfMatch(`"other"`))
+		assert.IsError(t, err, cache.ErrPreconditionFailed)
+
+		_, err = c.Stat(ctx, key, cache.IfMatch(`"other"`))
+		assert.IsError(t, err, cache.ErrPreconditionFailed)
+	})
+}
+
 func testNamespaceDelete(t *testing.T, c cache.Cache) {
 	defer c.Close()
 	ctx := t.Context()

internal/cache/conditional.go

@@ -0,0 +1,22 @@
+package cache
+
+import (
+	"net/http"
+
+	"github.com/alecthomas/errors"
+
+	"github.com/block/cachew/client"
+)
+
+// conditionalShortCircuit evaluates conditional opts against the stored ETag in
+// headers. A nil error means the object should be served normally. A non-nil
+// error short-circuits the request: ErrNotModified is returned together with
+// headers (so callers can surface a 304 with the stored validators), while
+// ErrPreconditionFailed is returned with nil headers.
+func conditionalShortCircuit(headers http.Header, opts []Option) (http.Header, error) {
+	err := errors.WithStack(client.NewRequestOptions(opts...).Check(headers.Get(ETagKey)))
+	if errors.Is(err, ErrNotModified) {
+		return headers, err
+	}
+	return nil, err
+}

internal/cache/disk.go

@@ -232,7 +232,7 @@ func (d *Disk) Delete(_ context.Context, key Key) error {
 	return nil
 }
 
-func (d *Disk) Stat(ctx context.Context, key Key) (http.Header, error) {
+func (d *Disk) Stat(ctx context.Context, key Key, opts ...Option) (http.Header, error) {
 	path := d.keyToPath(d.namespace, key)
 	fullPath := filepath.Join(d.config.Root, path)
 
@@ -256,10 +256,13 @@ func (d *Disk) Stat(ctx context.Context, key Key) (http.Header, error) {
 	}
 
 	headers.Set("Content-Length", strconv.FormatInt(info.Size(), 10))
+	if h, err := conditionalShortCircuit(headers, opts); err != nil {
+		return h, err
+	}
 	return headers, nil
 }
 
-func (d *Disk) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, error) {
+func (d *Disk) Open(ctx context.Context, key Key, opts ...Option) (io.ReadCloser, http.Header, error) {
 	path := d.keyToPath(d.namespace, key)
 	fullPath := filepath.Join(d.config.Root, path)
 
@@ -297,6 +300,10 @@ func (d *Disk) Open(ctx context.Context, key Key) (io.ReadCloser, http.Header, e
 		return nil, nil, errors.Join(errors.Errorf("failed to update expiration time: %w", err), f.Close())
 	}
 
+	if h, condErr := conditionalShortCircuit(headers, opts); condErr != nil {
+		return nil, h, errors.Join(condErr, f.Close())
+	}
+
 	return f, headers, nil
 }
 

internal/cache/memory.go

@@ -58,7 +58,7 @@ func NewMemory(ctx context.Context, config MemoryConfig) (*Memory, error) {
 
 func (m *Memory) String() string { return fmt.Sprintf("memory:%dMB", m.config.LimitMB) }
 
-func (m *Memory) Stat(_ context.Context, key Key) (http.Header, error) {
+func (m *Memory) Stat(_ context.Context, key Key, opts ...Option) (http.Header, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
@@ -78,10 +78,13 @@ func (m *Memory) Stat(_ context.Context, key Key) (http.Header, error) {
 
 	headers := maps.Clone(entry.headers)
 	headers.Set("Content-Length", strconv.Itoa(len(entry.data)))
+	if h, err := conditionalShortCircuit(headers, opts); err != nil {
+		return h, err
+	}
 	return headers, nil
 }
 
-func (m *Memory) Open(_ context.Context, key Key) (io.ReadCloser, http.Header, error) {
+func (m *Memory) Open(_ context.Context, key Key, opts ...Option) (io.ReadCloser, http.Header, error) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
 
@@ -101,6 +104,9 @@ func (m *Memory) Open(_ context.Context, key Key) (io.ReadCloser, http.Header, e
 
 	headers := maps.Clone(entry.headers)
 	headers.Set("Content-Length", strconv.Itoa(len(entry.data)))
+	if h, err := conditionalShortCircuit(headers, opts); err != nil {
+		return nil, h, err
+	}
 	return io.NopCloser(bytes.NewReader(entry.data)), headers, nil
 }
 

internal/cache/noop.go

@@ -22,11 +22,11 @@ func NoOpCache() Cache {
 
 func (n *noOpCache) String() string { return "noop" }
 
-func (n *noOpCache) Stat(_ context.Context, _ Key) (http.Header, error) {
+func (n *noOpCache) Stat(_ context.Context, _ Key, _ ...Option) (http.Header, error) {
 	return nil, os.ErrNotExist
 }
 
-func (n *noOpCache) Open(_ context.Context, _ Key) (io.ReadCloser, http.Header, error) {
+func (n *noOpCache) Open(_ context.Context, _ Key, _ ...Option) (io.ReadCloser, http.Header, error) {
 	return nil, nil, os.ErrNotExist
 }