Original text:
boundaries to function, each application layer protocol has defined its own framing.  Note that while Message Framers add the most value when placed above a protocol that otherwise does not preserve message boundaries, they can also be used with datagram- or message-based protocols.  In these

Reviewer comments:
I think this helps, but one of the confusions is the distinction between a framing to provide a message-oriented API, and the use of framers underneath that API to change the representation of messages on the wire. I wonder if some of the difficulties we've had with framers is that some of us have been using the term to represent one of these concepts, and some the other? One is the concept of a framer that accumulates data and returns an object from a call, rather than returning a byte array containing a (partial) HTTP response. That's the API-level framer. The other is the sort of framer that performs TLS encryption on the HTTP request, after has been called. This transforms data, below the API. Do we need two different terms?
NAME - personally, I always thought that Framers can do both of these things; if this wasn't clear enough before, then I think your part 1 (returning an HTTPResponse object) was clear from before, and now this PR makes it clear that they also intercept the send call to transform data afterwards. So IMHO that's just the clarification that was needed.
Sorry! Obviously I only wanted to comment, but hit the wrong button :)
I know we moved some text about framers into the implementation doc but that really doesn't seem right when I look at it now. The section about framers in the implementation doc is the only section that defines an interface which probably is already an indication that just moving this text there was not right. However, also the text in the API doc seems now incomplete. I think we should move it back and rather define some real simple examples framers in the implementation document (just a prefixed length field (as many UDP mapping use) or maybe even an example implementation for STARTTLS). Further after moving it back we could figure out if really all parts of the interface are necessary or if there would be a more minimal interface that we could use. E.g. I'm not sure about the FailConnection() call or at least I think this could need more explanation.
Also I think it would be good to the section on framers earlier in the doc. I will open a separate section to propose some restructuring (as I also think it would be good to have the connection properties earlier).
I think the real problem with framers is that we left them vague to avoid having to worry about all the implications they bring with them (which are a lot as they impact almost every stage of the life of a connection) but also to not limit what implementations can do with them by making them very rigid. But I do agree that the text in API feels somewhat incomplete. Maybe one solution would be to explain what a framer should at least be able to do in the interface draft without specifying the actual API that is in implementation. I think we all agree at when a framer should be able to interact with the connection just not how that interaction is supposed to look like (as that is highly implementation specific).
I disagree that we should move the text back into the API document, since the group was very clear before that the details should be moved to implementation. The boundary we defined was to leave in the API: (a) the definition of what a framer is and why it's used and (b) the interface an application uses to add a framer to the connection. The API text should be complete with regards to how a user of a framer performs actions. What specific text would we want to add here?
First as I say that's the only piece of additional interface we define in the implementation draft which already is a sign that it's maybe not ideal. But for the API draft the part of how a framer interact with the transport is really unclear and looking at the part of interface, that now defined in the implementation doc, makes it really clear. I disagree that this part of the interface can or should be left to the implementation. The fact that you have to call the framer before you start any transmission and the events a framer should be aware of are generic and nothing implementation specific.
In the implementation draft we say: "A Message Framer is primarily defined by the set of code that handles events for a framer implementation" My assumption is that a custom framer implementation could be part of the application logic and therefore we need to define this interface as well. However looking at the implementation draft I guess I now confused myself about how this actually works. Why is the sending logic asynchronous? Isn't this something that happens iteratively when the application calls send(). How would that actually work? I thought the application could just call URL() and then the connection could call URL() and that would simply return a modified message... can you give an example for sending and receiving based on the interfaces currently defined in the implementation draft? Also please note that while I think the interface definition belongs in API draft, however, there are comments about copying and curser handling which should/could probably say in the implementation draft.
Interim: Add to -interface: Explain that framer(s) is in between the rest of the protocol stack and the application Intercepts calls to start/stop and send/receive And just leave as is, and have another framers document in the future once we get more details.
I think it'll be helpful to be a bit clearer on the timing here, see comment.Thanks a lot for doing this - to me, this looks really good. It makes things much clearer for readers of this document.I think this should clarify it, thanks!

Revised text:
boundaries to function, each application layer protocol has defined its own framing. <ins> To use a Message Framer, the application adds it to its Preconnection object.  Then, the Message Framer can intercept all calls to Send() or Receive() on a Connection to add Message semantics, in addition to interacting with the setup and teardown of the Connection.  A Framer can start sending data before the application sends data if the framing protocol requires a prefix or handshake (see RFC8229 for an example of such a framing protocol). </ins> Note that while Message Framers add the most value when placed above a protocol that otherwise does not preserve message boundaries, they can also be used with datagram- or message-based protocols.  In these