feat(validation): implement custom validation for redundancy level with improved error messaging

Author: akrem-chabchoub

pkg/api/api.go

@@ -214,8 +214,9 @@ type Service struct {
 
 	whitelistedWithdrawalAddress []common.Address
 
-	preMapHooks map[string]func(v string) (string, error)
-	validate    *validator.Validate
+	preMapHooks             map[string]func(v string) (string, error)
+	validationCustomErrorMessages map[string]func(err validator.FieldError) error
+	validate                *validator.Validate
 
 	redistributionAgent *storageincentives.Agent
 
@@ -321,6 +322,7 @@ func New(
 		}
 		return name
 	})
+	s.setupValidation()
 	s.stamperStore = stamperStore
 
 	for _, v := range whitelistedWithdrawalAddress {
@@ -709,11 +711,17 @@ func (s *Service) mapStructure(input, output any) func(string, log.Logger, http.
 			case []byte:
 				val = string(v)
 			}
+			var cause error
+			if msgFn, ok := s.validationCustomErrorMessages[err.Tag()]; ok {
+				cause = msgFn(err)
+			} else {
+				cause = fmt.Errorf("want %s:%s", err.Tag(), err.Param())
+			}
 			vErrs = multierror.Append(vErrs,
 				&validationError{
 					Entry: strings.ToLower(err.Field()),
 					Value: val,
-					Cause: fmt.Errorf("want %s:%s", err.Tag(), err.Param()),
+					Cause: cause,
 				})
 		}
 		return response(vErrs.ErrorOrNil())

pkg/api/bytes.go

@@ -40,7 +40,7 @@ func (s *Service) bytesUploadHandler(w http.ResponseWriter, r *http.Request) {
 		Pin            bool             `map:"Swarm-Pin"`
 		Deferred       *bool            `map:"Swarm-Deferred-Upload"`
 		Encrypt        bool             `map:"Swarm-Encrypt"`
-		RLevel         redundancy.Level `map:"Swarm-Redundancy-Level" validate:"lte=4"`
+		RLevel         redundancy.Level `map:"Swarm-Redundancy-Level" validate:"rLevel"`
 		Act            bool             `map:"Swarm-Act"`
 		HistoryAddress swarm.Address    `map:"Swarm-Act-History-Address"`
 	}{}

pkg/api/bytes_test.go

@@ -449,7 +449,7 @@ func TestBytesRedundancyLevel(t *testing.T) {
 				Reasons: []jsonhttp.Reason{
 					{
 						Field: "swarm-redundancy-level",
-						Error: fmt.Sprintf("want lte:%d", maxValidLevel),
+						Error: fmt.Sprintf("want redundancy level to be in the range of %d and %d", int(redundancy.NONE), int(redundancy.PARANOID)),
 					},
 				},
 			},

pkg/api/bzz.go

@@ -72,7 +72,7 @@ func (s *Service) bzzUploadHandler(w http.ResponseWriter, r *http.Request) {
 		Deferred       *bool            `map:"Swarm-Deferred-Upload"`
 		Encrypt        bool             `map:"Swarm-Encrypt"`
 		IsDir          bool             `map:"Swarm-Collection"`
-		RLevel         redundancy.Level `map:"Swarm-Redundancy-Level" validate:"lte=4"`
+		RLevel         redundancy.Level `map:"Swarm-Redundancy-Level" validate:"rLevel"`
 		Act            bool             `map:"Swarm-Act"`
 		HistoryAddress swarm.Address    `map:"Swarm-Act-History-Address"`
 	}{}
@@ -387,7 +387,7 @@ func (s *Service) serveReference(logger log.Logger, address swarm.Address, pathV
 		Cache                 *bool             `map:"Swarm-Cache"`
 		Strategy              *getter.Strategy  `map:"Swarm-Redundancy-Strategy"`
 		FallbackMode          *bool             `map:"Swarm-Redundancy-Fallback-Mode"`
-		RLevel                *redundancy.Level `map:"Swarm-Redundancy-Level" validate:"omitempty,lte=4"`
+		RLevel                *redundancy.Level `map:"Swarm-Redundancy-Level" validate:"omitempty,rLevel"`
 		ChunkRetrievalTimeout *string           `map:"Swarm-Chunk-Retrieval-Timeout"`
 	}{}
 
@@ -599,7 +599,7 @@ func (s *Service) serveManifestEntry(
 func (s *Service) downloadHandler(logger log.Logger, w http.ResponseWriter, r *http.Request, reference swarm.Address, additionalHeaders http.Header, etag, headersOnly bool, rootCh swarm.Chunk) {
 	headers := struct {
 		Strategy              *getter.Strategy  `map:"Swarm-Redundancy-Strategy"`
-		RLevel                *redundancy.Level `map:"Swarm-Redundancy-Level" validate:"omitempty,lte=4"`
+		RLevel                *redundancy.Level `map:"Swarm-Redundancy-Level" validate:"omitempty,rLevel"`
 		FallbackMode          *bool             `map:"Swarm-Redundancy-Fallback-Mode"`
 		ChunkRetrievalTimeout *string           `map:"Swarm-Chunk-Retrieval-Timeout"`
 		LookaheadBufferSize   *int              `map:"Swarm-Lookahead-Buffer-Size"`

pkg/api/bzz_test.go

@@ -1300,7 +1300,7 @@ func TestBzzDownloadRedundancyLevel(t *testing.T) {
 				Reasons: []jsonhttp.Reason{
 					{
 						Field: "swarm-redundancy-level",
-						Error: fmt.Sprintf("want lte:%d", maxValidLevel),
+						Error: fmt.Sprintf("want redundancy level to be in the range of %d and %d", int(redundancy.NONE), int(redundancy.PARANOID)),
 					},
 				},
 			},

pkg/api/validation.go

@@ -0,0 +1,30 @@
+// Copyright 2026 The Swarm Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package api
+
+import (
+	"fmt"
+
+	"github.com/ethersphere/bee/v2/pkg/file/redundancy"
+	"github.com/go-playground/validator/v10"
+)
+
+const (
+	RedundancyLevelTag = "rLevel"
+)
+
+// setupValidation configures custom validation rules and their custom error messages.
+func (s *Service) setupValidation() {
+	s.validate.RegisterValidation(RedundancyLevelTag, func(fl validator.FieldLevel) bool {
+		level := redundancy.Level(fl.Field().Uint())
+		return level.Validate()
+	})
+
+	s.validationCustomErrorMessages = map[string]func(err validator.FieldError) error{
+		RedundancyLevelTag: func(err validator.FieldError) error {
+			return fmt.Errorf("want redundancy level to be in the range of %d and %d", int(redundancy.NONE), int(redundancy.PARANOID))
+		},
+	}
+}

pkg/file/redundancy/level.go

@@ -29,6 +29,11 @@ const (
 	PARANOID
 )
 
+// Validate validates the redundancy level
+func (l Level) Validate() bool {
+	return l >= NONE && l <= PARANOID
+}
+
 // GetParities returns number of parities based on appendix F table 5
 func (l Level) GetParities(shards int) int {
 	et, err := l.getErasureTable()