Draft: draft-ietf-taps-interface

Commentary: Closing : be more explicit about half - closed connections , allow it in the API too , fix errneous ConnectionError text . 
 Same build error . I do n't know what to do about this missing circleci file thing :( 
 good catch , thanks , incorporated 
 I do n't think you mean that  should throw a ConnectionError on a TCP Retransmission Timeout!I'm somewhat concerned about half - close , though this might just be editorial . An HTTP/3 implementation needs to send FIN when it 's done requesting , for instance ( I realize that HTTP/3 is not TCP , but I imagine the semantics are the same ) . So I think it would send its request with a end - of - message , According to the " Send " description , TAPS will send CLOSE.TCP automatically after the FIN . A regular " Close " will trigger a " Closed " event which tells the application it is n't getting more data , so I guess this just barely works if TAPS sends CLOSE.TCP but not Closed , and waits for the  command from the app ? Like I said , I 'm not sure this is wrong , but it 's not clearly stated how an app that needs half - close functionality should implement that . 
 I really really do n't think that TAPS should cause any Error on a TCP Retransmission Timeout ! This happens for many reasons , and is n't an upper - layer issue . 
 Regarding the half - closed scenario , I think you 're onto something there . Let 's see how this would work , for a client sending a message followed by a FIN , and the server answering : ( Note : all " close " calls " from above " have complete " all is over " semantics , to be able to also work with protocols which do not support half - closed connections ( such as SCTP ) . ) Client : Send , Message marked as Final . According to the implementation draft , this causes CLOSE.TCP , which will transmit the FIN to the server . As you suggest , the CLOSE.TCP would not invoke Closed , and instead wait for the  command from the app - this makes sense and would work like that , but indeed it 's not stated anywhere , so this text should be . Server : If this is a native TCP server , there 's no problem . If this is a TAPS server , then there 's no way for the server to know for the server - side transport system that it should not issue a Closed event to the application upon the FIN coming with the Final Message . After the Closed event , the application can not write anymore . Game over . How do we handle the server case ? E.g. , we could add yet another selection property : " Allow writing after Closed " . Not exactly beautiful ... but is there any other way to do it ? 
 Section 7 : Whether the connection can be used to receive data . A connection can not be used for reading if the connection was created with the Selection Property Direction of Communication set to unidirectional send or if a Message marked as Final was received , see Section 8.3.3.3 . The latter is only supported by certain transport protocols , e.g. , by TCP as half - closed connection . 
 Also : Final Messages The Message Context can indicate whether or not this Message is the Final Message on a Connection . For any Message that is marked as Final , the application can assume that there will be no more Messages received on the Connection once the Message has been completely delivered . This corresponds to the Final property that may be marked on a sent Message , see Section 8.1.3.5 . 
 technically solved in API ( " the best kind of solved " ) by existing text in 8.3.3.3 , section 10.1 still needs work in impl . 
 I write this here so people do n't miss it : There is this statement in the API doc , describing the Close call , which my PR for this issue will remove : " If the Remote Endpoint still has data to send , it can not be received after this call . " We can allow reading until Closed fires . For protocols such as SCTP that do not support half - closed connections , Closed would have to fire immediately upon calling  . 
 Looks good . LGTM , except for one thing .
Paragraph (version B):
At least one Local Endpoint MUST be specified if the Preconnection is
used to Listen() for incoming Connections, but the list of Local
Endpoints MAY be empty if the Preconnection is used to Initiate()
connections.  If no Local Endpoint is specified, the Transport
Services system will assign an ephemeral local port to the Connection
on the appropriate interface(s).  At least one Remote Endpoint MUST
be specified if the Preconnection is used to Initiate() Connections,
but the list of Remote Endpoints MAY be empty if the Preconnection is
used to Listen() for incoming Connections.  At least one Local
Endpoint and one Remote Endpoint MUST be specified if a peer-to-peer
Rendezvous is to occur based on the Preconnection.
Paragraph (version B):
If more than one Local Endpoint is specified on a Preconnection, then
all the Local Endpoints on the Preconnection MUST represent the same
host.  For example, they might correspond to different interfaces on
a multi-homed host, of they might correspond to local interfaces and
a STUN server that can be resolved to a server reflexive address for
a Preconnection used to make a peer-to-peer Rendezvous().
Paragraph (version B):
In most cases, it is expected that a single Remote Endpoint will be
specified by name, and a later call to Initiate() on the
Preconnection (see initiate) will internally resolve that name to a
list of concrete endpoints.  Specifying multiple Remote Endpoints on
a Preconnection allows applications to override this for more
detailed control.
Paragraph (version B):
A single Endpoint Object represents the identity of a network host.
That endpoint can be more or less specific depending on which
identifiers are set.  For example, an Endpoint that only specifies a
hostname may in fact end up corresponding to several different IP
addresses on different hosts.
Paragraph (version B):
The Transport Services API resolves names internally, when the
Initiate(), Listen(), or Rendezvous() method is called to establish a
Connection.  Privacy considerations for the timing of this resolution
are given in privacy-security.
Paragraph (version B):
The Resolve() action on a Preconnection can be used by the
application to force early binding when required, for example with
some Network Address Translator (NAT) traversal protocols (see
rendezvous).
Paragraph (version B):
An Endpoint can have an alternative definition when using different
protocols.  For example, a server that supports both TLS/TCP and QUIC
may be accessible on two different port numbers depending on which
protocol is used.
Paragraph (version B):
To support this, Endpoint Objects can specify "aliases".  An Endpoint
can have multiple aliases set.
Paragraph (version B):
The following example shows a case where "example.com" has a server
running on port 443, with an alternate port of 8443 for QUIC.
Paragraph (version B):
The following examples of Endpoints show common usage patterns.
Paragraph (version A):
Implementations may also support additional endpoint representations
and provide a single NewEndpoint() call that takes different endpoint
representations.
Paragraph (version A):
The transport services API resolves names internally, when the
Initiate(), Listen(), or Rendezvous() method is called to establish a
Connection.  The API explicitly does not require the application to
resolve names, though there is a tradeoff between early and late
binding of addresses to names.  Early binding allows the API
implementation to reduce connection setup latency, at the cost of
potentially limited scope for alternate path discovery during
Connection establishment, as well as potential additional information
leakage about application interest when used with a resolution method
(such as DNS without TLS) which does not protect query
confidentiality.
Paragraph (version B):
This property specifies whether the application would like the
Connection to send keep-alive packets or not.  Note that if a
Connection determines that keep-alive packets are being sent, the
applicaton should itself avoid generating additional keep alive
messages.  Note that when supported, the system will use the default
period for generation of the keep alive-packets.  (See also keep-
alive-timeout).
Paragraph (version B):
Note that this can have privacy implications because it might result
in users being linkable across the multiple paths.  Also, note that
setting this to false does not prevent the local Transport Services
system from _establishing_ connectivity using alternate paths (see
multipath-mode above); it only prevents _proactive advertisement_ of
addresses.
Paragraph (version A):
The most common client-server communication pattern involves the
client actively opening a connection, then sending data to the
server.  The server listens (passive open), reads, and then answers.
This property specifies whether an application wants to diverge from
this pattern - either by actively opening with Initiate(),
immediately followed by reading, or passively opening with Listen(),
immediately followed by writing.  This property is ignored when
establishing connections using Rendezvous().  Requiring this property
limits the choice of mappings to underlying protocols, which can
reduce efficiency.  For example, it prevents the transport system
from mapping Connections to SCTP streams, where the first transmitted
data takes the role of an active open signal I-D.ietf-taps-impl.
Paragraph (version B):
The most common client-server communication pattern involves the
client actively opening a connection, then sending data to the
server.  The server listens (passive open), reads, and then answers.
This property specifies whether an application wants to diverge from
this pattern - either by actively opening with Initiate(),
immediately followed by reading, or passively opening with Listen(),
immediately followed by writing.  This property is ignored when
establishing connections using Rendezvous().  Requiring this property
limits the choice of mappings to underlying protocols, which can
reduce efficiency.  For example, it prevents the Transport Services
system from mapping Connections to SCTP streams, where the first
transmitted data takes the role of an active open signal I-D.ietf-
taps-impl.
Paragraph (version B):
Session cache management: Used to tune session cache capacity,
lifetime, and other policies.
Paragraph (version B):
A Preconnection Object used in a Rendezvous() MUST have both the
Local Endpoint candidates and the Remote Endpoint candidates
specified, along with the transport properties and security
parameters needed for Protocol Stack selection, before the
Rendezvous() Action is initiated.
Paragraph (version B):
The Rendezvous() Action listens on the Local Endpoint candidates for
an incoming Connection from the Remote Endpoint candidates, while
also simultaneously trying to establish a Connection from the Local
Endpoint candidates to the Remote Endpoint candidates.
Paragraph (version B):
The Resolve() call returns lists of Local Endpoints and Remote
Endpoints, that represent the concrete addresses, local and server
reflexive, on which a Rendezvous() for the Preconnection will listen
for incoming Connections, and to which it will attempt to establish
connections.
Paragraph (version B):
The Rendezvous() Action can be initiated once both the Local Endpoint
candidates and the Remote Endpoint candidates retrieved from the peer
via the signalling channel have been added to the Preconnection.
Paragraph (version A):
The RendezvousDone<> Event occurs when a Connection is established
with the Remote Endpoint.  For Connection-oriented transports, this
occurs when the transport-layer connection is established; for
Connectionless transports, it occurs when the first Message is
received from the Remote Endpoint.  The resulting Connection is
contained within the RendezvousDone<> Event, and is ready to use as
soon as it is passed to the application via the Event.
Paragraph (version B):
The RendezvousDone<> Event occurs when a Connection is established
with the Remote Endpoint.  For Connection-oriented transports, this
occurs when the transport-layer connection is established; for
Connectionless transports, it occurs when the first Message is
received from the Remote Endpoint.  The resulting Connection is
contained within the RendezvousDone<> Event, and is ready to use as
soon as it is passed to the application via the Event.  Changes made
to a Preconnection after Rendezvous() has been called do not have any
effect on existing Connections.
Paragraph (version B):
Note that this does not guarantee no leakage of information, as
implementations may not be able to fully isolate all caches (e.g.
RTT estimates).  Note that this property may degrade connection
performance.
Paragraph (version B):
These properties specify configurations for the User Timeout Option
(UTO), in the case that TCP becomes the chosen transport protocol.
Implementation is optional and useful only if TCP is implemented in
the Transport Services system.
Paragraph (version A):
Message Contexts can also be used to send messages in reply to other
messages, see send-replies for details.
Paragraph (version B):
The Message Framer object can be added to one or more Preconnections
to run on top of transport protocols.  Multiple Framers may be added
to a preconnection; in this case, the Framers operate as a framing
stack, i.e. the last one added runs first when framing outbound
messages, and last when parsing inbound data.
Paragraph (version B):
Since Message Framers pass from Preconnection to Listener or
Connection, addition of Framers must happen before any operation that
may result in the creation of a Connection.
Paragraph (version B):
Note that this property is not a per-message override of the
connection Priority - see conn-priority.  The Priority properties may
interact, but can be used independently and be realized by different
mechanisms; see priority-in-taps.
Paragraph (version B):
The order in which Messages were submitted for transmission via the
Send Action will be preserved on delivery via Receive<> events for
all Messages on a Connection that have this Message Property set to
true.
Paragraph (version B):
Disabling this property indicates that the Transport Services system
may disable retransmissions or other reliability mechanisms for this
particular Message, but such disabling is not guaranteed.
Paragraph (version A):
Sent Events allow an application to obtain an understanding of the
amount of buffering it creates.  That is, if an application calls the
Send Action multiple times without waiting for a Sent Event, it has
created more buffer inside the transport system than an application
that always waits for the Sent Event before calling the next Send
Action.
Paragraph (version B):
Sent Events allow an application to obtain an understanding of the
amount of buffering it creates.  That is, if an application calls the
Send Action multiple times without waiting for a Sent Event, it has
created more buffer inside the Transport Services system than an
application that always waits for the Sent Event before calling the
next Send Action.
Paragraph (version A):
Multiple invocations of ReceivedPartial deliver data for the same
Message by passing the same MessageContext, until the endOfMessage
flag is delivered or a ReceiveError occurs.  All partial blocks of a
single Message are delivered in order without gaps.  This event does
not support delivering discontiguous partial Messages.
Paragraph (version A):
The described API is used to exchange information between an
application and the transport system.  While it is not necessarily
expected that both systems are implemented by the same authority, it
is expected that the transport system implementation is either
provided as a library that is selected by the application from a
trusted party, or that it is part of the operating system that the
application also relies on for other tasks.
Paragraph (version B):
The described API is used to exchange information between an
application and the Transport Services system.  While it is not
necessarily expected that both systems are implemented by the same
authority, it is expected that the Transport Services system
implementation is either provided as a library that is selected by
the application from a trusted party, or that it is part of the
operating system that the application also relies on for other tasks.
Paragraph (version B):
In either case, the Transport Services API is an internal interface
that is used to change information locally between two systems.
However, as the Transport Services system is responsible for network
communication, it is in the position to potentially share any
information provided by the application with the network or another
communication peer.  Most of the information provided over the
Transport Services API are useful to configure and select protocols
and paths and are not necessarily privacy sensitive.  Still, some
information could be privacy sensitive because it might reveal usage
characteristics and habits of the user of an application.