Improve docs regarding state and extensions

[Lachstec]

Motivation

Issue #2917 mentions that it should be easier to discover the documentation for Extension from the docs of State and vice versa. Indeed, Extension is very easy to miss as it is only mentioned after a couple of examples.

Solution

This PR updates the docs by

• moving the section mentioning extensions up in Router::with_state
• Adding a short mention of Extension to extract::State

Closes #2917

[lolbinarycat]

"state derived from a request" seems like a fairly narrow usecase. Extension is also useful when converting a previously stateless system into a stateful one, since changing the type of the State parameter also changes the type of the router, which can cause issues.

[mladedav]

"state derived from a request" seems like a fairly narrow usecase. Extension is also useful when converting a previously stateless system into a stateful one, since changing the type of the State parameter also changes the type of the router, which can cause issues.

I agree with how the docs are written now. Extension has been historically used for passing around application state, but users should use State for that now. It's type safe and more maintainable.

I'd recommend anyone who needs to make their application stateful to use State instead of Extension even though they will have to make more changes if they're passing around Routers. I can't think of any scenarios other than the one in docs where I'd recommend an Extension.

[lolbinarycat]

well, i genuinely could not get State to function properly when i tried. does every handler need to accept a State parameter for it to work?

[jplatte]

@lolbinarycat No, that's not required. Please open a new discussion under Q&A to get help with that.