Draft: draft-ietf-taps-interface

Commentary: This PR provides usage examples of our abstract interface , to address . The examples show how an application might use Listen ( ) , Initiate ( ) , and  ( ) , send a Message , and receive a Message . There is some redundancy between these examples , and I introduces some subtle differences to make them plausible , e.g. , the " server " provides its identity , and the " client " verifies the other endpoint 's identity using a trust callback . Overall the section became rather long . Should we instead just stick to one example , e.g. , Initiate ( ) ? ( Or Rendezvous ( ) because it covers the most aspects ? Or Initiate ( ) but with all the aspects from  ( ) ? ) Otherwise I 'm particularly interested in feedback on the Rendezvous ( ) example -- I think it 's correct wrt the draft , but is there a " more plausible " port number , and should anything else be set there that is not in the Initiate ( ) and Listen ( ) examples ? 
 Thanks for the review , I addressed the comments . Maybe the default for Preserve Message Boundaries should be  as well , if we receive only complete Messages by default ... 
 I 'm good with these changes . Regarding how we show the pseudo - code , I 'm not totally sure about the notation ( how rigorous are we on that ? ) , so someone else should validate it makes sense . 
 Similar to the way we simple diagrams to the architecture document to make the " story " of the document more compelling , we should begin the interface document with a simple workflow for an example connection . This way , we can show concretely up front how this is simple and useful , while being quite flexible and powerful . This can also inform how we then continue to explain depth to the details . 
 I 'm going to prepare a PR this week . 
 This looks good , modulo a couple of comments in the review ( introduce API example notation , decide on formatting for property names ) . In the interests of getting this into the draft rev for Prague , though , I do n't think we should block merging on these , and can clean them up in / after Prague .
Paragraph (version B):
Act as a server, by listening for incoming connections, receiving
requests, and sending responses, see server-example.
Paragraph (version B):
Act as a client, by connecting to a remote endpoint using
Initiate, sending requests, and receiving responses, see client-
example.
Paragraph (version B):
Act as a peer, by connecting to a remote endpoint using Rendezvous
while simultaneously waiting for incoming Connections, sending
Messages, and receiving Messages, see peer-example.
Paragraph (version B):
The examples in this section presume that a transport protocol is
available between the endpoints which provides Reliable Data
Transfer, Preservation of data ordering, and Preservation of Message
Boundaries.  In this case, the application can choose to receive only
complete messages.
Paragraph (version B):
If none of the available transport protocols provides Preservation of
Message Boundaries, but there is a transport protocol which provides
a reliable ordered octet stream, an application may receive this
octet stream as partial Messages and transform it into application-
layer Messages.  Alternatively, an application may provide a
Deframer, which is a function that transforms an octet stream into a
sequence of Messages, see receive-framing.
Paragraph (version B):
This is an example of how an application might listen for incoming
Connections using the Transport Services Interface, receive a
request, and send a response.
Paragraph (version B):
This is an example of how an application might connect to a remote
application using the Transport Services Interface, send a request,
and receive a response.
Paragraph (version B):
This is an example of how an application might establish a connection
with a peer using Rendezvous(), send a Message, and receive a
Message.