Draft: draft-ietf-taps-interface

Commentary: Here 's the list of comments that this resolves , along with answers on how I did it : 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 is n'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 . MW : Agreed , removed this sentence . 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 : " for configuration of cryptographic identities and transport security parameters persistent across multiple Connections " MW : replaced as you suggest , because I believe that was the intended meaning anyway . " An application primarily interacts with this interface ... " This seems awkward . An interface is the means by which an application interacts with the underlying transports . MW : replaced " interface " with " API " . 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 do n't spuriously occur when some symbol has n't been defined . MW : this was n't about spuriously occurring compile - time or runtime errors but about implementing fall - backs because the API contract generally is only " best effort " except for things that will work over TCP . I inserted some more text here to clarify this better with examples . Also : why " exclusive of appendices " ? MW : Good catch ! That 's a historical thing ; I removed it . That appendix does n't even exist anymore . Transport Properties " As preference typed selection properties ... " I ca n't parse this . MW : it seems that this sentence has disappeared by now . There was another occurrence of " Preference - typed " , which I changed into " of type ' Preference ' " .  " An ideal transport system " for whom ? The capacity partitioning recommended here seems purely subjective . I 'd just remove it . MW : I replaced " An ideal transport system implementation would " with " A transport system implementation should , if possible , " . I believe that recommending a partitioning is necessary so that an application knows what to expect if things really work out . The particular described partitioning method is as good as any other , because , if it is implemented , an application can tune things as it wants anyway using the priority values . Without at least some sort of guidance on partitioning , the priorities become quite meaningless . With it , an application can at least say " this is how I 'd like to divide the capacity , if at all possible " . Transmission Might be worth pointing out there 's no guarantee here , either , considering resegmenting TCP middleboxes . MW : done ( by adding " , if possible " to the first sentence ) . Contexts " To get or set Message Properties , the optional scope parameter is left empty , for framing meta - data , the framer is passed . " I ca n't parse this . MW : It seems that this sentence has disappeared , auto - resolving this problem :) ( 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 ? MW : lower means higher priority . I a bracket to clarify this . Errors Should the SoftError Event carry some information about e.g. the ICMP message received ? MW : yes . The text said " This event informs the application about the receipt of an ICMP error message related to the Connection " ... and I replaced " receipt " with " receipt and content " . 
 Merging this one to get new drafts out ; let 's continue the discussion at or after 107 .
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 event queues, handler functions or classes,
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):
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 event queues, handler functions or classes,
communicating sequential processes, or other asynchronous calling
conventions.
Paragraph (version A):
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 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 API 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 API 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):
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 of this interface SHOULD implement each Selection
Property, Connection Property, and Message Context Property
specified in this document.  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.  For
example, if TCP is the only underlying transport protocol, the
Message Property "msg-ordered" can be implemented even if
disabling ordering will not have any effect TCP because the API
does not guarantee out-of-order delivery.  Similarly, the msg-
lifetime" Message Property can be implemented but ignored, as the
description of this Property states that "it is not guaranteed
that a Message will not be sent when its Lifetime has expired".
Paragraph (version A):
Preference-typed Selection Properties can be frequently used.
Implementations MAY therefore provide additional convenience
functions, see preference-conv for examples.  In addition,
implementations MAY provide a mechanism to create TransportProperties
objects that are preconfigured for common use cases as outlined in
property-profiles.
Paragraph (version B):
Selection Properties of type "Preference" can be frequently used.
Implementations MAY therefore provide additional convenience
functions, see preference-conv for examples.  In addition,
implementations MAY provide a mechanism to create TransportProperties
objects that are preconfigured for common use cases as outlined in
property-profiles.
Paragraph (version A):
connection-props provides a list of Connection Properties, while
Selection Properties are listed in the subsections below.  Note that
many properties are only considered during establishment, and can not
be changed after a Connection is established; however, they can be
queried.  Querying a Selection Property after establishment yields
the value Required for properties of the selected protocol and path,
Avoid for properties avoided during selection, and Ignore for all
other properties.
Paragraph (version B):
connection-props provides a list of Connection Properties, while
Selection Properties are listed in the subsections below.  Note that
many properties are only considered during establishment, and can not
be changed after a Connection is established; however, they can be
queried.  Querying a Selection Property after establishment yields
the value "Require" for properties of the selected protocol and path,
Avoid for properties avoided during selection, and Ignore for all
other properties.
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".  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 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 "Require" strictly limits path selection to a single
interface, and may often lead to less flexible and resilient
connection establishment.
Paragraph (version A):
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):
interface type as "Require" limits path selection to a small set of
interfaces, and leads to less flexible and resilient connection
establishment.
Paragraph (version A):
The Connection Property "Priority" operates on entangled Connections
as in msg-priority: when allocating available network capacity among
Connections in a Connection Group, sends on Connections with higher
Priority values will be prioritized over sends on Connections with
lower Priority values.  An ideal transport system implementation
would assign each Connection the capacity share (M-N) x C / M, where
N is the Connection's Priority value, M is the maximum Priority value
used by all Connections in the group and C is the total available
capacity.  However, the Priority setting is purely advisory, and no
guarantees are given about the way capacity is shared.  Each
implementation is free to implement a way to share capacity that it
sees fit.
Paragraph (version B):
The Connection Property "Priority" operates on entangled Connections
as in msg-priority: when allocating available network capacity among
Connections in a Connection Group, sends on Connections with higher
Priority values will be prioritized over sends on Connections with
lower Priority values.  A transport system implementation should, if
possible, assign each Connection the capacity share (M-N) x C / M,
where N is the Connection's Priority value, M is the maximum Priority
value used by all Connections in the group and C is the total
available capacity.  However, the Priority setting is purely
advisory, and no guarantees are given about the way capacity is
shared.  Each implementation is free to implement a way to share
capacity that it sees fit.
Paragraph (version A):
This property specifies that a message should be sent and received as
a single packet without transport-layer segmentation or network-layer
fragmentation.  Attempts to send a message with this property set
with a size greater to the transport's current estimate of its
maximum transmission segment size will result in a "SendError".  When
used with transports supporting this functionality and running over
IP version 4, the Don't Fragment bit will be set.
Paragraph (version B):
This property specifies that a message should be sent and received as
a single packet without transport-layer segmentation or network-layer
fragmentation, if possible.  Attempts to send a message with this
property set with a size greater to the transport's current estimate
of its maximum transmission segment size will result in a
"SendError".  When used with transports supporting this functionality
and running over IP version 4, the Don't Fragment bit will be set.
Paragraph (version A):
This Property is a non-negative integer representing the relative
inverse priority of this Connection relative to other Connections in
the same Connection Group.  It has no effect on Connections not part
of a Connection Group.  As noted in groups, this property is not
entangled when Connections are cloned, i.e., changing the Priority on
one Connection in a Connection Group does not change it on the other
Connections in the same Connection Group.
Paragraph (version B):
This Property is a non-negative integer representing the relative
inverse priority (i.e., a lower value reflects a higher priority) of
this Connection relative to other Connections in the same Connection
Group.  It has no effect on Connections not part of a Connection
Group.  As noted in groups, this property is not entangled when
Connections are cloned, i.e., changing the Priority on one Connection
in a Connection Group does not change it on the other Connections in
the same Connection Group.
Paragraph (version A):
Asynchronous introspection is also possible, via the SoftError Event.
This event informs the application about the receipt of an ICMP error
message related to the Connection.  This will only happen if the
underlying protocol stack supports access to soft errors; however,
even if the underlying stack supports it, there is no guarantee that
a soft error will be signaled.
Paragraph (version B):
Asynchronous introspection is also possible, via the SoftError Event.
This event informs the application about the receipt and contents of
an ICMP error message related to the Connection.  This will only
happen if the underlying protocol stack supports access to soft
errors; however, even if the underlying stack supports it, there is
no guarantee that a soft error will be signaled.