Add better support for request body access/manipulation

[dmontagu]

This pull request introduces a small change to APIRoute to make it easier to construct a custom app attribute in a custom subclass.

There is a lot of custom functionality that this change would simplify, but there are two especially important capabilities it adds:

• A way to get handle exceptions with access to the request body
• A way to modify the request body prior to its parsing/handling by FastAPI

I've added two sections to the "Using the Request Directly" docs showing how to use the changes in this PR to implement both of the above kinds of feature.

---

There have been many recent github issues that could be better-addressed with this capability.

Related to accessing the body in middleware/exception handlers:

• Response from the server is never received in case of using middleware. #180 accessing request body in middleware
• Access request body when reusing FastAPI's exception handlers #375 accessing request body in exception handlers
• Awaiting request body in middleware blocks the application #394 accessing request body in middleware
• Catch exception type of Exception and process body request #575 accessing request body in exception handlers
• Question about Request.Body() encode/starlette#493 accessing request body in exception handlers (using fastapi)
• Consume request body in middleware is problematic encode/starlette#495 a variety of use cases involving accessing request body in middleware (some using fastapi)

Related to modifying the request prior to handling by FastAPI:

• msgpack response if client asks for application/x-msgpack #521 support for msgpack-encoded requests
• GZipMiddleware (unzipping encoded requests) encode/starlette#644 support for gzip-encoded requests (using fastapi)

---

Quoting Tom Christie from encode/starlette#495:

"Consume request body in middleware is problematic"

Indeed. Consuming request data in middleware is problematic.
Not just to Starlette, but generally, everywhere.

On the whole you should avoid doing so if at all possible.

I think using middleware to consume the request body is the obvious (or, perhaps, "naive") way to handle these issues. But that approach is explicitly discouraged, and not supported. So I think the approach described in / supported by this PR is especially valuable.

---

(This pull request is in lieu of #568, and includes what I think is both the smallest and most important change to APIRoute from that pull request.)

[codecov]

Codecov Report

Merging #589 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff           @@
##           master   #589    +/-   ##
======================================
  Coverage     100%   100%            
======================================
  Files         258    264     +6     
  Lines        6307   6427   +120     
======================================
+ Hits         6307   6427   +120

Impacted Files	Coverage Δ
.../test_custom_request_and_route/test_tutorial003.py	100% <100%> (ø)
docs/src/custom_request_and_route/tutorial002.py	100% <100%> (ø)
docs/src/custom_request_and_route/tutorial001.py	100% <100%> (ø)
.../test_custom_request_and_route/test_tutorial002.py	100% <100%> (ø)
.../test_custom_request_and_route/test_tutorial001.py	100% <100%> (ø)
fastapi/routing.py	100% <100%> (ø)	⬆️
docs/src/custom_request_and_route/tutorial003.py	100% <100%> (ø)
... and 3 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7a504a7...b2640d3. Read the comment docs.

[tiangolo]

Awesome @dmontagu ! Thanks a lot! 🎉 🚀 🍰

I think this is sufficiently important to have its own section in the docs, so I moved it. I put it near the end as I consider this quite advanced and it could confuse newcomers.

I also added an extra example setting the route_class in a router. For that, I had to rebase from master, to include your recent fix 😅

Thanks again! 🙇‍♂️ 🌮