docs: add SVS v4 specification - #23
Conversation
Uploads the SVS v4 wire-format specification (mhash, distinct FullStateVector / PartialStateVector / SvsDataRef TLVs, and the publish + pull recovery mode) alongside the existing v3 Specification.md. A 'Migration from Version 3' section (§9) summarizes the wire-format deltas. Source: https://github.com/named-data/ndnd/blob/psvs/docs/svs-v4.md Reference implementation: named-data/ndnd std/sync std/ndn/svs/v4
|
|
||
| ### 1.2 Large groups | ||
|
|
||
| When the encoded State Vector exceeds **`SyncVectorThreshold`** (a |
There was a problem hiding this comment.
The transition from a small group to a large group could be sudden.
It could occur when:
- A new member (name + boot time combination) joins the group.
- A sequence number's TLV-LENGTH increases, such as incrementing from 0xFFFF to 0x00010000.
This implies that, every node must be prepared to accept both formats at all times.
Hence, having both "small group" and "large group" would unnecessarily complicate the protocol and its implementations.
If I read correctly, the Direct FULL mode is either same as or very similar to the small group mode, I suggest deleting small group mode altogether.
Instead, the protocol could specify that a producer MUST send as Direct FULL mode when the state vector size is within the threshold.
|
|
||
| ## 2. Format and Naming | ||
|
|
||
| ### 2.1 Sync Interest |
There was a problem hiding this comment.
Sync Interest Prefix Announcement (introduced in #21) is missing.
| | `0xCE` | **PARTIAL** | `StateVector` contains a subset (§4.2). Used for new publication only when FULL exceeds threshold. | | ||
|
|
||
| Distinct TLVs (instead of a shared field with a discriminator) let a | ||
| receiver skip the more expensive subset-evaluation code path when it sees |
There was a problem hiding this comment.
The spec should not use the term "code path", which is an implementation concept.
|
|
||
| ### 4.3 `SyncVectorThreshold` | ||
|
|
||
| `SyncVectorThreshold` is a fixed library constant (1200 bytes) that bounds |
There was a problem hiding this comment.
The spec should not use the term "library constant", which is an implementation concept.
|
|
||
| **Computation:** | ||
|
|
||
| ```abnf |
There was a problem hiding this comment.
This block is not valid ABNF syntax.
You should use ABNF to define what goes into the plaintext, and then use a non-ABNF block to define mhash concept.
| full-vector Data. | ||
|
|
||
| ```abnf | ||
| SvsData = SVS-DATA-TYPE TLV-LENGTH |
There was a problem hiding this comment.
The outer SVS-DATA-TYPE TLV-LENGTH is redundant.
The enclosed Data packet's Content could just contain MemberSetHash (FullStateVector|PartialStateVector|SvsDataRef), without the T and L parts.
| ( FullStateVector | ||
| | PartialStateVector | ||
| | SvsDataRef ) ; exactly one | ||
|
|
There was a problem hiding this comment.
MemberSetHash and SvsDataRef should have ABNF definitions.
| ``` | ||
|
|
||
| | Field | TLV type | Value | | ||
| |-------|----------|-------| |
There was a problem hiding this comment.
Delete the table in favor of the ABNF block.
| PARTIAL in this case as a signal to the caller; the caller MUST treat an | ||
| empty PARTIAL as the publish + pull trigger instead of forwarding it. | ||
|
|
||
| An implementation MAY use the following selection priority: |
There was a problem hiding this comment.
Why is this a MAY instead of a MUST ?
|
|
||
| --- | ||
|
|
||
| ## 9. Migration from Version 3 |
There was a problem hiding this comment.
I don't see the necessity of a breaking change.
Instead, the proposed feature can be added incrementally into SVS v3 in the following way:
- Choose a non-critical TLV-TYPE number for
MemberSetHash. - When
StateVectoris small enough to fit in a State Vector Data, encodeMemberSetHash + StateVector. Recipients who do not understandMemberSetHashwould ignore it. - If a State Vector Data is received with
StateVectoronly, a recipient who needsMemberSetHashcan compute it from theStateVector. - Choose a critical TLV-TYPE number for
PartialStateVectorandSvsDataRef;SvsDataRefcontains nestedName. - When
StateVectoris too large to fit in a State Vector Data, encode eitherMemberSetHash + PartialStateVectorandMemberSetHash + SvsDataRef. Recipients who do not understand this scheme would drop the packet after seeing a critical TLV-TYPE number.
This maintains wire format compatibility and enables upgrading SVS v3 to support the PartialStateVector feature.
Pesa
left a comment
Pesa
left a comment
There was a problem hiding this comment.
General NAK on the design per today's NDN group discussion.
3 participants
This PR adds the SVS v4 wire-format specification as
Specification-v4.md, alongside the existing v3Specification.md.Summary
SVS v4 extends the v3 wire format to support large sync groups by introducing:
mhash, TLV0xCB) carried in every Sync Data.VectorTypediscriminator with three distinct TLVs:FullStateVector(0xCD) — direct form carrying the complete State Vector.PartialStateVector(0xCE) — direct form carrying a publication-time subset, used when the encoded FULL exceedsSyncVectorThreshold.SvsDataRef(0x07) — publish-only form pointing to a retrievable full-vector Data.mhashmismatch or when the local FULL exceedsSyncVectorThreshold. Producers publish full-vector Data at/<group>/<node>/<boot>/32=sv/<version>and send a publish-only Sync Data referencing it./<sync-prefix>/v=4.SyncVectorThresholdis a fixed library constant of 1200 bytes.Reference implementation
The ndnd Go implementation in
named-data/ndnd(std/sync,std/ndn/svs/v4) ships against this spec on thepsvsbranch.File
Specification-v4.md(508 lines)This is a non-breaking, additive contribution —
Specification.md(v3) is left untouched. v3 and v4 deployments cannot interoperate on the same Sync Interest prefix (v=3vsv=4), per the §9 migration note.cc @yoursunny — addressing the request from named-data/ndnd#190.