Draft: draft-ietf-taps-interface

Commentary: Completes 
 As discussed at the IETF 105 TAPS session : I suggest defining framers as a set of functions that transforms messages into byte streams and vice versa ( quite similar to what we have now , but replace " piece of code " with " set of functions " ) . And then we have to find words for the " Framers can also do a bit more negotiation , handshake , etc " . Also , I suggest keeping the following in the API draft : how to add a Framer to a Preconnection what functionality a Framer can implement how an application can interact with framer metadata through the Message Context The rest I suggest to move to the Implementation draft , e.g. , the " How can a Framer be implemented " . It 's an example , but Framers can also be implemented in different ways . I 'm willing to contribute text if needed . 
 Done with ! 
 lgtmThanks  ! I had a very quick look and the text split and move of text looks good to me , so no problem merging this . I noticed two nits and one question for what seemed to be an inconsistency to me .
Paragraph (version A):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(receive-framing).
Paragraph (version B):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol that provides a
reliable ordered byte stream, an application may receive this byte
stream as partial Messages and transform it into application-layer
Messages.  Alternatively, an application may provide a Message
Framer, which can transform a byte stream into a sequence of Messages
(framing).
Paragraph (version A):
The application can set a minIncompleteLength value to indicates the
smallest partial Message data size in bytes that should be delivered
in response to this Receive.  By default, this value is infinite,
which means that only complete Messages should be delivered (see
receive-partial and receive-framing for more information on how this
is accomplished).  If this value is set to some smaller value, the
associated receive event will be triggered only when at least that
many bytes are available, or the Message is complete with fewer
bytes, or the system needs to free up memory.  Applications should
always check the length of the data delivered to the receive event
and not assume it will be as long as minIncompleteLength in the case
of shorter complete Messages or memory issues.
Paragraph (version B):
The application can set a minIncompleteLength value to indicate the
smallest partial Message data size in bytes that should be delivered
in response to this Receive.  By default, this value is infinite,
which means that only complete Messages should be delivered (see
receive-partial and framing for more information on how this is
accomplished).  If this value is set to some smaller value, the
associated receive event will be triggered only when at least that
many bytes are available, or the Message is complete with fewer
bytes, or the system needs to free up memory.  Applications should
always check the length of the data delivered to the receive event
and not assume it will be as long as minIncompleteLength in the case
of shorter complete Messages or memory issues.
Paragraph (version A):
See receive-framing for handling Message framing in situations where
the Protocol Stack only provides a byte-stream transport.
Paragraph (version B):
See framing for handling Message framing in situations where the
Protocol Stack only provides a byte-stream transport.
Paragraph (version A):
Message Framers allow message boundaries to be preserved when using a
Connection object, even when using byte-stream transports.  This
facility is designed based on the fact that many of the current
application protocols evolved over TCP, which does not provide
message boundary preservation, and since many of these protocols
require message boundaries to function, each application layer
protocol has defined its own framing.
Paragraph (version B):
Although most applications communicate over a network using well-
formed Messages, the boundaries and metadata of the Messages are
often not directly communicated by the transport protocol itself.
For example, HTTP applications send and receive HTTP messages over a
byte-stream transport, requiring that the boundaries of HTTP messages
be parsed out from the stream of bytes.
Paragraph (version B):
Message Framers allow extending a Connection's Protocol Stack to
define how to encapsulate or encode outbound Messages, and how to
decapsulate or decode inbound data into Messages.  Message Framers
allow message boundaries to be preserved when using a Connection
object, even when using byte-stream transports.  This facility is
designed based on the fact that many of the current application
protocols evolved over TCP, which does not provide message boundary
preservation, and since many of these protocols require message
boundaries to function, each application layer protocol has defined
its own framing.
Paragraph (version A):
A Message Framer is primarily defined by the set of code that handles
events for a framer implementation, specifically how it handles
inbound and outbound data parsing.
Paragraph (version A):
Applications can instantiate a Message Framer upon which they will
receive framing events, or use a Message Framer defined by another
library.
Paragraph (version A):
Message Framer objects will deliver events to code that is written
either as part of the application or a helper library.  This piece of
code will be referred to as the "framer implementation".
Paragraph (version A):
Framers have the ability to also dynamically modify Protocol Stacks,
as described in framer-lifetime.
Paragraph (version B):
The API to implement a Message Framer can vary depending on the
implementation; guidance on implementing Message Framers can be found
in I-D.ietf-taps-impl.
Paragraph (version A):
When a Connection establishment attempt begins, an event is delivered
to notify the framer implementation that a new Connection is being
created.  Similarly, a stop event is delivered when a Connection is
being torn down.  The framer implementation can use the Connection
object to look up specific properties of the Connection or the
network being used that may influence how to frame Messages.
Paragraph (version A):
When Message Framer generates a "Start" event, the framer
implementation has the opportunity to start writing some data prior
to the Connection delivering its "Ready" event.  This allows the
implementation to communicate control data to the remote endpoint
that can be used to parse Messages.
Paragraph (version A):
In order to parse an received flow of data into Messages, the Message
Framer notifies the framer implementation whenever new data is
available to parse.
Paragraph (version B):
Common Message Framers can be provided by the Transport Services
implementation, but an implemention ought to allow custom Message
Framers to be defined by the application or some other piece of
software.  This section describes one possible interface for defining
Message Framers as an example.
Paragraph (version B):
A Message Framer is primarily defined by the set of code that handles
events for a framer implementation, specifically how it handles
inbound and outbound data parsing.  The piece of code that implements
custom framing logic will be referred to as the "framer
implementation", which may be provided by the Transport Services
implementation or the application itself.  The Message Framer refers
to the object or piece of code within the main Connection
implementation that delivers events to the custom framer
implementation whenever data is ready to be parsed or framed.
Paragraph (version B):
When a Connection establishment attempt begins, an event can be
delivered to notify the framer implementation that a new Connection
is being created.  Similarly, a stop event can be delivered when a
Connection is being torn down.  The framer implementation can use the
Connection object to look up specific properties of the Connection or
the network being used that may influence how to frame Messages.
Paragraph (version B):
When a Message Framer generates a "Start" event, the framer
implementation has the opportunity to start writing some data prior
to the Connection delivering its "Ready" event.  This allows the
implementation to communicate control data to the remote endpoint
that can be used to parse Messages.
Paragraph (version B):
In order to parse a received flow of data into Messages, the Message
Framer notifies the framer implementation whenever new data is
available to parse.
Paragraph (version A):
With RECEIVE.TCP, TCP delivers a stream of bytes without any
Message delineation.  All data delivered in the "Received" or
"ReceivedPartial" event will be part of a single stream-wide
Message that is marked Final (unless a MessageFramer is used).
EndOfMessage will be delivered when the TCP Connection has
received a FIN (CLOSE-EVENT.TCP or ABORT-EVENT.TCP) from the peer.
Paragraph (version B):
With RECEIVE.TCP, TCP delivers a stream of bytes without any
Message delineation.  All data delivered in the "Received" or
"ReceivedPartial" event will be part of a single stream-wide
Message that is marked Final (unless a Message Framer is used).
EndOfMessage will be delivered when the TCP Connection has
received a FIN (CLOSE-EVENT.TCP or ABORT-EVENT.TCP) from the peer.