Draft: draft-trammell-taps-interface

Commentary: This should fix the different styles in Transport and Send Parameter from Issue 
 , taken from Socket Intents , provides the transport application hints by binding a special higher - layer class of transport parameter to the connection . , which describes the sending API , is largely taken from Post Sockets and tends to give simpler semantics to each Content at send time . These approaches have the similar aims , but come to them from different angles . Socket Intents was very ~Socket ~ Connection - oriented , and Post Sockets very ~Message ~ Content oriented . It seems difficult for them to coexist in a way that would allow an application developer to use this interface with ease . We should discuss , and agree on a way forward . 
 Being Content - oriented is good , as it offers more potential freedom below the api . i ’m for making as much as possible content - oriented . however : the intents things seem to be longer - term statements about app expectations or behavior - it does n’t make much sense to combine all of them with messages . same for some of the minset based parameters - i think having both is the only reasonable way out ? ! why hard to use , when these are all optional configs on a connection handle ? 
 For   , we already considered on which granularity these Intents can be applied – see slide 7 – I guess allowing them in any scope they are applicable is fine . Yes , this needs to be to the API 
 I grabbed the ticket and will try to do a pass tomorrow – Input welcome 
 I 've looked over this again , and I think there are four levels of granularity here , and part of what I 'm seeing as " lack of harmony " is the fact that three of them are kind of mixed up , and each of them interact with the send interface a little differently . here 's where I think we are ( following my comment in , considering intents more deeply ) ... Intents are about what the application does . You could have them be bound to a whole context ( i.e. , a container for multiple connections ; the process level object ) , except some applications might need to speak multiple protocols with wildly different profiles ( e.g. ,  ) , so it 's probably a useful simplifying decision to bind them only to Connections . Since Intents are advisory only , violating an Intent while sending should never be a runtime error . Transport selection properties are basically only about the constraints on Protocol Stack selection , and become irrelevant once the stack is selected ( we can have different discussion about how to do re - pre - establishment and whether or not the perceived need to do that is an application / API design error up in ) . Certain violations of transport selection properties may be runtime errors , but the API should endeavor to gracefully degrade . Transport stack properties are a lower - level way to reach down into the stack and tweak performance parameters , though these should be expressed in a transport - independent way when possible . Inconsistent transport stack property configuration will lead to runtime errors , but this is the application 's fault for being picky . ( I suspect servers will need to do more of this sort of thing than clients).Send parameters are about what should be done with this particular piece of Content within the context of the Connection it 's sent on . I think we 've got the right set of these , though we still need to come to consensus on priorities , it seems ... 
 I disagree with this perspective because it drops path selection from consideration . Intents are equally useful for path setup as well as assigning contents to paths – Theresa and I deeply looked into this.\ Therefore we should be able to express intents when sending contents . If the intent expressed on a content contradicts the path set up , the transport system must ignore them and continue . It might also make sense to change path selection parameters ( see Issue ) In addition to that , there are Transport Stack Properties that apply on a per - conetnts granularity ( e.g. " urgent data " in TCP ) - but these are I do n't like the idea to add the whole " require / prefer / avoid / prohibit " for all Send Parameters – Intents and all examples of Transport Stack Properties I came up with make no use of them . What we can to harmonize the concepts instead changing the the Protocol- and Path Selection Properties into Key / Values and put the " require / prefer / avoid / prohibit " into the value field 
 I do n't see how , can you say more here ? So perhaps the issue here is that we 're artificially trying to keep Intents separate from other path and protocol selection parameters , and we should try to recast all of these in terms of " selection parameters " attached to a preference . Ugh . Me either , but I do n't think I suggested that . hm , this is moving in the right direction here , but the interface still feels a little C89ish . How about making the preference the action on the parameter object instead ? i.e. : and so on ? 
 I disagree with this perspective because it drops path selection from consideration . I disagree with excluding  ( and some of the Path Selection Properties ) from the Contents Send Properties . Agreed – but I was arguing against artificially trying to keep   and Send Parameters apart . There is an intersection between both sets and that intersection should neither be duplicated nor look awkward in the API . I like this . How do we design the ContentsParameters then ? I 'd propose the following : 
 Ah , okay . Hm . Yes , we disagree . :) The send parameters really should be limited to those things which are bound to the Content . Indeed , one way to do this would for content to have Parameters bound to it , but that leads IMO to an unpleasant - to - use interface . In some languages , there 's no way around that , but as points out some languages ( e.g. Python ) provide optional arguments , and in those cases send parameters can be optional args to the function . We should n't define something that mandates a clunkier interface than the idiom of the language allows . We can of course define send parameters that are related to transport parameters ( and indeed , we should provide some easy to use reference to see which of these parameters are related / exclusive / etc ) , but I think they 're fundamentally different animals . 
 I 'm a bit confused here . So far I assumed that Intents could be set both per Connection and on individual Content , so they could be both transportParameters and sendParameters . For me , transportParameters and sendParameters are different things , but they can still be expressed using the same vocabulary , as discussed in . So the disagreement here is on whether an application should also be allowed set Intents as sendParameters , right ? 
 I think so , yes . In document terms , the two ways forward seem to be : Keep " Intents " as a separate category of things in § 5.2.4 , and note in § 7 that all Intents are also usable as send parameters ( somehow).Eliminate § 5.2.4 as a separate entity , fold intents into transport parameters , and create intents - derived send parameters where appropriate . I 'm proposing the latter . There 's another discussion we need to have about which Intents stay in the API and which do n't -- some of these , for instance , seem difficult to non - arbitrarily map down to behaviors in the underlying protocol stacks as pointed out in mail -- but that 's a separate issue . 
 I see , thanks for clarifying . In the current § 5.2.4 , it says that some Intents can also apply to individual messages , namely  to be Sent / Received , Timeliness , Disruption Resilience , and Cost Preferences . This reflects the previous work on granularity that  pointed out in his earlier post in this thread .   - derived send parameters for ( a subset of ) the above sounds feasible to me . About folding the Connection - based Intents into the other transport parameters , I see two potential issues which I 'm not sure yet how to resolve : Under what heading to put them - As they can influence both protocol and path selection , neither of these heading seemed appropriate for me , that 's why I put them under a separate heading . If not Intents , what should this heading be ? Reformulating them - Philipp and I already discussed whether some Intents could be reformulated as properties that fit into the " Require " , " Prefer " , " Avoid " , " Prohibit " preferences . But not all Intents can fit this scheme . What to do with those ? 
 One quick point : Though the phrasing sounds silly , " Intend " semantics are pretty much the same as " Prefer " semantics . ( " I intend to use this connection in this way " -"I prefer PSIs / paths that work well with this assumption " ) 
 I agree with  that the properties in the Application Intents section should be distributed between the other properties sections . If we want a new " Data / Content Properties " that could be good too , for the things that are more about what the application wants for its data . I 'd say for you list : Traffic Category or Service Class seems like a Protocol Selection Property ( previously Generic Protocol Property ) . This is a generic protocol option that influences the nature of the stream or flow I have . It influences how I initialize my transport protocol . Size / Duration / Timeliness / Resilience all seem like Protocol Selection Properties ( previously Generic Protocol Properties ) . Again , these will help choose which protocols to use , and how to prep and schedule them . Cost Preferences ( for us , Allow / Prohibit Expensive ) is a Path Selection Property . One thing that would be good to note is that Path Selection properties take effect not just in the initial bringup , but for all of the evaluation of flows and interfaces for multipath or migratable protocols . I would argue again that any properties per - send / receive should be specified as separate APIs from the pre - establishment APIs , even if they look similar , since they have different effects and domains of relevance . 
 For Traffic Category and Cost Preferences , I can see them fit better into Protocol or Path Selection , but I 'm not sure yet if they fit exclusively . For the other Intents I 'm not convinced that they can be sorted at all . For example , so far we use  mainly to select the path on which we predict the shortest completion time for the transfer , i.e. , depending on whether it is a " large " or a " small " transfer . For Timeliness and Resilience I can also more easily think of a path selection example based on lower latency and availability , respectively . On the other hand , the same Intents can help choose and configure transport protocols . So maybe putting them as " Data / Content Properties " would be better than trying to squeeze them into one of the two Selection categories . I think making the above clear in the Implementation draft will help us in this discussion and I 'm planning to get started on this soon . I agree with Tommy 's point about Path Selection properties also taking effect later on . About the per - send / receive properties ,  is currently working on Intents - derived per - Content properties , see . 
 I agree that the intents fit in different parts . I think that 's part of the problem - they 're treated ( by being under one subheading ) as a category in their own right , but they 're really quite a heterogeneous set of things . 
 I think the whole dividing into path selection properties , protocol selection properties , intents and protocol properties is rather historic , than making sense at all . In my world , we have four Dimensions in which we can divide up parameters : Type Int / Enum Protocol Properties Content Properties Intents Preference Enum Preferences of Expression advisory Intents Preferences with avoid / prefer preference Protocol Properties Content Properties mandatory Preferences with require / prohibit preference Protocol Properties Content Properties Subject Protocol Selection Preferences Intents Protocol Parameters Preferences Protocol Properties Intents Path Selection ( read MPTCP subflow ) Preferences Protocol Properties Intents Path Selection ( read MPTCP segment to subflow assignment ) Preferences Protocol Properties Content Properties Intents Content Transmission Preferences Protocol Properties Intents of use Pre - Establishment Preferences Protocol Properties Intents Establishment Preferences Protocol Properties Intents Content Send Preferences Content Properties Protocol Properties Intents Mixing these dimensions in terminology is bound to fail ( as we currently try to do ) . Still working out how and where to fix this 
 First consequences : get rid of differentiating between Path Selection and Protocol Selection properties rename Path Selection and Protocol Selection properties to Preferences remove the Preference parameter from Protocol properties and Intents Make calls for Transport and Send Properties roughly the same 
 wait , why ? Whether or not a parameter is preferred ( or avoided , or required , or prohibited ) is orthogonal to how we talk about them , or am I missing something here ? 
 Look at # protocol - props – there is nothin to require / prefer / avoid / prohibt 
 ahhh okay , got it . 
 I had a brief look at the branch here , and I 'm very confused about what you 're trying to do here . unnecessary as a send parameter ; the length of the Content gives the size to be sent . Maybe you could tell the transport the size of the message it should expect to receive based on a given send , but I 'm not sure I know what a transport will do with it similarly odd ; certainly this is a property of multiple sends , not a single one ? to be an alternate expression of Lifetime . to be an alternate expression of path selection property . I think we should probably take a step back here , and instead of starting from an attempt to map   concepts directly into this document , attempt to see what concepts in Socket Intents are missing from the API , and how those can best be in keeping with the architecture ( and can be implemented using transport services described in 8095 and the upcoming security properties doc ) . In any case I do n't think this will converge before -00 , so let 's take the time pressure off and mark it post - London ... 
 This was " just " a copy an paste and is fixed now . Most work went into re - structuring and fixing terminology to harmonise Sent and Trasnport Parameter concepts . I will file a PR today and remove the post - London milestone for from this ticket . I am fine with a partial merge and a new post - London issues for discussing Send Parameter Intents . 
 this is closeable with the merge of , yes ? 
 Most things discussed here are addressed with merge - remaining things are post - London and covered by issue 
 From a quick look , no objections on my part . I 'll review in more detail and align with the preconnection changes in once this is merged . Fine by me ... little things here and there , but altogether this seems ok IMO
Paragraph (version A):
When creating a connection, an application needs to specify transport
parameters reflecting its requirements and preferences regarding its
communication.  These Transport parameters include Protocol Selection
Properties, Protocol Properties (specific configuration of a
transport protocol once it has been selected), Path Selection
Properties, and Application Intents (hints to the transport system
what to optimize for).
Paragraph (version A):
Some properties are strict requirements that the application relies
on, while others are hints of what transport features would be
helpful for the application.  For example, if an application asks for
reliable data transfer, choosing a transport protocol such as UDP,
which does not have this feature, will break the application's
functionality.  On the other hand, the option to not require
checksums when receiving an individual Content can help optimize for
low latency, but if not present, it will most likely not break the
fundamental assumptions of the application.
Paragraph (version A):
For most properties, it is beneficial for the application to set them
as early as possible in order to help the transport system optimize.
Some parameters can also be set later in the lifetime of a
connection.  However, Protocol Selection Properties and Path
Selection Properties MUST be added to the TransportParameters object
before calling Initiate() and SHOULD result in a runtime error if
changed later.  appendix-specify-query-params gives an overview of
what Transport Parameters can be specified and queried during which
phase.
Paragraph (version A):
The following properties can be adjusted before establishing a
Connection.  There need to be sensible defaults for the Protocol
Selection Properties.  The defaults given in the following section
represent a configuration that can be implemented over TCP.  An
alternate set of default Protocol Selection Properties would
represent a configuration that can be implemented over UDP.
Paragraph (version B):
When creating a connection, an application needs to specify transport
parameters reflecting its requirements and preferences regarding its
communication.  These Transport parameters include _Transport
Preferences_ (towards protocol selection and path selection) as well
as _Application Intents_ (hints to the transport system what to
optimize for) and _Protocol Properties_ (to configure transport
protocols).
Paragraph (version B):
All Transport Parameters are organized within a single name space,
that is shared with Send Parameters (see send-params).  While
Application Intents and Protocol Properties take parameter specific
values, Transport Preferences use one of five fixed levels (see
transport-prefs).
Paragraph (version B):
Some parameters express strict requirements that the application
relies on, while others are hints of what transport features would be
helpful for the application.  For example, if an application asks for
reliable data transfer, choosing a transport protocol such as UDP,
which does not have this feature, will break the application's
functionality.  On the other hand, the option to not require
checksums when receiving an individual Content can help optimize for
low latency, but if not present, it will most likely not break the
fundamental assumptions of the application.  Moreover, there can be
conflicts between parameters set by the application: If multiple
features are requested which are offered by different protocols, it
may not be possible to satisfy all requirements.  Consequently, a
transport system must prioritize Transport Parameters and consider
the relevant trade-offs, see also TAPS-MINSET.
Paragraph (version B):
Transport Preferences drive protocol selection and path selection on
connection establishment.  Not all transport protocols work on all
paths.  Thus, transport protocol selection is tied to path selection,
which may involve choosing between multiple local interfaces that are
connected to different access networks.
Paragraph (version B):
Preferences effecting protocol selection MUST be added to the
TransportParameters object before establishing a connection.
Changing them later SHOULD result in a runtime error.
Paragraph (version B):
Preferences effecting path selection MAY be changed but only
effect future connection migrations or path selection for
multipath protocols.
Paragraph (version B):
There need to be sensible defaults for the Transport Preferences.
There need to be sensible defaults for the Protocol Selection
Properties.  The defaults given in the following section represent a
configuration that can be implemented over TCP.  An alternate set of
default Protocol Selection Properties would represent a configuration
that can be implemented over UDP.
Paragraph (version A):
Not all transport protocols work on all paths.  Thus, transport
protocol selection is tied to path selection, which may involve
choosing between multiple local interfaces that are connected to
different access networks.
Paragraph (version A):
Path Selection Properties are requirements, prohibitions, or
preferences, that an application has regarding path selection.  These
properties should be specified as early as possible in order to help
the TAPS system optimize.  However, they may also be specified later.
Paragraph (version A):
Specifying Application Intents is not mandatory.  An application can
specify any combination of Application Intents.  All Application
Intents can be specified for connections and cloning a Connection to
form a Connection Group will clone the associated Intents along with
the other transport parameters.  Some Intents can also be specified
for individual Content, similar to the properties in send-props.
Paragraph (version B):
Specifying Application Intents is not mandatory.  An application can
specify any combination of Application Intents.  All Application
Intents can be specified for connections and cloning a Connection to
form a Connection Group will clone the associated Intents along with
the other transport parameters.  Some Intents can also be specified
for individual Content, similar to the properties in send-params.
Paragraph (version B):
All transport parameters used in the pre-establishment phase are
collected in a _TransportParameters_ object.  For the sake of
convenience, we suggests implementing TransportParameters class as
sub-class of an existing Dictionary or Set class to allow in-place
notion of Transport Parameters.
Paragraph (version B):
The Individual parameters are then added to the TransportParameters
object.  While Protocol Properties and Application Intents use the
"add" call, Transport Preferences use special calls for the levels
defined in transport-params.
Paragraph (version A):
The Send action takes six per-Content properties which control how it
will be sent down to the underlying Protocol Stack and transmitted.
Note that some of these properties are not compatible with transport
parameters; attempting to Send with such an incompatibility yields a
SendError.
Paragraph (version B):
The Send action takes per-Content send parameters which control how
the contents will be sent down to the underlying Protocol Stack and
transmitted.
Paragraph (version B):
If Send Parameters should be overridden for a specific content, an
empty sent parameter Object can be acquired and all desired Send
Parameters can be added to that object.  A Send Parameters object can
be reused for sending multiple contents with the same properties.
Paragraph (version B):
The Send Parameters are organized in _Content Properties_, _Protocol
Properties_, and _Application Intents_.  The Send Parameters share a
single namespace with the Transport Parameters (see transport-
params).  This allows to specify Protocol Properties and that can be
overridden on a per content basis or Application Intents that apply
to a specific content.  See appendix-specify-query-params for an
overview.
Paragraph (version B):
On a bi-directional connection, this Intent specifies what amount of
data the application expects to receive in reply to the content sent.
It is a numeric property and given in Bytes.
Paragraph (version B):
This Intent specifies what bitrate the application wishes the content
to be sent with.  This is useful as input for any transport that does
packet pacing.  It is a numeric property and given in Bytes per
second.
Paragraph (version B):
On a bi-directional connection, this Intent specifies what bitrate
the application expects to receive in reply to the content sent.  It
is a numeric property and given in Bytes per second.
Paragraph (version B):
This Intent describes what an application prefers regarding monetary
costs, e.g., whether it considers it acceptable to utilize limited
data volume.  It provides hints to the transport system on how to
handle tradeoffs between cost and performance or reliability.  This
Intent can also apply to individual Content.
Paragraph (version B):
The default is "Balance Cost".
Paragraph (version A):
Transport Features of the protocols that were selected.  These
features correspond to the properties given in protocol-selection-
props and can only be queried.
Paragraph (version B):
Transport Features of the protocols that were selected.  These
features correspond to the properties given in transport-params
and can only be queried.