Comments on -arch

[csperkins]

Apologies for not organising these better -- this train journey is too short to subdivide before I arrive.

• §1, 1st para: "imitated being the BSD socket() [POSIX] interface." ->
  "imitated being the Berkeley sockets interface [POSIX]"
• §2.1, 1st para: discussion of async uses of sockets, immediately after
  saying sockets provide a blocking sycnhronous interface, confuses. It
  should maybe say "When emulating an asynchronous interface using
  sockets..." rather than "Wehn sockets are presented as an asynchronous
  interface..."?
• §2.1, 4th para: "Using asynchronous events allows for a much simpler
  interaction model when establishing connections and transferring data".
  This depends on the programming language, surely? For simple cases, if
  you don't care about performance and advanced features, the synchronous
  model is easier to use. Maybe "...a more natural interaction model" since
  it better reflects the underlying behaviour?
• §2.2, 2nd para: "Messages seamlessly work with transport protocols
  that support datagrams or records, but can also be used over a stream
  by defining an application-layer framer". This make it seem like each
  application needs to define its own framers when using the TAPS, but
  I'd expect most framers to be introduced implicitly by the stack and
  it to be unusual for them to be provided by the application. That is,
  the applications says "I want an HTTP connection" and the stack then
  implicitly figures out HTTP/2-TLS-TCP vs HTTP/3-QUIC and inserts the
  appropriate framers itself.
• §3.2, 2nd para: "if the API allows an application to specify a preference
  for constrained checksum usage, communication would not fail when a
  protocol such as TCP is selected, which uses a checksum covering the
  entire payload" - what's a constrained checksum? Does this mean partial
  checksums over only part of the packet?
• Figure 4: should this also show send calls, receive events, Messages,
  and other events in Established? I understand that it's just showing
  lifetime related events, but it seems incomplete because of that, and
  the later sections introduce objects not shown in the diagram.
• §4.1.1: rename the subsection to "Connection-related Objects" since
  it's broader than just Connection?
• §4.1.1: Can Connection Properties be specified on a Preconnection? Can
  Message Properties be specified on a Preconnection or Connection, or only
  on Messages?
• §4.1.1 specifies that a Listener is creared from a Preconnection, but
  doesn't say that a Connection is created from a Preconneciton or a
  Listener. Should it?
• §4.1.2: "An Endpoint can be specified at various levels" - what's a level
  here?
• §4.1.2, 1st bullet: "with wider scope (such as a hostname)" -- a hostname
  doesn't necessarily have wider scope than an IP address. It might be more
  abstract.
• §4.1.2 Selection Properties: "a Wi-Fi Ethernet connection"?
• §4.1.2 Connection Properties: "Connection Properties SHOULD be specified
  on a Preconnection prior to Connection establishment, but MAY be modified
  later" -- modified on the Preconnection later, or modified on the
  Connection object after it's been established?
• §4.1.2 Connection Properties: "Such changes do not affect protocol or path
  selection, but only modify the manner in which a connection sends and
  receives data" -- might this cause the connection to select a different
  path? I can imagine setting certain properties might make certain paths
  unviable in a way that the transport could detect.
• §4.1.3 Initiate: "for other protocols, this will just establish local
  state" - it might be worth giving an example here, since otherwise it
  could be interpreted as being like a Listen, or saying "for
  connectionless protocols..."?
• §4.1.3 Listen: "The action of marking a Listener as willing to accept
  incoming Connections" -- phrasing is cumbersome, maybe just "Enables
  a Listener to accept incoming Connections"?
• §4.1.3 Listen: "Listeners by default register with multiple paths,
  protocols, and local endpoints, unless constrained by Selection
  Properties" -- doesn't this depend on the Local Endpoint too?
• §4.1.3 Rendezvous: TCP simultaneous open is one type of rendezvous,
  but only giving this as an example makes it seems more narrowly
  scoped that I envisaged. For example, I'd expect Rendezvous could
  perform an ICE exchange it STUN candidates were passed as Remote
  Endpoints. Should this description be generalised?
• §4.1.4 Message: "Boundaries of a Message might or might not be understood
  or transmitted by transport protocols. Specifically, what one application
  considers to be multiple Messages sent on a stream-based transport can be
  treated as a single Message by the application on the other side, and
  vice versa." -- I'm unconvinced by this. A stream protocol, such as TCP,
  doesn't send arbitrary messages, it sends messages framed by some higher
  layer protocol. The endpoints need to agree on that protocol, and hence
  on the meaning and boundaries of the messages, if communication is to
  proceed.
• §4.1.4 Message Properties: The initial sentence ("Message Properties can
  be used to annotate specific Messages") can be read as this is the only
  way to set properties; the later text that "Message Properties MAY be set
  on a Preconnection" then surprises. Maybe combine these and restructure:
  "Message Properties can be used to annotate specific Messages or can be
  set on a Preconnection [or Connection?] to specify defaults for future
  messages. Message Properites might apply to how a Message is sent...
  When recieving Messages..."
• §4.1.4 Send: What's a "partial Message"? The previous text has spoken
  only in terms of Messages, and has not hinted that partial messages can
  be sent. Need prior introduction, if we're to allow this. It's not clear
  that the architecture needs the concept of partial messages; are there
  examples of protocols that send partial messages, rather than messages
  of unknown size that are fragmented by the framer?
• §4.1.5: "This list is not exhaustive" -- that the list of events is not
  exhaustive makes sense, but surely we should be able to provide a list
  of categories of events?
  Error events are missing; are there more?
• §4.1.6 Close: The way this is written suggests that the API doesn't
  support half closed connections. That may be reasonable, but it's a
  limitation. If intended, can it be made explicit.
• §4.1.6 is the only semantic difference between Close and Abort that
  one attempts to deliver outstanding data and the other doesn't? It
  seems unusual that there's no implication that Close is successful
  and Abort is a failure action.
• §4.2.1 Path Selection: do the Selection Properties include multiple
  Local Endpoints and Remote Endpoints? Or is a Preconnection supplied
  with a set of Local and Remote Endpoints along with some Selection
  Properties? Is Candidate Gathering itself not an operation to be
  performed by the implementation before a Rendezvous can be performed?
• §4.2.2 Candidate Racing: The term "racing" implies that candidates
  are tried simultaneously to see which succeeds first. That's true
  in some cases, but others probe candidates in a defined order.
  Should this be phrased as "Candidate Selection and/or Racing"?
• §4.2.4, 1st para: what's a "process" in this context? The term has not
  been introduced previously.