Draft: draft-ietf-taps-interface

Commentary: This PR is based on the presentation given at IETF 104 and the received feedback regarding Framers . This enhances and clarifies the API text around how framers are set up and used . 
 I agree that we should have an example somewhere , but I also thought this should be a different PR . 
 One comment / request : I would assume that most framers would have a length field . I wonder if it would be make sense to provide an interface to indicate where to find the length and move the parsing task into the transport . That would implementing simple framers that only have a length super easy ... 
 Not done , but did some cleanup to remove the Instance object , etc . Now there 's just a  that interacts with the Connection , which simplifies things a bunch . I 'd like to add some diagrams , but also a code example of a simple length - value header framer . I was looking at our " sample " code for a client and server , and it 's not clear to me in our syntax how we show what the code does upon receiving an event . Let 's say , I want to show that my message framer is called to handle a new sent message . Where do I write that " block " of code ? ? 
 Earlier when we discussed an example , we agreed that we need it but that we could leave it out of this PR . Another answer : I think the receiving code is also changed by PR . ISTM that landing this one as well as first , and then writing this example code would be a good sequence . UPDATE : I just noticed that you approved PR three minutes ago , so I just clicked the " merge " button . I hope that this makes things easier . 
 thanks for the comments ! I more clarification that there 's a Message Framer object that delivers events to the framer implementation code , and made it more clear that this " framer implementation " code is something that the application or some other library does , and it 's what receives the events to actual do the framing and run its code . 
 can you take another look at the state of the PR ? I 'd like to see this merged and then iterate more if we need , to make sure that other work ( like the message context PR ) make sense with this and do n't get out of sync . 
 So sorry for leaving this dangling ! I looked at this PR recently but was too clumsy to notice that my requests have long been addressed :( now , I 'd be fine with merging this , but again I 'm afraid of my clumsiness because this talks of conflicts ... my suggestion : give a day or two too , and then just go ahead and merge this in yourself . Either way , I think it 's easy to agree that we should merge this now , and if there would be small fixes needed they can still be done later . 
 Okay , based on request , merging in now . Please file new issues for further changes ! 
 Hi , we now implemented ( basic ) framers in , here are some things we noticed that might be of value for the upcoming interim : The current way the deframer is supposed to modify the octetstream is not very well specified , the deframer should probably have an interface to the connection on which it can either tell it how much of the stream it has removed or what the new stream is . If the application enables partial receives , the framer needs a way to communicate to the connection that it only deframed part of the message . If there is an error during the deframing process ( that is not caused by an incomplete message ) , the deframer needs some standardized behavior on how to indicate this . The connection should then throw an appropriate event , possibly an invalid configuration event ( as mentioned ) since both are issues the application can actively remedy . 
 Please see the proposed changes in , and review ! 
 These have been solved by the new version of framers , thanks . 
 Thanks for the text and starting the discussion ! Two high - level comments : ( 1 ) This seems to have a particular implementation too specifically in mind . Please generalize . ( 2 ) Pictures and examples would help , too . ( Will re - review after the rest of the raft of comments have been addressed.)Thank you for clarifying - now it is clear what a framer is . I still do n't like the the design of a framer being an object provided by the transport system that takes care of the buffer management , while the actual framing is done in in callbacks interacting with it . While this is a very reasonable design to minimise copying data , it really feels wrong from an OO perspective . Despite this dislike , I think we should land this PR now and discuss the design in Montreal .
Paragraph (version B):
Most Message Framers fall into one of two categories: - Header-
prefixed record formats, such as a basic Type-Length-Value (TLV)
structure - Delimeter-separated formats, such as HTTP/1.1.
Paragraph (version B):
When sending Messages, applications can add specific Message values
to a MessageContext (message-props) that is intended for a Framer.
This can be used, for example, to set the type of a Message for a TLV
format.  The namespace of values is custom for each unique Message
Framer.