search

braid-org / braid-spec

Working area for Braid extensions to HTTP
https://braid.org
233 stars 16 forks source link

Remove references to unknown / missing "Braid-WebRTC" from http spec #95

Open josephg opened 3 years ago

josephg commented 3 years ago

Spec says:

5.3.  A Serverless Chat Example
...
   Additionally, the Braid protocol can be
   expressed over peer-to-peer transports (e.g. Braid-WebRTC) to support
   a peer-to-peer synchronization without a server.  Braid-HTTP clients
   will be able to interoperate with Braid-WebRTC peers.  For example, a
   chat application might be served and synchronized on Braid-HTTP,
   while also establishing redundant peer-to-peer connections on
   Braid-WebRTC.  The server could then be shut down, and users of the
   chat app could continue to send messages to one another.

Its really jarring mentioning a separate, unspecified protocol (Braid-WebRTC) in this example. This reference is confusing as-is, because people will go looking for that spec!

Either the text should be clear about whats being proposed here. Eg:

  ... Future versions of this protocol may be expressed over
  peer-to-peer transports (e.g. WebRTC) to support synchronization
  without a server.

Or remove / change this example entirely.

toomim commented 3 years ago

Yeah, we've implemented a braid webrtc transport in redwood, but the point of this paragraph isn't to get people using a common webrtc specification, but just to suggest that they could use additional network channels like webrtc as an example.

Would it be better if the text said this:

5.3.  A Serverless Chat Example
...
   Additionally, the Braid protocol can be expressed over peer-to-peer
   transports (e.g. WebRTC) to support a peer-to-peer synchronization
   without a server.  For example, a chat application might be served
   and synchronized on Braid-HTTP, while also establishing redundant
   peer-to-peer connections on WebRTC, and translating all Braid-HTTP
   messages over the WebRTC connections, and vice versa.  The server
   could then be shut down, and users of the chat app could continue to
   send messages to one another.
josephg commented 3 years ago

Thats a bit better, but I think it still doesn't address my main concern. My concern is that the spec doesn't specify how to embed braid in WebRTC, or how to use braid in a P2P context. This example implies that it has.

The question to ask about a good spec is, "with no supplementary material, could I read the spec and know how to write an implementation that can talk to any other implementation". The answer is "no" wrt WebRTC and P2P. (And if we want to describe how to do that, that description shouldn't be described as an example.

This is an island we want to reach, but the spec doesn't build a bridge to that island yet. We should either call that out explicitly ("Future versions of this protocol may...") or remove this text completely.