On 17/09/2021 21:55, Robert Sparks via Datatracker wrote:
Reviewer: Robert Sparks
Review result: Not Ready
This is an art-art early review of draft-ietf-taps-architecture
My first observation and request is that the group rethink the separation of
the architecture and interface documents. It is a warning-sign that the
interface document is a normative reference for the architecture document. As
the documents are currently constructed, a new reader cannot grasp the
architecture without inferring some of it through reading the interface.
Consider reformulating the architecture document as an overview - introduce
principles, concepts, and terminology, but don't attempt to be normative.
(There are signs that this may already be, or have been, a path the document
was being pushed towards). If nothing else, rename it, and acknowledge that the
actual architecture is specified using the interface definition.
Note that the first sentence of the Overview in the interface document also
highlights the current structural problem.
In this and the interface document, there is an inconsistent use of
capitalization to try to make Very Important Concepts visually distinctive.
Please reconsider this mechanic. If you keep it, use it consistently.
The document currently says (just before section 3.1) "The rest of this
document describes the architecture non-normatively", but then goes on to use a
bunch of 2119/8174 language (much of which really shouldn't be - please try
eliminating all of them).
Describe what you mean by racing earlier in the document - the use in the
Introduction is bare.
Describe what you mean by caching and why you might want to isolate sessions
earlier.
Describe what you mean by cloning earlier.
Consider an explicit discussion of multicast/anycast considerations in _this_
document.
The last bullet in the Overview is out of place - the others are an overview of
the document, but this one is a description of a concept.
In section 2.1 "its call to read will not complete immediately" is easy to
misread. The call to read does in fact return immediately. Any read data is
returned asyncronously. Please rework this sentence.
Make it clearer in 3.1 that you are introducing a concept named Properties. A
sentence that starts "Properties are" would really help.
In 3.1 consider "It is important for applications using a Transport Services
system to be robust to the" instead of using REQUIRED.
At 3.2, if this were a requirements document for the Transport Services system,
the SHOULD in the first paragraph might make sense. But if its an architecture
document, or better, an overview and introduction. It would be better to simply
say "is" rather than SHOULD. (And in a requirements document, I would argue
that this SHOULD should be a MUST).
In 3.3, you are talking about racing before you've described what it is. At the
point where you note that racing should only happen over stacks with identical
security properties, note when doing so might introduce privacy issues and what
can be done about them.
The big paragraph that is the first bullet of section 4.1.2 doesn't read well.
Pleas consider restructuring it, and simplifying the sentences as much as
possible.
At 4.1.7, be clearer than "without cleaning up state".
I added this as a set of issues in github, where we can also discuss
whether/how to resolve these:
https://github.com/ietf-tapswg/api-drafts/issues
Gorry
_______________________________________________
Taps mailing list
Taps@ietf.org
https://www.ietf.org/mailman/listinfo/taps
