Merge pull request #144 from bright-room/feat/96-validator-composition-utility-all-any

Close #96: Add All and Any validator composition utilities

Author: kukv

CLAUDE.md

@@ -33,7 +33,7 @@ make shell          # Interactive bash in container
 Key interfaces:
 - `Storage` — `Get`/`Set`/`Delete` for cached responses (pluggable backend)
 - `Locker` — optional per-key mutual exclusion for concurrent request handling. Storage implementations that also implement `Locker` enable automatic lock acquisition in the middleware. Returns 409 Conflict on lock failure.
-- `Validator` — `Validate(Config) error` for configuration validation. `ValidatorFunc` is a function adapter (like `http.HandlerFunc`). Preset validators (`MaxTTL`, `MinTTL`, etc.) return `*PresetValidator` which supports `.WithMessage()` for custom error messages.
+- `Validator` — `Validate(Config) error` for configuration validation. `ValidatorFunc` is a function adapter (like `http.HandlerFunc`). Preset validators (`MaxTTL`, `MinTTL`, etc.) return `*PresetValidator` which supports `.WithMessage()` for custom error messages. Composition functions `All` (AND) and `Any` (OR) combine multiple validators and also return `*PresetValidator`.
 
 Configuration uses the **Functional Options** pattern (`WithXxx()` functions).
 

README.md

@@ -138,6 +138,37 @@ mw, err := idem.New(
 )
 ```
 
+#### Validator Composition
+
+Use `All` and `Any` to combine validators with AND / OR logic:
+
+```go
+mw, err := idem.New(
+	idem.WithTTL(1 * time.Hour),
+	idem.WithValidation(
+		// All: every validator must pass (AND)
+		idem.All(
+			idem.MinTTL(1 * time.Minute),
+			idem.MaxTTL(24 * time.Hour),
+		),
+		// Any: at least one validator must pass (OR)
+		idem.Any(
+			idem.AllowedKeyHeaders("Idempotency-Key"),
+			idem.KeyHeaderPattern(regexp.MustCompile(`^X-`)),
+		),
+	),
+)
+```
+
+`All` and `Any` return `*PresetValidator`, so they support `.WithMessage()` and can be nested arbitrarily:
+
+```go
+idem.All(
+	idem.Any(v1, v2),
+	v3,
+).WithMessage("validation failed")
+```
+
 ### Metrics
 
 Use `WithMetrics` to observe cache hits, misses, lock contention, and errors — for example, to export to Prometheus:

errors.go

@@ -16,4 +16,7 @@ var (
 
 	// ErrInvalidTTLRange is returned by TTLRange when min exceeds max.
 	ErrInvalidTTLRange = errors.New("idem: TTLRange min must not exceed max")
+
+	// ErrAllValidatorsFailed is returned by Any when every validator fails.
+	ErrAllValidatorsFailed = errors.New("idem: all validators failed")
 )

validator.go

@@ -92,6 +92,37 @@ func KeyHeaderPattern(pattern *regexp.Regexp) *PresetValidator {
 	}
 }
 
+// All returns a Validator that succeeds only when every given validator
+// succeeds. Validators run in order; validation stops at the first error.
+func All(validators ...Validator) *PresetValidator {
+	return &PresetValidator{
+		validate: func(cfg Config) error {
+			for _, v := range validators {
+				if err := v.Validate(cfg); err != nil {
+					return err
+				}
+			}
+			return nil
+		},
+	}
+}
+
+// Any returns a Validator that succeeds when at least one of the given
+// validators succeeds. Validators run in order; validation stops at the
+// first success. If all validators fail, an error is returned.
+func Any(validators ...Validator) *PresetValidator {
+	return &PresetValidator{
+		validate: func(cfg Config) error {
+			for _, v := range validators {
+				if err := v.Validate(cfg); err == nil {
+					return nil
+				}
+			}
+			return ErrAllValidatorsFailed
+		},
+	}
+}
+
 // AllowedKeyHeaders returns a Validator that requires the key header
 // name to be one of the specified allowed values.
 func AllowedKeyHeaders(allowed ...string) *PresetValidator {