Generic interface for storing per-request state.

[tomchristie]

From this: #374 (comment)

I think we should probably support a public interface for storing arbitary per-request state, within the ASGI scope.

That could either be:

1. request['whatever'] = ... - Expose the ASGI scope, and let the user handle it directly if they really need to.
2. request.scope['whatever'] = ... - Same as before, but let's move it into a different bit of public API.
3. request.state.whatever = ... - Store arbitrary state, and always keep it isolated from the rest of the namespace in the ASGI scope. (Implementation wise, store it all in a scope['state'] dictionary)

With (1) and (2) we might need to think a bit about mutability and it's implications. Eg. If the scope is modified, do we update the request.url, request.headers or whatever else it might affect? Probably we just put a disclaimer on "request.scope" gives you access to the underlying ASGI scope - make sure you've got a bit of an idea what you're doing.

Incidentally, I think I prefer (2) over the "request is dict-like" interface that we currently have.

[tomchristie]

Also note that (2) doesn't neccessarily preclude (3)

[tomchristie]

(Ie. we could expose the scope dictionary, and have a generic "some other request state" interface)

[chris-erickson]

From a beginner perspective, I prefer 3 then 2 because I know that it's my own space to mess around with and I don't have to wonder if I'm doing something dangerous like in 1. Being immutable might actually prevent it, but you don't know until you try for yourself and perhaps in multiple ways to be confident you are OK to do that. I would also imagine that it saves from potential breaking changes when I happen to have named something in a way you would like to use in Starlette.

[tomchristie]

Okay, then. So I'd be very happy to have a request.state interface added.

Implementation-wise this should just store everything into a dictionary within the ASGI scope, named "state".

Eg. request.state.time_started = time.time() --> scope["state"]["time_started"] = time.time()