Document deviations from RFC 8446 PL

[tgeoghegan]

Explains in detail how the syntax from RFC 8446 section 3.7 is repurposed for concise descriptions of structure variants. Additionally, the section on message encoding is moved to "Protocol Definition" to make the document flow better.

Closes #472

[cjpatton]

Reviewer note: @suman-gantaobserved that TLS-syntax does not explicitly allow case blocks with multiple fields. We currently don't have any cases of this.

[suman-ganta]

How do we express multiple selects and their associated qualified members in this notation? (Such case does not exist in DAP so far I think)

[tgeoghegan]

Since this doesn't occur in DAP, I don't think we need to define it. Also, I would push back pretty hard on any struct definition that contained multiple selects. That would almost certainly allow construction of messages that aren't semantically valid, which would force extra validation checks on implementations. I think we would always prefer a struct contain a single enumeration where all its variants are valid over multiple enumerated types.

[suman-ganta]

From, the semantics of variants, it is possible to have several selects in a structure. Since variants allow dynamic members of structure, it sounds like legitimate definition to me. Am I missing anything here? Since we are coming up with a notation that could probably be followed in future DAP specs too, I'm trying to make sure we define something that lasts.

I'm fine if you would like to defer this to later updates.

Overall, In this notation, I didn't see the distinction between representing alwaysExsting fields vs fields added as a result of a specific value of enum. Since the order of fields matter, and these dynamic fields can appear in the middle of two static fields, some visual cue (bold/italicized etc) could help to locate them.

[cjpatton]

Can you give an example of when multiple selects in the same struct is ambiguous?

[wangshan]

@tgeoghegan does this mean the syntax from {{Section 3.7 of !RFC8446}} is forbidden in this doc?
If a structure has the following def:

struct {
   uint32 always_present;
   ExampleEnum type;
}

Then does the below have ambiguity?

struct variant {
   uint32 always_present = 0;
   ExampleEnum type = number;
}

Does it mean always_present can only be a constant 0 or it just happens to be 0 in this variant?

[tgeoghegan]

@tgeoghegan does this mean the syntax from {{Section 3.7 of !RFC8446}} is forbidden in this doc?

I don't think so. By introducing struct variant, we avoid collision with the RFC 8446 s3.7 notation, meaning it can be used without further complications. However, I don't think DAP ever should: TLS 1.3 needs that notation because it wants some its messages to be backward compatible with TLS 1.2. We have no such problem.

If a structure has the following def:

struct {
   uint32 always_present;
   ExampleEnum type;
}

Then does the below have ambiguity?

struct variant {
   uint32 always_present = 0;
   ExampleEnum type = number;
}

Does it mean always_present can only be a constant 0 or it just happens to be 0 in this variant?

I don't think there's ambiguity because using struct variant makes it clear we're not using the notation from RFC 8446 section 3.7.

[wangshan]

I don't think there's ambiguity because using struct variant makes it clear we're not using the notation from RFC 8446 section 3.7.

I see, so it essentially overrides RFC 8446 s3.7. Do you think it's worth calling out this in the example? @tgeoghegan

[tgeoghegan]

It does not override that section of RFC 8446. The notation in 8446 section 3.7 is struct { ... } whatever. The notation we introduce here is struct variant { ... } whatever which does not conflict.

[suman-ganta]

struct variant is kind of indicating it is deviation from struct, but most of the struct semantics apply. variant alone is not defined anywhere, so it would leave every one for wild interpretations.

[cjpatton]

@tgeoghegan please squash and merge at will!