Inconsistent `Swarm-Redundancy-Level` Header Handling Across API Endpoints

[gacevicljubisa]

Summary

The Swarm-Redundancy-Level header is inconsistently handled across API endpoints and internal components. Some handlers respect the user-specified redundancy level while others ignore it and use hardcoded values (PARANOID or DefaultLevel). This creates unpredictable behavior and potential performance issues.

This issue requires input from research and product teams to determine appropriate defaults and whether all operations should respect the header.

Current State Analysis

Handler Behavior

Handler	Endpoint	Default	Respects Header	Issue
bytesUploadHandler	POST /bytes	NONE	✅	None
bzzUploadHandler	POST /bzz	NONE	✅	None
bzzDownloadHandler	GET /bzz/{address}/{path}	PARANOID	❌	loadsave.NewReadonly ignores header
bzzHeadHandler	HEAD /bzz/{address}/{path}	PARANOID	❌	loadsave.NewReadonly ignores header
downloadHandler	GET /bytes/{address}	PARANOID	✅	None

Problem Details

Critical Issues in API Handlers

BZZ Download Handlers (pkg/api/bzz.go)

Location: serveReference() method, line ~409

// BUG: Always uses redundancy.DefaultLevel (PARANOID) instead of rLevel variable
ls := loadsave.NewReadonly(s.storer.Download(cache), s.storer.Cache(), redundancy.DefaultLevel)

The header is parsed but ignored. This affects:

• GET /bzz/{address}/{path} - always uses PARANOID
• HEAD /bzz/{address}/{path} - always uses PARANOID

Hardcoded Redundancy Levels in Other Components

Stewardship Service (pkg/steward/steward.go)

• Line 44: traversal.New(ns.Download(true), joinerPutter, redundancy.DefaultLevel)
• Line 45: traversal.New(&netGetter{r}, joinerPutter, redundancy.DefaultLevel)

Node Bootstrap (pkg/node/bootstrap.go)

• Line 285: loadsave.NewReadonly(st, putter, redundancy.DefaultLevel)

Access Control Handlers (pkg/api/accesscontrol.go)

All access control operations hardcode redundancy.PARANOID:

• actDecryptionHandler (line 129)
• actListGranteesHandler (line 207)
• actEncryptionHandler (line 162)
• actGrantRevokeHandler (lines 347-348)
• actCreateGranteesHandler (lines 501-502)

Pin Operations (pkg/api/pin.go)

• Line 56: traverser := traversal.New(getter, s.storer.Cache(), redundancy.PARANOID)

Performance Impact

Critical Concerns

1. Forced Maximum Redundancy: When hardcoded to PARANOID, operations use the highest redundancy level (16 replicas) regardless of user needs

   • Increases network traffic by up to 16x
   • Increases storage requirements across the network
   • Slows down upload/download operations
   • Wastes node resources and bandwidth

2. No User Control: Users cannot optimize performance for their use case:

   • Cannot use lower redundancy for temporary or non-critical data
   • Cannot balance cost vs. reliability for different content types
   • Cannot reduce resource usage when appropriate

3. Inconsistent Behavior: Different endpoints with different defaults create confusion and make it difficult to predict system behavior

Questions for Research & Product Teams

Research Team:

• Should all operations respect the Swarm-Redundancy-Level header, or are there security/reliability reasons for forcing PARANOID on specific operations (e.g., access control, pinning)?
• What are the recommended default redundancy levels for different operation types?
• Are there minimum redundancy requirements for sensitive operations?

Product Team:

• Should users have full control over redundancy levels for all operations?
• Should different operations have different default redundancy levels, or should there be one global default?
• How should this be communicated in API documentation?
• Are there use cases where forcing PARANOID is desirable?

[nugaon]

BZZ retrieval takes into account the rLevel on feed retrieval, otherwise it goes with the default redudancy level which is inconsistent, so it must be corrected. Modifying the parameter in serveReference affects HEAD request as well.

ACT should include this parameter, but fall back to PARANOID if that is not defined. It is reasonable to set lower level for testing or short-living/frequently changing changes in access control.

Stewardship and Pinning endpoints do not define Swarm-Redundancy-Level and rLevel is stored in the service struct which should be defined as a parameter of the Traverse method instead.
I think, the redundancy header could be optional on both, just to keep it unified across endpoints, though it won't be a overused feature for sure.

Chain snapshot is made independently from the Bee's operation, presumably with the hard-coded PARANOID value as well. I believe it would be the best to leave as it is, since it is not connected to any API.

There is no security reasons to not allow redundancy API header to be exposed and change the default setting, I think the redundancy level alignment with some features was just neglected.

The decision about the default value for all operations was PARANOID for GET, and for POST is none. The former is because

1. technically anyone could append to the dispersed replicas independently from the orignal uploader.
2. it only applies to fetch the root chunk data, after then the redundancy level is encoded in the chunk's span.
   The PARANOID level should make downloads faster, not slow them down.

I'm confused about "the sensitive operation" related question. The user should decide what the correct level is for each type of data.

OpenAPI documentation must be adjusted by adding the missing header descriptions.

[nugaon]

New consideration is whether to add the redundancy header to chunk, feed and soc POST endpoints as well due to of ACT. How to address this is debatable, since it could introduce confusion, as no dispersed replicas would be generated for the uploaded chunk itself (except later for SOCs and feeds).
IMO, it can be detailed in the documentation that, it is only for setting ACT erasure level.
In another PR, dispersed replica feature could be added for chunk POST endpoint, wdyt?

[zsgsp]

Revisit on a research call.

[zsgsp]

No progress.

[zelig]

HEADER value correctly overwrites value.
In case of retrieval, redundancy level only matters for single chunk EC scopes (root chunk and SOC) and affects how many dispersed replicas are searched.

Otherwise EC redundancy level is encoded in the packed-address chunk (intermediate chunk of the file tree).

Different defaults across upload and retrieval.
Upload is MEDIUM.
Retrieval PARANOID. This choice is motivated by the fact that if downloader only knows root hash and nothing about the upload redundancy, then this maximises the chance of finding a replica.

We recommend no special setting for other chunk functions (like ACT manifest etc)

see https://github.com/ethersphere/research-tasks/issues/1#issuecomment-3902695212

[nugaon]

There is zero redundancy level for uploads at the moment,
and the headers do not overwrite the values on all endpoints:

• bee/pkg/api/bzz.go

  Lines 409 to 410 in 975f137

  	ls := loadsave.NewReadonly(s.storer.Download(cache), s.storer.Cache(), rLevel)
  	feedDereferenced := false

• bee/pkg/api/pin.go

  Lines 69 to 70 in 975f137

  	traverser := traversal.New(getter, s.storer.Cache())

• bee/pkg/api/stewardship.go

  Lines 67 to 68 in 975f137

  	err = s.steward.Reupload(r.Context(), paths.Address, stamper, rLevel)
  	if err != nil {

edit: the permalinks are the fixed versions, see diff in #5383

Why is the default redundancy coding not symmetrical at ACT if there is no API to extend the dispersed replicas of a root chunk? It could save requests if it was MEDIUM for uploads and downloads as well.