Draft: draft-trammell-taps-interface

Commentary: This commit fixes bug by making transport parameter types explicit . It also fixes Path- and Protocol Selection Properties from " binary + preference " to preferences type . With the old boolean properties , one could do things like " prohibit Reliable Transport false " - is that the same as " prefer Reliable Transport true " ? 
 To the questions in review summary : For the general case : I believe there will be boolean properties ( that are not preferences ) . The way I understand " Excessive Retransmit Notifications " and " ICMP soft error message " , I think booleans are the more appropriate type . Not for -00 , but for -01 : I want to define all types more rigorously in -01 --- we have Boolean , Enumeration , Boolean in the Transport Parameters right now , we also have some Integers in the Send Parameters . I am not sure that the frontmatter of this section is the right place to do so . 
 General clarification : This pull request changed " preference " to a data type a value can have rather than being something weakly defined that can be specified along with every Transport Parameter . So we go from a Key / Preference / Value tripel where Preference or Value is pointless for ( n-1 ) cases to a Key / Value pair with typed values . The only Transport Parameter ( including the Intents in the Appendix ) that uses a parameter and a preference is the " Interface Type " . I would like to land this for -00 as this is good enough for discussion while the old state is confusing . ToDos for -01 : Explain types clearly make " Interface Type " easier in -01 discuss extendability 
 If we 're doing booleans , the document needs to define a concise and generally applicable rule for how booleans interact with preferences . ISTM that boolean True = = preference Prefer and boolean False = = preference  ( in which case , why not just say  and Avoid instead of True and False ? ) I might be wrong here though . Will defer to 
 also Please file everything in the comments on this PR that should be addressed in -01 as an issue ( if you have n't already ) ... thanks ! 
 Ok - now I got your point . These properties ( Notification of excessive retransmissions and Notification of ICMP soft error message arrival ) are actually doing two things : Enable sending these events Indicate that we prefer protocols stacks that can send these events The question is which one is more important . As I think the former is more important , I leave it boolean an add remarks to the individual properties that this implies preferring protocols that can provide these events for now . As this does not hide things , this should provide the better feedback for -00 
 This should be ready for landing . – please merge if you agree Open Issues for Milestone itef-01 : Restructure Transport Parameters Section Explain data types explicitly Rewrite Interface Types to be useful and implementable 
 Transport and Send Parameter have different data types . These types are used in the document in a more or less intuitive way but are never defined explicitly . May need a new section next to the pseudocode definition . 
 This has been addressed in PR 
 This is a fork of Issue – The part of it that does not need discussion . Annotate " data type " for each Transport Parameter Change " boolean " Protocol and Path Selection Parameters to type " Preference " Remove editing artifacts 
 still not convinced by the boolean argument , but it 's time to ship it .
Paragraph (version A):
All Transport Parameters are organized within a single namespace
shared with Send Parameters (see send-params).  All transport
parameters take paremeter-specific values.  Protocol and Path
Selection properties additionally take one of five preference levels,
though not all preference levels make sense with all such properties.
Paragraph (version A):
Note that it is possible for a set of specified transport parameters
to be internally inconsistent, or for preferences to be inconsistent
with the later use of the API by the application.  Application
developers can reduce inconsistency by only using the most stringent
preference levels when failure to meet a preference would break the
application's functionality (e.g. the Reliable Data Transfer
preference, which is a core assumption of many application
protocols).  Implementations of this interface should also raise any
detected errors in configuration as early as possible, to help ensure
these inconsistencies are caught early in the development process.
Paragraph (version B):
All Transport Parameters are organized within a single namespace
shared with Send Parameters (see send-params).  These transport
parameters take values of parameter-specific types.
Paragraph (version B):
Note that it is possible for a set of specified transport parameters
to be internally inconsistent, or to be inconsistent with the later
use of the API by the application.  Application developers can reduce
inconsistency by only using the most stringent preference levels when
failure to meet a preference would break the application's
functionality (e.g. the Reliable Data Transfer preference, which is a
core assumption of many application protocols).  Implementations of
this interface should also raise any detected errors in configuration
as early as possible, to help ensure these inconsistencies are caught
early in the development process.
Paragraph (version B):
Internally, the transport system will first exclude all protocols and
paths that match a Prohibit, then only keep candidates that match a
Require, then sort candidates according to Preferred properties, and
then use Avoided properties as a tiebreaker.  In case of conflicts
between protocol and path selection properties, path selection
properties take precedence.  For example, if an application indicates
a preference for a specific path, but also a preference for a
protocol not available on this path, the transport system will try
the path first, so the protocol selection property might not have an
effect.
Paragraph (version A):
This boolean property specifies whether the application wishes to use
a transport protocol that that provides mechanisms to help ensure
that all data is received and without corruption on the other side.
This also entails being notified when a Connection is closed or
aborted.  This property applies to Connections and Connection Groups.
This is a strict requirement.  The default is to enable Reliable Data
Transfer.
Paragraph (version A):
This boolean property specifies whether the application wishes to use
a transport protocol that provides mechanisms to ensure that data is
received by the application on the other end in the same order as it
was sent.  This property applies to Connections and Connection
Groups.  This is a strict requirement.  The default is to preserve
data ordering.
Paragraph (version B):
This property specifies whether the application wishes to use a
transport protocol that that provides mechanisms to help ensure that
all data is received and without corruption on the other side.  This
also entails being notified when a Connection is closed or aborted.
This property applies to Connections and Connection Groups.  This is
a strict requirement.  The default is to enable Reliable Data
Transfer.
Paragraph (version B):
This property specifies whether the application wishes to use a
transport protocol that provides mechanisms to ensure that data is
received by the application on the other end in the same order as it
was sent.  This property applies to Connections and Connection
Groups.  This is a strict requirement.  The default is to preserve
data ordering.
Paragraph (version A):
This boolean property specifies whether an application considers it
useful to indicate its reliability requirements on a per-Message
basis.  This property applies to Connections and Connection Groups.
This is not a strict requirement.  The default is to not have this
option.
Paragraph (version A):
This boolean property specifies whether an application would like to
supply a Message to the transport protocol before Connection
establishment, which will then be reliably transferred to the other
side before or during Connection establishment, potentially multiple
times.  See also send-idempotent.  This is a strict requirement.  The
default is to not have this option.
Paragraph (version A):
This boolean property specifies that the application would prefer
multiple Connections within a Connection Group to be provided by
streams of a single underlying transport connection where possible.
This is not a strict requirement.  The default is to not have this
option.
Paragraph (version A):
This boolean property specifies whether an application considers it
useful to be informed in case sent data was retransmitted more often
than a certain threshold.  This property applies to Connections and
Connection Groups.  This is not a strict requirement.  The default is
to have this option.
Paragraph (version A):
This boolean property specifies whether an application considers it
useful to be informed when an ICMP error message arrives that does
not force termination of a connection.  This property applies to
Connections and Connection Groups.  Received ICMP errors will be
available as SoftErrors.  Note that even if a protocol supporting
this property is selected, not all ICMP errors will necessarily be
delivered, so applications cannot rely on receiving them.  This is
not a strict requirement.  The default is not to have this option.
Paragraph (version A):
This boolean property specifies whether the application considers it
useful to enable / disable / configure a checksum when sending data,
or decide whether to require a checksum or not when receiving data.
This property applies to Connections and Connection Groups.  This is
not a strict requirement, as it signifies a reduction in reliability.
The default is full checksum coverage without being able to change
it, and requiring a checksum when receiving.
Paragraph (version B):
This property specifies whether an application considers it useful to
indicate its reliability requirements on a per-Message basis.  This
property applies to Connections and Connection Groups.  This is not a
strict requirement.  The default is to not have this option.
Paragraph (version B):
This property specifies whether an application would like to supply a
Message to the transport protocol before Connection establishment,
which will then be reliably transferred to the other side before or
during Connection establishment, potentially multiple times.  See
also send-idempotent.  This is a strict requirement.  The default is
to not have this option.
Paragraph (version B):
This property specifies that the application would prefer multiple
Connections within a Connection Group to be provided by streams of a
single underlying transport connection where possible.  This is not a
strict requirement.  The default is to not have this option.
Paragraph (version B):
This property specifies whether an application considers it useful to
be informed in case sent data was retransmitted more often than a
certain threshold.  When set to true, the effect is twofold: The
application may receive events in case excessive retransmissions.  In
addition, the transport system considers this as a preference to use
transports stacks that can provide this notification.  This is not a
strict requirement.  If set to false, no notification of excessive
retransmissions will be sent and this transport feature is ignored
for protocol selection.
Paragraph (version B):
This property applies to Connections and Connection Groups.  The
default is to have this option.
Paragraph (version B):
This property specifies whether an application considers it useful to
be informed when an ICMP error message arrives that does not force
termination of a connection.  When set to true, received ICMP errors
will be available as SoftErrors.  Note that even if a protocol
supporting this property is selected, not all ICMP errors will
necessarily be delivered, so applications cannot rely on receiving
them.  Setting this option also implies a preference to prefer
transports stacks that can provide this notification.  If not set, no
events will be sent for ICMP soft error message and this transport
feature is ignored for protocol selection.
Paragraph (version B):
This property applies to Connections and Connection Groups.  The
default is not to have this option.
Paragraph (version B):
This property specifies whether the application considers it useful
to enable / disable / configure a checksum when sending data, or
decide whether to require a checksum or not when receiving data.
This property applies to Connections and Connection Groups.  This is
not a strict requirement, as it signifies a reduction in reliability.
The default is full checksum coverage without being able to change
it, and requiring a checksum when receiving.
Paragraph (version A):
This enumerated property specifies which kind of access network
interface, e.g., WiFi, Ethernet, or LTE, to prefer over others for
this Connection, in case they are available.  In general, Interface
Types should be used only with the "Prefer" and "Prohibit" preference
level.  Specifically, using the "Require" preference level for
Interface Type may limit path selection in a way that is detrimental
to connectivity.  The default is to use the default interface
configured in the system policy.