Specification is missing normative content

[domenic]

The specification right now contains:

• IDL
• A few non-normative summaries of method names (e.g. "openTCPSocket is used to open a client TCP socket.") and dictionary members (e.g. "The port that the socket should be bound to. When omitted, or 0, any port can be used.")
• One "SHOULD NOT" normative requirement: "User agents that do not support direct sockets SHOULD NOT expose openTCPSocket() or openUDPSocket() on the Navigator interface." which is kind of strange because (a) in general if a user agent doesn't implement a spec, it won't implement the IDL portions of a spec either, so we don't bother stating that; (b) this is only a SHOULD NOT, not a MUST NOT, which is quite unusual.

To write a full specification, you'll need normative algorithm steps, paralleling implementation code, for all public APIs.

A good example of this for a streams-based spec is https://wicg.github.io/serial/. Notable places:

• The requestPort() method shows how to normatively specify methods steps, including the processing of dictionary members, checking for transient activation, checking for permissions policy, etc.

• The readable getter steps show how to lazily construct a ReadableStream instance, with the appropriate pullAlgorithm and cancelAlgorithm. You might not want to do this lazily, but the stream construction example there is the right amount of detail.

  Note how it's very precise about error conditions, task queuing, state management, etc. But it's appropriately vague about the actual getting-bytes parts, saying "Invoke the operating system to read up to desiredSize bytes from the port, putting the result in the byte sequence bytes." I.e. you don't need to explain to people how to use OS TCP libraries.

• Similarly the writable getter steps for the WritableStream construction.