feat(gsoc): fine grained API#5497
Conversation
Add `Swarm-Soc-Fields` header to allow clients to request specific SOC fields (address, recoveredpubkey, identifier, signature, wrappedaddress, span, payload) in GSOC WebSocket messages. Add `Swarm-Cache-Wrapped-Chunk` header to enable caching of wrapped chunks on the node. Update GSOC handler to pass full SOC object instead of just payload, enabling access to all chunk properties. Adjust WebSocket buffer sizes to accommodate maximum SOC fields message size.
Add tests for `Swarm-Soc-Fields` header to verify requesting specific SOC fields (identifier, wrappedAddress, payload) and full wrapped chunk data (span + payload). Add test for `Swarm-Cache-Wrapped-Chunk` header to verify wrapped chunks are cached and retrievable. Update test helpers to support custom headers and return storer instance. Update gsoc handler signature to accept full SOC object instead of payload bytes.
There was a problem hiding this comment.
General comment: payload is the only variable-length field, but nothing stops clients from putting it before fixed fields (e.g. payload,identifier). That’s parseable only if you know all fixed sizes and derive payload_len = frame_len − fixed_total — which isn’t documented in OpenAPI. A typical left-to-right parser will misread or fail on those orderings. Worth either requiring payload to be last, or documenting field sizes and the parsing rule explicitly.
nugaon
force-pushed
the
feat/gsoc-fine-grained
branch
from
71f67e5 to
46186ef
Compare
|
great catch @sbackend123 ! I wouldn't put any check for the serialization order. The payload always can be recovered and define its length from the response bytes, because all other properties have fixed length -> if |
2 participants
Checklist
Description
Extends the GSOC (
/gsoc/subscribe/{address}) WebSocket endpoint so that clients can configure which SOC fields are serialized and sent on every incoming message, and optionally cache the wrapped chunk locally.New headers:
Swarm-Soc-Fields— comma-separated list of fields to include in the binary message. Allowed values:address,recoveredPubKey,identifier,signature,wrappedAddress,span,payload. Defaults topayloadfor backward compatibility.Swarm-Cache-Wrapped-Chunk— whentrue, the wrapped chunk of every incoming GSOC message is stored in the local cache so it can later be resolved through the bytes endpoint (useful when the SOC wraps a root chunk larger than 4 KB).API / handler changes:
gsoc.Handlersignature is changed fromfunc([]byte)tofunc(*soc.SOC)so subscribers have access to all SOC properties.ReadBufferSizeandWriteBufferSizeare sized toswarm.SocMaxChunkSizeandmaxSocFieldsSizerespectively to avoid split writes for the worst-case serialized message.OpenAPI:
SwarmCommon.yamland referenced them in the/gsoc/subscribe/{address}operation.8.1.0to8.2.0.Open API Spec Version Changes (if applicable)
Bee API:
8.1.0→8.2.0Motivation and Context (Optional)
Previously the GSOC subscription returned only the raw payload of the wrapped chunk. Consumers who also needed the span, the SOC address, the signature, or the recovered public key had no way to obtain them through the WebSocket. This change makes the subscription fully configurable while keeping the default behavior unchanged.
Caching the wrapped chunk is a separate convenience for users who publish large content through GSOC and want recipients to be able to fetch the full content via the standard bytes endpoint.
Related Issue (Optional)
Screenshots (if appropriate):
AI Disclosure