HttpInput reopen/recycle cleanup

[sbordet]

Jetty version(s)
10+

Description
HttpInput.recycle() is an empty method.
Interceptors are only destroyed when HttpInput is reopened, so their resources may linger around for a long time.
It would be better to destroy interceptors ASAP in recycle() and reset the state in reopen().

Also, HttpInput.reopen() calls AsyncContentProducer.recycle() which is confusing.
Consider having both recycle() and reopen() in AsyncContentProducer and forward from HttpInput.

These 2 methods should be javadoc'ed to clarify when they are called and what actions they do.

[winne42]

These 2 methods should be javadoc'ed to clarify when they are called and what actions they do.

It would be really great to have some documentation about HttpInput's and AsyncContentProducer's methods and how they work together! Looking forward to this.

[lorban]

@winne42 HttpInput and ContentProducer are some of the most complicated pieces of Jetty's internals. They basically implement a finite-state machine that acts as a bridge between the servlet's InputStream (which obeys another finite-state machine because of async mode) and another finite-state machine in the HttpChannel layer (which abstracts away the differences between HTTP 1 and 2 and other protocols). They are considered internal APIs subject to change at any time.

Besides the existing javadoc, there are these PlantUML diagrams that document the interactions between the three layers as well as the state transitions for the most important API calls:

For async servlets:

https://github.com/eclipse/jetty.project/blob/2231e6496e87ae95c4c6db3d5c45c493ac525749/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput_async.puml

and for blocking servlets:

https://github.com/eclipse/jetty.project/blob/2231e6496e87ae95c4c6db3d5c45c493ac525749/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInput_blocking.puml

Plus a summary of the ContentProducer state machine:

https://github.com/eclipse/jetty.project/blob/2231e6496e87ae95c4c6db3d5c45c493ac525749/jetty-server/src/main/java/org/eclipse/jetty/server/HttpInputState.puml

That's pretty much all I can say succinctly on this subject, except that I would like to insist on the fact that you should not depend on any of this, except to satisfy your curiosity.

I hope this helps.

[winne42]

@lorban Thank you so much for the detailed explanation and the links! I can see that you consider this to be internal implementation details. As someone interested in Jetty interceptors I just need to understand when readFrom() and destroy() are being called and what's commonly done in each - just the info you added to the JavaDoc in #7296 <3.

(the standard LMGTFY approach doesn't work - when googling "jetty interceptor" I get zero helpful hits on the first result page, but instead two extensive guides [1, 2] how to use interceptors in Jersey... :-D)