Subject: [Taps] draft-ietf-taps-interface-05 review

From: Kyle Rose <[email-masked]>
Date: Thu, 23 Jan 2020 20:24:24 -0500

I've completed my review of draft-05, inline below. I will also submit a PR
with minor changes that I recommend be addressed via cherry-picking
agreed-upon hunks from the diff.

2. Terminology and Notation

 * "The method for
   dispatching and handling Events is an implementation detail, with the
   caveat that the interface for receiving Messages must require the
   application to invoke the Connection.Receive() Action once per
   Message to be received (see Section 8)."

This isn't true if ReceivedPartial events are triggered, right? Also, it's
not really clear that any of this discussion belongs in a section titled
"Terminology and Notation". This issue is alluded to later in the doc, and
probably mostly belongs in the implementation doc.

 * The notation "Sender -> Event" says nothing about who receives the
event. Is it just assumed to be the application in the context of the
particular event (e.g., a thread processing a particular connection)?

3. Interface Design Principles

 * What does "long-term caching of cryptographic identities" mean? The
implication seems to be that credentials and transport security parameters
can be configured once and used repeatedly. I'm not sure time interval
("long-term") is the right modifier here, and the word "caching" might be
misunderstood as it means something subtly different in the realm of
computer hardware and software than the dictionary definition implies.
Maybe something like:

   "...and for configuration of cryptographic identities and transport
security parameters persistent across multiple Connections"

 * "An application primarily interacts with this interface..." This seems
awkward. An interface is the means by which an application interacts with
the underlying transports.

4.2.1. Transport Property Names

 * The use of dashes in property names means they will necessarily look
different in almost every widely-used language, in which dash is an
operator.

 * If we're not currently asking IANA to create a registry of property
names or namespaces, should we provide a recommendation that such symbols
not listed explcitly in this document be prefixed with some experimental
identifier?

4.3. Scope of the Interface Definition

 * "Implementations of this interface SHOULD implement each Selection
      Property, Connection Property, and Message Context Property
      specified in this document, exclusive of appendices.  Each
      interface SHOULD be implemented even when this will always result
      in no operation, e.g. there is no action when the API specifies a
      Property that is not available in a transport protocol implemented
      on a specific platform."

This seems like it implies that a property that is unavailable should
silently fail to be activated, which conflicts with the "Require"
preference referenced later. There may be some way to reword this to be
clear that it's referring to implementing all of the properties in the API
so that compile-time or runtime errors don't spuriously occur when some
symbol hasn't been defined.

Also: why "exclusive of appendices"?

5.2. Specifying Transport Properties

 * There are a lot of choices being made about how users will want to
prioritize transport protocol selection. How confident are we that, for
instance, path selection should take priority over protocol selection? I
think that's right, but I wonder if it might not make more sense to have
two interfaces: one that provides a purely numeric priority ordering of
preferences, and one (based on the existing 5-level preferences) that maps
into it.

 * "As preference typed selection properties..." I can't parse this.

 * Using the same enum (Require(d[sic])/Avoid/Ignore) for the queried
output of selected properties seems like a shortcut that will lead to some
confusion.

5.2.5. Use 0-RTT Session Establishment with an Idempotent Message

 * I'll repeat the same statement I made at the mic a few years ago:
idempotency != replay-safe. DELETE is idempotent, but not safe for replay
because someone might have done a PUT or POST in the meantime.

5.2.10. Interface Instance or Type

 * These type symbols really deserve an actual registry, or at least the
start of one. Otherwise, we are likely to end up with a mess.

5.2.11. Provisioning Domain Instance or Type

 * What about ordering of similar interfaces? I have a 2-SIM cellphone with
wifi.

5.3.2. Connection Establishment Callbacks

 * What constitutes trust verification prior to the handshake?

6.4. Connection Groups

 * "An ideal transport system" for whom? The capacity partitioning
recommended here seems purely subjective. I'd just remove it.

7.3.1. Sent

 * It seems like an abstract API would be helpful for the reference to the
Message to which a Sent event applies: this seems like something many, many
applications would need to do. With callbacks, the application can always
curry in a reference to the original message (that's what my event system
from ~2001 did), so maybe that should be the recommendation and the message
reference removed...? I don't have a strong feeling here other than that if
something is included then its use should be more well-defined.

7.3.3. SendError

 * Is there a reason why a single messageContext object is used for both
sends and receives? I probably missed the original discussion about this,
but I'd like to understand the reasoning.

7.4.7. Reliable Data Transfer (Message)

 * The default isn't "true", it's whatever the underlying connection had,
right?

7.4.9. Singular Transmission

 * Might be worth pointing out there's no guarantee here, either,
considering resegmenting TCP middleboxes.

8. Receiving Data

 * A connection can be used to receive data if it is not configured as
unidirectional transmit.

8.2. Receive Events

 * "A call to Receive will be paired with a single Receive Event" or
possibly multiple ReceivedPartial Events?

 * Also, can the draft be consistent about Receive vs. Received, et al.?

9. Message Contexts

 * "To get or set Message Properties, the optional scope parameter is
   left empty, for framing meta-data, the framer is passed." I can't parse
this.

11. General comments

 * There's a lot of UNIXisms here that should probably be excised in favor
of a more abstract presentation. The most obvious is the use of -1 to mean
something other than the integer -1. In Python, for instance, you might
want to use None for this purpose. I would specify non-numeric values
symbolically, and maybe indicate in the appendix that a UNIX C
implementation might want to use -1 to represent such values.

11.1.3. Priority (Connection)

 * I'm not sure what "relative inverse priority" means. Is P1 higher
priority than P5, and therefore lower inverse priority than P5? Or the
other way around?

11.1.10. Capacity Profile

 * Very little of this section is about capacity. Traffic Profile?

 * "High Throughput Data" might be better phrased as "Capacity-Seeking".

11.2. Soft Errors

 * Should the SoftError Event carry some information about e.g. the ICMP
message received?