Protocol specification: Metadata Header included in Frame Header?

[obergner]

Background

Maybe it's just me but I find the section on Metadata Optional Header in Frame Header Format ambiguous:

Specific Frame Types MAY contain Metadata. If that Frame Type supports both Data and Metadata, the optional Metadata header MUST be included. This metadata header is between the Frame Header and any payload.

The last sentence seems to imply that the metadata header is considered not to be a part of the Frame Header.

However,

(24 bits = max value 16,777,215) Unsigned 24-bit integer representing the length of Metadata in bytes. Excluding Metadata Length field.

and

Metadata Length MUST be equal to the Frame Length minus the sum of the length of the Frame Header and the length of the Frame Payload, if present.

make it clear that the specification does indeed consider the Metadata Optional Header a component of the Frame Header. Otherwise the numbers would not add up.

This tripped me up when I recently started to implement the RSocket protocol in a pet project.

Suggestion

Change

This metadata header is between the Frame Header and any payload.

to something along the lines of

This metadata header is included in the Frame Header immediately following its Flags.

[yschimke]

Thanks, want to submit a PR with your suggested wording fix?

[obergner]

@yschimke I would gladly do so. However, I have come to doubt that my suggested fix would be accurate. It seems that the Metadata Optional Header (aka metadata length) is indeed not part of the Frame Header. Although the specification lists it in the paragraph that defines Frame Header.

I wanted to implement an encoder for SETUP frames and was unsure where in the byte stream to encode metadata length in case the metadata flag was set. The specification as I read it (see above) seemed to imply that it should follow immediately after the frame header.

However, none of the ASCII diagrams illustrating frame wire formats explicitly state where to put the metadata header, including the ASCII diagram for SETUP frame. I turned to rsocket-java and rsocket-ccp to find out how they handle the metadata header in SETUP frames. They encode it immediately before any metadata payload in the SETUP frame, so only after version, keep alive, max lifetime etc., thereby separating Frame Header and Metadata Optional Header.

This seems to imply:

1. Semantically, Metadata Optional Header is not a component of Frame Header. Rather, it is a component of metadata.

2. The statement

   Metadata Length MUST be equal to the Frame Length minus the sum of the length of the Frame
   Header and the length of the Frame Payload, if present.

   is wrong. It should read

   Metadata Length MUST be equal to the Frame Length minus the sum of the length of the Frame
   Header, the Metadata Optional Header, and the length of the Frame Payload, if present.

A simple fix would be to not mention Metadata Optional Header in the specification of Frame Header at all and state elsewhere that metadata has always to be prepended by a 24 bits metadata length field.