Skip to content

Commit 4a2539b

Browse files
committed
docs(unixfs): reject interleaved PBNode fields
Clarify that Links and Data must each appear as a contiguous group on the wire. Interleaving (e.g. Links, Data, Links) produces duplicate Links lists and decoders should reject it. Addresses PR feedback from @achingbrain.
1 parent 23618d8 commit 4a2539b

File tree

1 file changed

+6
-3
lines changed

1 file changed

+6
-3
lines changed

src/unixfs.md

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,9 @@ This field order is stricter than the intuitive protobuf convention of
142142
serializing fields by field number.
143143

144144
Decoders MUST accept both field orderings, as existing IPFS data contains
145-
blocks encoded in either order.
145+
blocks encoded in either order. However, each field MUST appear as a
146+
contiguous group: interleaving (e.g., `Links`, `Data`, `Links`) is not
147+
valid and decoders SHOULD reject it.
146148

147149
Encoders that want to be compliant with the `unixfs-v0-2015` and
148150
`unixfs-v1-2025` profiles from
@@ -1247,8 +1249,9 @@ Following the [Robustness Principle](https://specs.ipfs.tech/architecture/princi
12471249
implementations writing backward and forward compatible software should be
12481250
conservative in what they produce (use the field order expected by the target
12491251
profile) and liberal in what they accept (decode blocks regardless of field
1250-
order). A future IPIP introducing new profiles may adopt a different field
1251-
order convention.
1252+
order). Interleaving (e.g., `Links`, `Data`, `Links`) is not a valid
1253+
third ordering; it produces duplicate `Links` lists. A future IPIP
1254+
introducing new profiles may adopt a different field order convention.
12521255

12531256
A practical consequence of the current `Links`-before-`Data` order is that
12541257
streaming protobuf parsers encounter all link entries before `PBNode.Data`.

0 commit comments

Comments
 (0)