Draft: draft-ietf-taps-arch

Commentary: Addresses . Removes most of the normative language in arch , which was n't strictly necessary . What 's left is the careful text around security protocols being raced , etc , which I believe is required . 
 After the review , I would still be in favour of using RFC2119 language to describe what is required architecturally to be a TAPS system . In my review , I agree the number of requirements is now reduced . I really do wonder if we could ( please ) group all these requirements on architecture into a single subsection , so they are easy to read - and we can they say that these are the architectural requirements , explcitly refererence those in section XX relating to racing . I suggest we insert this requirements text either as short text blocks in their own section , or simply a set of bullets in section 1.3 ( although I am open to other places where we can call - out the architectural requirements ) . Perhaps we should also check we still have captured something along the lines of : " The System should permit evolution of the system without affecting programs using it . In normal use , TAPS systems are RECOMMENDED to result in consistent selection for the same network conditions when they have the same set of preferences , but applications using the TAPS API are REQUIRED to be robust to the automated selection , including the possibility to express requirements that constrain the choices that can be made by the system . " And possibly add " Applications using TAPS can explicitly require or prevent the use of specific transport features ( and transport protocols ) using the " REQUIRED " and " PROHIBIT " ... " or something like that . If this seems appropriate to add a section on overall requirements , I would then suggest to use lower case within the document and simply refer to this subsection , where necessary to get the RFC2119 sentences . 
 At some point we normative language to the arch doc but only changed cases where use of upper case keywords are obvious . If we really want to use normative language , we would need another pass and make sure that we identified everything that should be specified normatively . Alternatively , we could just remove any normative language again and revert respective words back to lower case . I think that would be my preferred solution as a ) it is less work and b ) I do n't think this document necessarily needs normative language . 
 Personally , I 'd prefer to keep the language - but I agree we ought to review the items . I 'd really like to use REQUIRED , RECOMMENDED , rather MUST and SHOULD - because these are not protocol operation requirements , but implementation requirements to conform . e.g. : , these properties SHOULD apply to multiple transport protocols . could be . : , it is RECOMMENDED that these properties apply to multiple transport protocols . 
 I think having normative language in there is a good idea because it makes it clearer what criteria we think an implementation has to meet or to give guidance on what to prioritize to implement . In the current draft , there 's two places in which I find the normative language odd and maybe misplaced though : Section 4.1 : " Events MAY also provide opportunities for the application to interact with the underlying transport by querying state or updating maintenance options . " - Maybe this should be rephrased or the MAY removed ? Clearly events are an opportunity to exchange information , which an implementation MAY or may not take . Section 3.2 : " A Transport Services API MUST allow applications to define such requirements and constrain the system 's options . " - This seems to be oddly unspecific for a MUST : There MUST be some way to define some constraints , but what exact constraints is undefined ? Also , this is in addition to minset , and I thought MUST should mostly cover minset to limit scope creep . 
 I agree with bot of those Theresa ! I do n't think we need keywords for either of these clauses . 
 Following our discussion during the interim and having thought about it a bit more , I 'd be okay with not having normative language in the Architecture document , as long as we make sure that it still clearly says what has to be implemented ( i.e. , support for minset ) , and as long as we still clearly warn against unsafe fallback for security protocols and such . But I guess that for me , changing the words to lower case would be enough . However , if we do that ( and maybe even if we do n't ) , we need to make clear that the API document actually contains ALL the normative language we need . For example , I 'm not seeing anything on security protocols fallback in the API document yet . 
 I admit I misunderstood what  's comment was .  was Sorry . - this was the benefit of some discussion . This has made me realise : The edits in Tommy 's   are likely appropriate - the way the text evolved was not useful after all . I will read the whole ID carefully and ... My hope of good requirements requires much more focussed text - I take the opportunity to propose a concise requirements section along the lines of what emerged in the Interim . Coming soon . 
 I 'm merging in advance of the 107 draft deadline . There 's one question as to how hard we should push minset at the arch level , which I think is a point for wider discussion , and a few nits which can be picked up after the draft lands . 
 Proposed new requirements section in arch opened as new issue . If we agree to consider that , this issue can now be closed . 
 is the new issue for this .
Paragraph (version A):
There are key differences between the architecture of the Transport
Services system and the architecture of the Socket API: the Transport
Services API is asynchronous and event-driven; it uses messages for
representing data transfer to applications, and it assumes an
implementation that can use multiple IP addresses, multiple
protocols, multiple paths, and provide multiple application streams.
Paragraph (version B):
There are key differences between the architecture of the Transport
Services system and the architecture of the Socket API: the Transport
Services API is asynchronous and event-driven; it uses messages for
representing data transfer to applications; and it assumes an
implementation that can use multiple IP addresses, multiple
protocols, multiple paths, and provide multiple application streams.
Paragraph (version A):
Functionality that is common across multiple transport protocols
SHOULD be accessible through a unified set of API calls.  An
application ought to be able to implement logic for its basic use of
transport networking (establishing the transport, and sending and
receiving data) once, and expect that implementation to continue to
function as the transports change.
Paragraph (version A):
Any Transport Services API is REQUIRED to allow access to the
distilled minimal set of features offered by transport protocols I-
D.ietf-taps-minset.
Paragraph (version A):
There are applications that will need to control fine-grained details
of transport protocols to optimize their behavior and ensure
compatibility with remote systems.  A Transport Services system
therefore SHOULD also permit more specialized protocol features to be
used.  The interface for these specialized options ought to be
exposed differently from the common options to ensure flexibility.
Paragraph (version B):
Functionality that is common across multiple transport protocols
ought to be accessible through a unified set of API calls.  An
application using a Transport Services API can implement logic for
its basic use of transport networking (establishing the transport,
and sending and receiving data) once, and expect that implementation
to continue to function as the transports change.
Paragraph (version B):
As a baseline, any Transport Services API needs to allow access to
the distilled minimal set of features offered by transport protocols
I-D.ietf-taps-minset.
Paragraph (version B):
There are applications that will need to control fine-grained details
of transport protocols to optimize their behavior and ensure
compatibility with remote systems.  A Transport Services system
therefore ought to also permit more specialized protocol features to
be used.  The interface for these specialized options ought to be
exposed differently from the common options to ensure flexibility.
Paragraph (version A):
Other specialized features, however, could be strictly required by an
application and thus constrain the set of protocols that can be used.
For example, if an application requires support for automatic
handover or failover for a connection, only protocol stacks that
provide this feature are eligible to be used, e.g., protocol stacks
that include a multipath protocol or a protocol that supports
connection migration.  A Transport Services API MUST allow
applications to define such requirements and constrain the system's
options.  Since such options are not part of the core/common
features, it will generally be simple for an application to modify
its set of constraints and change the set of allowable protocol
features without changing the core implementation.
Paragraph (version B):
Other specialized features, however, could be strictly required by an
application and thus constrain the set of protocols that can be used.
For example, if an application requires support for automatic
handover or failover for a connection, only protocol stacks that
provide this feature are eligible to be used, e.g., protocol stacks
that include a multipath protocol or a protocol that supports
connection migration.  A Transport Services API needs to allow
applications to define such requirements and constrain the system's
options.  Since such options are not part of the core/common
features, it will generally be simple for an application to modify
its set of constraints and change the set of allowable protocol
features without changing the core implementation.
Paragraph (version A):
Implementations that provide the Transport Services API I-D.ietf-
taps-impl will vary due to system-specific support and the needs of
the deployment scenario.  It is expected that all implementations of
Transport Services will offer the entire mandatory API.  All
implementations are REQUIRED to offer an API that is sufficient to
use the distilled minimal set of features offered by transport
protocols I-D.ietf-taps-minset, including API support for TCP and UDP
transport.  However, some features provided by this API will not be
functional in certain implementations.  For example, it is possible
that some very constrained devices might not have a full TCP
implementation beneath the API.
Paragraph (version B):
Implementations that provide the Transport Services API I-D.ietf-
taps-impl will vary due to system-specific support and the needs of
the deployment scenario.  It is expected that all implementations of
Transport Services will offer the entire mandatory API.  All
implementations are expected to offer an API that is sufficient to
use the distilled minimal set of features offered by transport
protocols I-D.ietf-taps-minset, including API support for TCP and UDP
transport.  However, some features provided by this API will not be
functional in certain implementations.  For example, it is possible
that some very constrained devices might not have a full TCP
implementation beneath the API.
Paragraph (version A):
To preserve flexibility and compatibility with future protocols, top-
level features in the Transport Services API SHOULD avoid referencing
particular transport protocols.  The mappings of these API features
to specific implementations of each feature is explained in the I-
D.ietf-taps-impl along with the implications of the feature on
existing protocols.  It is expected that I-D.ietf-taps-interface will
be updated and supplemented as new protocols and protocol features
are developed.
Paragraph (version A):
It is important to note that neither the Transport Services API I-
D.ietf-taps-interface nor the Implementation document I-D.ietf-taps-
impl define new protocols or protocol capabilities that affect what
is communicated across the network: this implies that a Transport
Services system MUST be deployable on only one side of a connection.
A Transport Services system acting as a connection initiator can
communicate with any existing system that implements the transport
protocol(s) selected by the Transport Services system.  Similarly, a
Transport Services system acting as a listener can receive
connections for any protocol that is supported by the system from
existing initiators that implement the protocol, independent of
whether the initiator uses Transport Services as well or not.
Paragraph (version B):
To preserve flexibility and compatibility with future protocols, top-
level features in the Transport Services API ought to avoid
referencing particular transport protocols.  The mappings of these
API features to specific implementations of each feature is explained
in the I-D.ietf-taps-impl along with the implications of the feature
on existing protocols.  It is expected that I-D.ietf-taps-interface
will be updated and supplemented as new protocols and protocol
features are developed.
Paragraph (version B):
It is important to note that neither the Transport Services API I-
D.ietf-taps-interface nor the Implementation document I-D.ietf-taps-
impl define new protocols or protocol capabilities that affect what
is communicated across the network.  Use of a Transport Services
system does not require that a peer on the other side of a connection
uses the same API or implementation.  A Transport Services system
acting as a connection initiator can communicate with any existing
system that implements the transport protocol(s) selected by the
Transport Services system.  Similarly, a Transport Services system
acting as a listener can receive connections for any protocol that is
supported by the system from existing initiators that implement the
protocol, independent of whether the initiator uses Transport
Services as well or not.
Paragraph (version A):
Pre-Establishment (preestablishment) encompasses the properties
that an application can pass to describe its intent, requirements,
prohibitions, and preferences for its networking operations.  For
any system that provides generic Transport Services, these
properties SHOULD apply to multiple transport protocols.
Properties specified during Pre-Establishment can have a large
impact on the rest of the interface: they modify how establishment
occurs, they influence the expectations around data transfer, and
they determine the set of events that will be supported.
Paragraph (version B):
Pre-Establishment (preestablishment) encompasses the properties
that an application can pass to describe its intent, requirements,
prohibitions, and preferences for its networking operations.
These properties apply to multiple transport protocols, unless
otherwise specified.  Properties specified during Pre-
Establishment can have a large impact on the rest of the
interface: they modify how establishment occurs, they influence
the expectations around data transfer, and they determine the set
of events that will be supported.
Paragraph (version A):
Event Handling (events) defines categories of notifications which
an application can receive during the lifetime of transport
objects.  Events MAY also provide opportunities for the
application to interact with the underlying transport by querying
state or updating maintenance options.
Paragraph (version B):
Event Handling (events) defines categories of notifications which
an application can receive during the lifetime of transport
objects.  Events also provide opportunities for the application to
interact with the underlying transport by querying state or
updating maintenance options.
Paragraph (version A):
Preconnection: A Preconnection object is a representation of a
potential Connection.  It has state that describes parameters of a
Connection that might exist in the future: the Local Endpoint from
which that Connection will be established, the Remote Endpoint
(preestablishment) to which it will connect, and Transport
Properties that influence the paths and protocols a Connection
will use.  A Preconnection can be fully specified such that it
represents a single possible Connection, or it can be partially
specified such that it represents a family of possible
Connections.  The Local Endpoint (preestablishment) MUST be
specified if the Preconnection is used to Listen for incoming
Connections.  The Local Endpoint is OPTIONAL if it is used to
Initiate Connections.  The Remote Endpoint MUST be specified in
the Preconnection that is used to Initiate Connections.  The
Remote Endpoint is OPTIONAL if it is used to Listen for incoming
Connections.  The Local Endpoint and the Remote Endpoint MUST both
be specified if a peer-to-peer Rendezvous is to occur based on the
Preconnection.
Paragraph (version B):
Preconnection: A Preconnection object is a representation of a
potential Connection.  It has state that describes parameters of a
Connection that might exist in the future: the Local Endpoint from
which that Connection will be established, the Remote Endpoint
(preestablishment) to which it will connect, and Transport
Properties that influence the paths and protocols a Connection
will use.  A Preconnection can be fully specified such that it
represents a single possible Connection, or it can be partially
specified such that it represents a family of possible
Connections.  The Local Endpoint (preestablishment) is required if
the Preconnection is used to Listen for incoming Connections.  The
Local Endpoint is optional if it is used to Initiate Connections.
The Remote Endpoint is required in the Preconnection that is used
to Initiate Connections.  The Remote Endpoint is optional if it is
used to Listen for incoming Connections.  The Local Endpoint and
the Remote Endpoint are both required if a peer-to-peer Rendezvous
is to occur based on the Preconnection.
Paragraph (version A):
Send: The action to transmit a Message over a Connection to the
remote system.  The interface to Send MAY include Message
Properties specific to how the Message content is to be sent.  The
status of the Send operation MUST be delivered back to the sending
application in an event (events).
Paragraph (version A):
Receive: An action that indicates that the application is ready to
asynchronously accept a Message over a Connection from a remote
system, while the Message content itself will be delivered in an
event (events).  The interface to Receive MAY include Message
Properties specific to the Message that is to be delivered to the
application.
Paragraph (version B):
Send: The action to transmit a Message over a Connection to the
remote system.  The interface to Send can accept Message
Properties specific to how the Message content is to be sent.  The
status of the Send operation is delivered back to the sending
application in an event (events).
Paragraph (version B):
Receive: An action that indicates that the application is ready to
asynchronously accept a Message over a Connection from a remote
system, while the Message content itself will be delivered in an
event (events).  The interface to Receive can include Message
Properties specific to the Message that is to be delivered to the
application.
Paragraph (version A):
Connection Closed: Signals to an application that a given
Connection is no longer usable for sending or receiving Messages.
The event SHOULD deliver a reason or error to the application that
describes the nature of the termination.
Paragraph (version A):
Message Received: Delivers received Message content to the
application, based on a Receive action.  This MAY include an error
if the Receive action cannot be satisfied due to the Connection
being closed.
Paragraph (version B):
Connection Closed: Signals to an application that a given
Connection is no longer usable for sending or receiving Messages.
The event delivers a reason or error to the application that
describes the nature of the termination.
Paragraph (version B):
Message Received: Delivers received Message content to the
application, based on a Receive action.  This can include an error
if the Receive action cannot be satisfied due to the Connection
being closed.
Paragraph (version A):
The Transport Services API SHOULD allow applications to explicitly
define Connection Groups that force separation of Cached State and
Protocol Stacks.  For example, a web browser application might use
Connection Groups with separate caches for different tabs in the
browser to decrease linkability.
Paragraph (version A):
The interface to specify a Connection Group MAY expose fine-grained
tuning for which properties and cached state is allowed to be shared
with other Connections.  For example, an application might want to
allow sharing TCP Fast Open cookies across groups, but not TLS
session state.
Paragraph (version B):
The Transport Services API can allow applications to explicitly
define Connection Groups that force separation of Cached State and
Protocol Stacks.  For example, a web browser application might use
Connection Groups with separate caches for different tabs in the
browser to decrease linkability.
Paragraph (version B):
The interface to specify a Connection Group can expose fine-grained
tuning for which properties and cached state is allowed to be shared
with other Connections.  For example, an application might want to
allow sharing TCP Fast Open cookies across groups, but not TLS
session state.