Articulate the general form of Updates

[toomim]

In https://github.com/braid-org/braid-spec/issues/96 we realized that the Braid-HTTP illustrates a range of ways to express Updates (aka "New Version" messages), but doesn't fully articulate the general form. This results in a lot of confusing ambiguity about what the spec allows.

I propose writing up a general form for Updates:

• Equivalence between a GET response, and PUT request, PATCH request, or POST request
  • All of these forms express an "update", either from server to client, or client to server
  • GET and PUT use Patch-Type where PATCH uses Content-Type
  • TBD: What shall we say about POST? Is there a recommended use for POST with Braid-HTTP?
• Equivalence between regular regular HTTP update and Patches: 1
  • Patches: N is optional extension for all updates, and defines a "second level" of framing within an update
  • If you have only one patch, you can eliminate that extra framing, and merges the patch headers with normal update headers. This is equivalent to the update format of an existing HTTP message, like a Partial PUT.
• Guidance to ensure that Braid PUTs to legacy servers (that don't understand them) don't clobber state.
  • See https://github.com/braid-org/braid-spec/issues/117 for discussion of what to include here.

This should satisfy the questions raised in issue #96, and ensure we have symmetry across range requests and responses in the design under consideration in https://github.com/braid-org/braid-spec/issues/97#issuecomment-1684888647.

Finally, once we articulate the general space of possible updates, we also noted in https://github.com/braid-org/braid-spec/issues/96#issuecomment-786359966 that we might want to impose some constraints on this general form in practice, so we should deliberate what those might be, and articulate any that we want to impose.

Open Questions:

1. What is there to say about POST? Do we see a use for POST in Braid-HTTP? Do users of POST need to know anything special when using it with Braid?
2. Do we want any constraints on this general space of updates, like requiring Patches: 1 in subscription responses as mentioned in issue 97, that might simplify implementations?
3. What do we think about https://github.com/braid-org/braid-spec/issues/117?

[toomim]

For Question 2, I'm copying the pros/cons of "Requiring Patches: 1 in Subscription Responses" from #96 here:

• In requests, Patches: N is already optional because of the existing semantics of HTTP's PATCH method
• In responses, Patches: 1 is optional but this is ambiguous in the spec at the moment we're not sure if it should be required or not

The remainder of work to decide on in this issue is whether patches: 1 is mandatory in subscriptions when a transaction contains 1 patch.

For / against:

• Make patches: 1 in subscription responses optional:
  • In some systems sending multiple patches within a transaction is invalid so they wouldn't need to implement parsing for that header
  • The network protocol is simpler and smaller (1 less header)
  • This is symmetric with the logic for PATCH requests
• Or make patches: X in subscription responses mandatory, even when only one patch is being sent
  • As Mike said, the logic for this will generally be needed anyway
  • And if that logic is implemented, requiring it will make the parser a bit simpler (since there aren't multiple modes or anything like that)