feat: download mode for the chunk stream endpoint

[martinconic]

Checklist

• I have read the coding guide.
• My change requires a documentation update, and I have done it.
• I have added tests to cover my changes.
• I have filled out the description and linked the related issues.

Description

Adds a download mode to GET /chunks/stream. A client opens one websocket and pulls many chunks over it, instead of paying for an HTTP request per chunk.

Closes #5417, closes #5599.

Protocol

Mode is fixed at handshake — via Sec-WebSocket-Protocol: swarm-chunk-download, or ?mode=download for browser clients that cannot set headers. A connection is an upload stream or a download stream, never both.

Request frame: ['D'][32-byte address]..., up to 256 addresses. 'D' is the command byte from #5417; batching sits under it so the two compose, and it leaves room to add commands later without breaking clients.

Reply frame: [status][32-byte address][payload] — 0x00 success, 0x01 not found, 0x02 error. Replies arrive out of order as retrievals complete, so clients match on the address. Exactly one reply per requested address.

swarm-cache is honoured on the download path, matching GET /chunks/{address}.

From #5599

Batched requests (256/frame), a bounded worker pool rather than an uncontrolled request storm, streamed partial results, per-address success/failure, and relief from the browser's six-connections-per-host limit. Implemented over websocket — one of the response options that issue listed — rather than POST /chunks/batch.

The video-streaming motivation in #5599 is not served by this endpoint and has been split out. Playback wants HTTP Range and server-side read-ahead on /bzz; this endpoint has no cancellation and strict FIFO delivery, so a seek would mean dropping the connection. It suits random-access and bulk workloads: manifest traversal, SQLite/Parquet-style page reads, bulk sync, pinning.

Notes for review

• topology.ErrNotFound maps to 0x01, matching how bzz.go treats the same error from the same storer.Download call.
• Per-request timeout is getter.DefaultFetchTimeout, the constant the joiner already uses, so one unreachable chunk can't park a worker indefinitely.
• The delivery write deadline is 5 minutes. A client that buffers ahead stops reading while its buffer drains; a short deadline tears the stream down for it. Verified: with a 2s deadline a 6s pause killed the stream after 28 of 2000 chunks.
• Control frames use a separate 5s deadline and don't take the write mutex — WriteControl is safe concurrently, and holding the mutex would let a slow delivery delay the close frame.
• Shutdown closes the connection so the blocked ReadMessage returns, instead of api.Close() timing out against a 15-minute read deadline.
• OpenAPI bumped to 8.2.0.

AI Disclosure

• This PR contains code that has been generated by an LLM.
• I have reviewed the AI generated code thoroughly.
• I possess the technical expertise to responsibly review the code generated in this PR.

[acud]

not sure about this custom serialization by hand thing... it is just specced out in the openapi spec and assumed that implementers should implement it by hand. it is fragile and breakable. why not use some sort of standard serialization format to both decode the request and encode the response?

[aloknerurkar]

Since we are making breaking changes and also building on the serialization thread — I'd suggest going further than reworking the download framing: use one connection for both directions, with request/response semantics and a request id.

Two things this fixes beyond tidiness:

1. Upload is round-trip bound. The upload loop is strictly sequential — read → put → ack → read, one chunk in flight. Each chunk costs a full RTT, so on a 50ms link that's ~20 chunks/sec regardless of bandwidth. Download already has a 16-worker pool; upload has none. stamper.Stamp already takes issuer.mtx (pkg/postage/stamper.go:43), so concurrent stamping is safe — the ceiling is the protocol, not the storage layer.

2. Neither direction is recoverable. Download replies carry no id, and the upload ack is successWsMsg = []byte{} — an empty frame with no address at all. Clients correlate purely by ordering. On any error both paths call sendErrorClose and drop the connection, so a client that had N requests outstanding cannot tell which completed. For bulk upload that means restarting from zero.

A shared envelope — [type][8-byte request-id][payload] for requests, [type][8-byte request-id][status][payload] for responses — would give:

• one read loop feeding one typed job channel, with a worker pool serving both Get and Put (removes the duplicated read/deadline/close-handler logic between the two handlers)
• pipelined uploads instead of one-at-a-time
• per-request error status instead of connection teardown, so a single bad chunk no longer kills the stream
• correlation for recovery after an error close

I'd keep this as raw binary rather than JSON-RPC or protobuf. JSON-RPC costs more on the wire with base64 and ~15x encode/decode — self-defeating for an endpoint that exists to cut per-chunk overhead. Protobuf is bee's p2p convention but has never appeared in pkg/api; requiring a schema compiler would be a new burden on bee-js. The binary envelope stays a four-line DataView parse in the browser with no dependency.

The upload stream endpoint was not written with care. I was going through the code and there is a lot of scope to cleanup. Multiple putters defined, deferred/direct upload semantics, stamped and unstamped chunks etc. I feel that this would make it much more usable for clients and also close to what elad mentioned about having grpc style chunk get/put API.

[aloknerurkar]

Exactly one reply per requested address, and "a dropped frame is indistinguishable from a slow one" because replies carry no request id. But the protocol-error paths in the read loop (sendErrorClose + return on bad message type, bad length, unknown opcode, oversized batch) void every in-flight request silently.

A client that sends 256 addresses and then trips CloseMessageTooBig on its next frame has no way to determine which of the first 256 were answered. With no request id and no per-batch boundary marker in the reply stream, the only recovery is to discard everything and re-request.

The OpenAPI spec documents the close codes, but not that pending replies are lost when they fire. At minimum that consequence belongs in the spec. A framing with a request/batch id — which is largely what @acud point about a standard serialization format would give you for free — would make it recoverable instead.

[martinconic]

Since we are making breaking changes and also building on the serialization thread — I'd suggest going further than reworking the download framing: use one connection for both directions, with request/response semantics and a request id.

Two things this fixes beyond tidiness:

1. Upload is round-trip bound. The upload loop is strictly sequential — read → put → ack → read, one chunk in flight. Each chunk costs a full RTT, so on a 50ms link that's ~20 chunks/sec regardless of bandwidth. Download already has a 16-worker pool; upload has none. stamper.Stamp already takes issuer.mtx (pkg/postage/stamper.go:43), so concurrent stamping is safe — the ceiling is the protocol, not the storage layer.
2. Neither direction is recoverable. Download replies carry no id, and the upload ack is successWsMsg = []byte{} — an empty frame with no address at all. Clients correlate purely by ordering. On any error both paths call sendErrorClose and drop the connection, so a client that had N requests outstanding cannot tell which completed. For bulk upload that means restarting from zero.

A shared envelope — [type][8-byte request-id][payload] for requests, [type][8-byte request-id][status][payload] for responses — would give:

• one read loop feeding one typed job channel, with a worker pool serving both Get and Put (removes the duplicated read/deadline/close-handler logic between the two handlers)
• pipelined uploads instead of one-at-a-time
• per-request error status instead of connection teardown, so a single bad chunk no longer kills the stream
• correlation for recovery after an error close

I'd keep this as raw binary rather than JSON-RPC or protobuf. JSON-RPC costs more on the wire with base64 and ~15x encode/decode — self-defeating for an endpoint that exists to cut per-chunk overhead. Protobuf is bee's p2p convention but has never appeared in pkg/api; requiring a schema compiler would be a new burden on bee-js. The binary envelope stays a four-line DataView parse in the browser with no dependency.

The upload stream endpoint was not written with care. I was going through the code and there is a lot of scope to cleanup. Multiple putters defined, deferred/direct upload semantics, stamped and unstamped chunks etc. I feel that this would make it much more usable for clients and also close to what elad mentioned about having grpc style chunk get/put API.

Thank you for this, sounds like a good change. @acud do you also agree?

[acud]

@martinconic i generally encourage the initiative from @aloknerurkar, but i'm still not 100% convinced a custom encoding is right.
@aloknerurkar, to answer some of your points:

• the per-chunk overhead we are reducing has to do more with TCP socket open/close overhead and all sorts of stamper serialization overhead, not message encoding
• i agree that it would be better to have things as you suggested
• i'd still suggest to have a standard encoding library, ideally protobuf, because it has tooling out there and you don't have to send people (or agents) to do endianness or the likes in a browser js library
• also not sure, if all is managed on one websocket, how much we have to deal with partial reads/flushes/buffering

i think we can progress with this proposal, and make serialization a pluggable implementation. but in general i'd encourage to move away from hand written serialization at least on wire-formats (persistence is a different story).

[aloknerurkar]

@martinconic i generally encourage the initiative from @aloknerurkar, but i'm still not 100% convinced a custom encoding is right. @aloknerurkar, to answer some of your points:

• the per-chunk overhead we are reducing has to do more with TCP socket open/close overhead and all sorts of stamper serialization overhead, not message encoding
• i agree that it would be better to have things as you suggested
• i'd still suggest to have a standard encoding library, ideally protobuf, because it has tooling out there and you don't have to send people (or agents) to do endianness or the likes in a browser js library
• also not sure, if all is managed on one websocket, how much we have to deal with partial reads/flushes/buffering

i think we can progress with this proposal, and make serialization a pluggable implementation. but in general i'd encourage to move away from hand written serialization at least on wire-formats (persistence is a different story).

I am fine with protobuf. The only reason I didn't suggest it is that bee-js/javascript will be primary consumer if this is successful and I remember there were issues with javascript ecosystem when working with protobuf. I spoke to claude and I see that there is a new typescript compiler which makes things easier. So I am totally on board!