Draft: draft-ietf-taps-interface

Commentary: This handles all of  's editorial comments in , save which should be discussed in a new issue . 
 unaddressed comment in 
 I think that this is ready to be merged , but requires merging by someone who 's less prone than me to mess something up when pressing the " Resolve conflicts " button . Please ? 
 The TAPS architecture uses Events for all asynchronous happenings , except the trust and challenge callbacks . I think this is the right way to do things but I 'm not sure because the callbacks are slightly underspecified at the moment -- callbacks are distinct from events because events are fire - and - forget from the TAPS system 's PoV , while callbacks might fail ( and the system and transport stacks react to that failure ) . This raises a few questions : we more explicitly specify callbacks in § 5.3.2 ? ( I think yes ) we add the concept of callbacks to the architecture ? ( I 'm not sure , maybe ? ) we generalize events instead to allow them to have a boolean return ? ( I think no ) 
 I think it is a good idea to keep them separate and specifying them more explicitly . We should also give the documents a pass with that differentiation in mind , for example in Sec . 2 of the API it says that callbacks are a possible way to implement events . 
 , we should specify callbacks in the API document , I do n't think the architecture needs a formal callback definition specifically BUT it should be updated to remove callbacks from the list of events , and just say that the API lets the application know when certain actions are completed . ' m not clear on the boolean return here ... in general , I do n't think the events need to be generalized ? 
 " boolean return " in terms of allowing the application to signal back that an event was not / could not be handled ( which is the reason callbacks are separate ) . 
 As we were very successful in normalising concepts and avoiding to add similar but slightly different things , I strongly prefer " events " over " events+callbacks " . Instead of a boolean return , I prefer either saying these events may use a specific abort mechanism or need to acknowledge the passed values ( and leave it to the implementation whether acknowledge means retuning a boolean , calling a function , writing to a channel or not throwing an exception ) . 
 A related note on section 5.2.13 ( direction of communication ): The descriptions for unidirectional send and receive in section 5.2 seem to leave open the possibility of bidirectional behavior , but in section 11 ( Managing Connections ) it 's an error condition if performing the unsupported operation . Current : " Unidirectional send : The connection must support sending data " Suggested : " Unidirectional send : The connection must support sending data , and the application can not use the connection to receive any data " ( and similar for unidirectional receive ) 
 Looks good !
Paragraph (version A):
The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing
network sockets into the UNIX programming model, allowing anyone who
knew how to write programs that dealt with sequential-access files to
also write network applications, was a revolution in simplicity.  The
simplicity of this API is a key reason the Internet won the protocol
wars of the 1980s.  SOCK_STREAM is tied to the Transmission Control
Protocol (TCP), specified in 1981 RFC0793.  TCP has scaled remarkably
well over the past three and a half decades, but its total ubiquity
has hidden an uncomfortable fact: the network is not really a file,
and stream abstractions are too simplistic for many modern
application programming models.
Paragraph (version B):
The BSD Unix Sockets API's SOCK_STREAM abstraction, by bringing
network sockets into the UNIX programming model, allowing anyone who
knew how to write programs that dealt with sequential-access files to
also write network applications, was a revolution in simplicity.  The
simplicity of this API is a key reason the Internet won the protocol
wars PROTOCOL-WARS of the 1980s.  SOCK_STREAM is tied to the
Transmission Control Protocol (TCP), specified in 1981 RFC0793.  TCP
has scaled remarkably well over the past three and a half decades,
but its total ubiquity has hidden an uncomfortable fact: the network
is not really a file, and stream abstractions are too simplistic for
many modern application programming models.
Paragraph (version A):
As a first step to realizing this design, I-D.ietf-taps-arch
describes a high-level architecture for transport services.  This
document builds a modern abstract programming interface atop this
architecture, deriving specific path and protocol selection
properties and supported transport features from the analysis
provided in RFC8095, I-D.ietf-taps-minset, and I-D.ietf-taps-
transport-security.
Paragraph (version B):
This document builds a modern abstract programming interface atop the
high-level architecture for transport services defined in I-D.ietf-
taps-arch.  It derives specific path and protocol selection
properties and supported transport features from the analysis
provided in RFC8095, I-D.ietf-taps-minset, and I-D.ietf-taps-
transport-security.
Paragraph (version A):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callbacks, communicating sequential
processes, or other asynchronous calling conventions.  The method for
dispatching and handling Events is left as 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 receiving).
Paragraph (version A):
This specification treats Events and errors similarly.  Errors, just
as any other Events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return errors immediately, according to the error
handling idioms of the implementation platform, for errors which can
be immediately detected, such as inconsistency in Transport
Properties.
Paragraph (version B):
How these abstract concepts map into concrete implementations of this
API in a given language on a given platform is largely dependent on
the features of the language and the platform.  Actions could be
implemented as functions or method calls, for instance, and Events
could be implemented via callbacks, communicating sequential
processes, or other asynchronous calling conventions.  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 receiving).
Paragraph (version B):
This specification treats Events and errors similarly.  Errors, just
as any other Events, may occur asynchronously in network
applications.  However, it is recommended that implementations of
this interface also return errors immediately, according to the error
handling idioms of the implementation platform, for errors that can
be immediately detected, such as inconsistency in Transport
Properties.
Paragraph (version A):
The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services
Architecture defined in I-D.ietf-taps-arch.
Paragraph (version A):
An application primarily interacts with this interface through two
Objects, Preconnections and Connections.  A Preconnection represents
a set of properties and constraints on the selection and
configuration of paths and protocols to establish a Connection with a
remote endpoint.  A Connection represents a transport Protocol Stack
on which data can be sent to and/or received from a remote endpoint
(i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional).  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e.  peer to peer
establishment).
Paragraph (version B):
The Transport Services Interface is the basic common abstract
application programming interface to the Transport Services
Architecture defined in the TAPS Architecture I-D.ietf-taps-arch.
Paragraph (version B):
An application primarily interacts with this interface through two
Objects: Preconnections and Connections.  A Preconnection represents
a set of properties and constraints on the selection and
configuration of paths and protocols to establish a Connection with a
remote Endpoint.  A Connection represents a transport Protocol Stack
on which data can be sent to and/or received from a remote Endpoint
(i.e., depending on the kind of transport, connections can be bi-
directional or unidirectional).  Connections can be created from
Preconnections in three ways: by initiating the Preconnection (i.e.,
actively opening, as in a client), through listening on the
Preconnection (i.e., passively opening, as in a server), or
rendezvousing on the Preconnection (i.e.  peer to peer
establishment).
Paragraph (version A):
The examples in this section presume that a transport protocol is
available between the endpoints which provides Reliable Data
Transfer, Preservation of data ordering, and Preservation of Message
Boundaries.  In this case, the application can choose to receive only
complete messages.
Paragraph (version A):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol which provides
a reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(receive-framing).
Paragraph (version B):
The examples in this section presume that a transport protocol is
available between the endpoints that provides Reliable Data Transfer,
Preservation of data ordering, and Preservation of Message
Boundaries.  In this case, the application can choose to receive only
complete messages.
Paragraph (version B):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(receive-framing).
Paragraph (version A):
Each application using the Transport Services Interface declares its
preferences for how the transport service should operate using
properties at each stage of the lifetime of a connection.  During
pre-establishment, Selection Properties (see selection-props) are
used to specify which paths and protocol stacks can be used and are
preferred by the application, and Connection Properties (see
connection-props) can be used to influence decisions made during
establishment and to fine-tune the eventually established connection.
These Connection Properties can also be used later, to monitor and
fine-tune established connections.  The behavior of the selected
protocol stack(s) when sending Messages is controlled by Message
Properties (see message-props).
Paragraph (version A):
Note that Configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later.  Connection
Properties specified early on may be used as additional input to the
selection process.  Also note that Protocol Specific Properties, see
property-names, should not be used as an input to the selection
process.
Paragraph (version B):
Each application using the Transport Services Interface declares its
preferences for how the transport service should operate using
properties at each stage of the lifetime of a connection using
Transport Properties, as defined in I-D.ietf-taps-arch.
Paragraph (version B):
Transport Properties are divided into Selection, Connection, and
Message Properties.  During pre-establishment, Selection Properties
(see selection-props) are used to specify which paths and protocol
stacks can be used and are preferred by the application, and
Connection Properties (see connection-props) can be used to influence
decisions made during establishment and to fine-tune the eventually
established connection.  These Connection Properties can also be used
later, to monitor and fine-tune established connections.  The
behavior of the selected protocol stack(s) when sending Messages is
controlled by Message Properties (see message-props).
Paragraph (version B):
Note that Configuring Connection Properties and Message Properties on
Preconnections is preferred over setting them later.  Early
specification of Connection Properties allows their use as additional
input to the selection process.  Protocol Specific Properties, see
property-names, should not be used as an input to the selection
process.
Paragraph (version A):
The Namespace part is empty for well known, generic properties,
i.e., for properties defined by an RFC which are not protocol
specific.
Paragraph (version B):
The Namespace part is empty for well known, generic properties,
i.e., for properties that are not specific to a protocol and are
defined in an RFC.
Paragraph (version A):
Actions, Events, and Errors in implementations of this interface
SHOULD carry the names given for them in the document, subject to
capitalization and punctuation conventions in the language of the
implementation, unless the implementation itself uses different
names for substantially equivalent objects for networking by
convention.
Paragraph (version A):
Implementations of this interface SHOULD implement each Selection
Property, Connection Property, and Message Context Property
specified in this document, exclusive of appendices, even if said
implementation is a non-operation, e.g.  because transport
protocols implementing a given Property are not available on the
platform.
Paragraph (version A):
Implementations may use other representations for Transport
Property Names, e.g., by providing constants or static singleton
objects, but should provide a straight-forward mapping between
their representation and the property names specified here.
Paragraph (version B):
This document defines a language- and platform-independent interface
to a Transport Services system.  Given the wide variety of languages
and language conventions used to write applications that use the
transport layer to connect to other applications over the Internet,
this independence makes this interface necessarily abstract.
Paragraph (version B):
There is no interoperability benefit in tightly defining how the
interface is presented to application programmers across diverse
platforms.  However, maintaining the "shape" of the abstract
interface across these platforms reduces the effort for programmers
who learn the transport services interface to then apply their
knowledge across multiple platforms.
Paragraph (version B):
Actions, Events, and Errors in implementations of this interface
SHOULD use the names given for them in the document, subject to
capitalization, punctuation, and other typographic conventions in
the language of the implementation, unless the implementation
itself uses different names for substantially equivalent objects
for networking by convention.
Paragraph (version B):
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.
Paragraph (version B):
Implementations may use other representations for Transport
Property Names, e.g., by providing constants, but should provide a
straight-forward mapping between their representation and the
property names specified here.
Paragraph (version A):
Internally, the transport system will first exclude all protocols and
paths that match a Prohibit, then exclude all protocols and paths
that do not match a Require, then sort candidates according to
Preferred properties, and then use Avoided properties as a
tiebreaker.  Selection Properties which select paths take preference
over those which select protocols.  For example, if an application
indicates a preference for a specific path by specifying an
interface, but also a preference for a protocol not available on this
path, the transport system will try the path first, ignoring the
preference.
Paragraph (version B):
Internally, the transport system will first exclude all protocols and
paths that match a Prohibit, then exclude all protocols and paths
that do not match a Require, then sort candidates according to
Preferred properties, and then use Avoided properties as a
tiebreaker.  Selection Properties that select paths take preference
over those that select protocols.  For example, if an application
indicates a preference for a specific path by specifying an
interface, but also a preference for a protocol not available on this
path, the transport system will try the path first, ignoring the
preference.
Paragraph (version A):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
The default is to Require that the Connection is congestion
controlled.
Paragraph (version B):
This property specifies whether the application would like the
Connection to be congestion controlled or not.  Note that if a
Connection is not congestion controlled, an application using such a
Connection should itself perform congestion control in accordance
with RFC2914.  Also note that reliability is usually combined with
congestion control in protocol implementations, rendering "reliable
but not congestion controlled" a request that is unlikely to succeed.
The recommended default is to Require that the Connection is
congestion controlled.
Paragraph (version A):
This property allows the application to select which specific network
interfaces or categories of interfaces it wants to "Require",
"Prohibit", "Prefer", or "Avoid".
Paragraph (version B):
This property allows the application to select which specific network
interfaces or categories of interfaces it wants to "Require",
"Prohibit", "Prefer", or "Avoid".  Note that marking a specific
interface as "Required" strictly limits path selection to a single
interface, and may often lead to less flexible and resilient
connection establishment.
Paragraph (version A):
Note that marking a specific interface as "Required" strictly limits
path selection to a single interface, and leads to less flexible and
resilient connection establishment.
Paragraph (version A):
The set of valid interface types is implementation- and system-
specific.  For example, on a mobile device, there may be "Wi-Fi" and
"Cellular" interface types available; whereas on a desktop computer,
there may be "Wi-Fi" and "Wired Ethernet" interface types available.
Implementations should provide all types that are supported on some
system to all systems, in order to allow applications to write
generic code.  For example, if a single implementation is used on
both mobile devices and desktop devices, it should define the
"Cellular" interface type for both systems, since an application may
want to always "Prohibit Cellular".  Note that marking a specific
interface type as "Required" limits path selection to a small set of
interfaces, and leads to less flexible and resilient connection
establishment.
Paragraph (version B):
The set of valid interface types is implementation- and system-
specific.  For example, on a mobile device, there may be "Wi-Fi" and
"Cellular" interface types available; whereas on a desktop computer,
there may be "Wi-Fi" and "Wired Ethernet" interface types available.
An implementation should provide all types that are supported on the
local system to all remote systems, to allow applications to be
written generically.  For example, if a single implementation is used
on both mobile devices and desktop devices, it should define the
"Cellular" interface type for both systems, since an application may
want to always "Prohibit Cellular".  Note that marking a specific
interface type as "Required" limits path selection to a small set of
interfaces, and leads to less flexible and resilient connection
establishment.
Paragraph (version A):
This property specifies whether an application considers it useful to
transfer data across multiple paths between the same end hosts.
Generally, in most cases, this will improve performance (e.g.,
achieve greater throughput).  One possible side-effect is increased
jitter, which may be problematic for delay-sensitive applications.
The default is to Prefer this option.
Paragraph (version B):
This property specifies whether an application considers it useful to
transfer data across multiple paths between the same end hosts.
Generally, in most cases, this will improve performance (e.g.,
achieve greater throughput).  One possible side-effect is increased
jitter, which may be problematic for delay-sensitive applications.
The recommended default is to Ignore this option.
Paragraph (version A):
In case a unidirectional connection is requested, but unidirectional
connections are not supported by the transport protocol, the system
should fall back to bidirectional transport.
Paragraph (version B):
The default is bidirectional.  Since unidirectional communication can
be supported by transports offering bidirectional communication,
specifying unidirectional communication may cause a transport stack
that supports bidirectional communication to be selected.
Paragraph (version A):
Transport Properties: Transport Properties can be specified as
part of a Preconnection to allow the application to configure
the Transport System and express their requirements,
prohibitions, and preferences.  There are three kinds of
Transport Properties: Selection Properties (preestablishment),
Connection Properties (preestablishment), and Message
Properties (datatransfer).  Message Properties can also be
specified during data transfer to affect specific Messages.
Paragraph (version B):
and Message Properties (datatransfer); note that Message
Properties can also be specified during data transfer to affect
specific Messages.