Draft: draft-ietf-taps-interface

Commentary: Now that the document is targeted for the standards track , its purpose ( i.e. what exactly it standardizes , and what it does not ) should be made clear . This is made a little more difficult because , as an abstract API we intend to be implementable in any reasonable language ( i.e. no   ) , Here 's what I think the scope is : message - orientation asynchronicity of event and reception asynchronicity of resolution and initiation the " shape " of the API : objects and events , and interactions between them , with a RECOMMENDATION that you use the same names ( " unless this facility is implemented in terms of a networking interface that already has different names or naming conventions for equivalent objects " or something like that ) . an MTI set of selection , connection , and message properties , and definitions ( though not names ) of these properties . a larger fully defined set of selection , connection , and message properties , such that if a system implements a given property it must implement it as described . 
 Why would we not want to make a recommendation on the names of properties ? We 'll need to name them in the drafts anyway , if we 're to cross - reference them from elsewhere , and at that point there 's no benefit in not recommending re - use of those names in concrete API implementations . 
 I think providing consistent naming across different implementations will be a key argument for the adoption of the abstract interface . The strongest argument for sticking to BSD Sockets is that they somehow look the same on all platforms . We should not miss the change to at least give recommendations about how to name the individual objects and properties . Implementations can and should extend and divert from it where it makes sense , but recommending names should help the individual APIs look at least similar . 
 There are different kinds of things we can recommend names for . objects actions events properties We have pretty good recommendations for the first three ( though different languages have e.g. different capitalization conventions ) . Names of properties are descriptive , though , and would make bad code names , so if we want to do the fourth we have some work to do . What I would propose to do for Bangkok : assume we recommend names for the first three , open an issue for recommended property names ( which is necessary for registry project anyway ) . 
 Looks good ! Just one comment in re - reading a section more carefully , not blocking . I especially like the " Scope of the Interface Definition " text ! Really nice and useful to have IMO
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 callback passing or other asynchronous
calling conventions.  The method for registering callbacks and
handlers 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 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 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):
Atomic transmission of data, using application-assisted framing
and deframing where the underlying transport does not provide
these.
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.  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):
Explicit support for multistreaming and multipath transport
protocols, and the grouping of related Connections into Connection
Groups through cloning of Connections, to allow applications to
take full advantage of new transport protocols supporting these
features.
Paragraph (version B):
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 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 B):
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 B):
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.