-
Notifications
You must be signed in to change notification settings - Fork 206
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add extensions["lifespan.state"] #354
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -46,6 +46,9 @@ The scope information passed in ``scope`` contains basic metadata: | |
* ``asgi["version"]`` (*Unicode string*) -- The version of the ASGI spec. | ||
* ``asgi["spec_version"]`` (*Unicode string*) -- The version of this spec being | ||
used. Optional; if missing defaults to ``"1.0"``. | ||
* ``state`` Optional(*dict[Unicode string, Any]*) -- An empty namespace where | ||
the application can persist state to be used when handling subsequent requests. | ||
Optional; if missing the server does not support this feature. | ||
|
||
If an exception is raised when calling the application callable with a | ||
``lifespan.startup`` message or a ``scope`` with type ``lifespan``, | ||
|
@@ -56,6 +59,38 @@ lifespan protocol. If you want to log an error that occurs during lifespan | |
startup and prevent the server from starting, then send back | ||
``lifespan.startup.failed`` instead. | ||
|
||
The ``extensions["lifespan.state"]`` dict is an empty namespace. | ||
Applications can store arbitrary data in this namespace. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This line is unclear... In the next section it's specified to store in Was this supposed to be removed? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes I think so |
||
A *shallow copy* of this dictionary will get passed into each request handler. | ||
This key will only be set if the server supports this extension. | ||
|
||
|
||
Lifespan State | ||
-------------- | ||
|
||
Applications often want to persist data from the lifespan cycle to request/response handling. | ||
For example, a database connection can be established in the lifespan cycle and persisted to | ||
the request/response cycle. | ||
The ```lifespan["state"]`` namespace provides a place to store these sorts of things. | ||
The server will ensure that a *shallow copy* of the namespace is passed into each subsequent | ||
request/response call into the application. | ||
Since the server manages the application lifespan and often the event loop as well this | ||
ensures that the application is always accessing the database connection (or other stored object) | ||
that corresponds to the right event loop and lifecycle, without using context variables, | ||
global mutable state or having to worry about references to stale/closed connections. | ||
|
||
ASGI servers that implement this feature will provide | ||
``state`` as part of the ``lifespan`` scope:: | ||
|
||
"scope": { | ||
... | ||
"state": {}, | ||
} | ||
|
||
The namespace is controlled completely by the ASGI application, the server will not | ||
interact with it other than to copy it. | ||
Nonetheless applications should be cooperative by properly naming their keys such that they | ||
will not collide with other frameworks or middleware. | ||
|
||
Startup - ``receive`` event | ||
''''''''''''''''''''''''''' | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -121,6 +121,10 @@ The *connection scope* information passed in ``scope`` contains: | |
listening port, or ``[path, None]`` where ``path`` is that of the | ||
unix socket. Optional; if missing defaults to ``None``. | ||
|
||
* ``state`` Optional(*dict[Unicode string, Any]*) -- A copy of the | ||
namespace passed into the lifespan corresponding to this request. (See :doc:`lifespan`). | ||
Optional; if missing the server does not support this feature. | ||
|
||
Comment on lines
+124
to
+127
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is missing in the |
||
Servers are responsible for handling inbound and outbound chunked transfer | ||
encodings. A request with a ``chunked`` encoded body should be automatically | ||
de-chunked by the server and presented to the application as plain body bytes; | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think the NotRequired should be included only here. This was previously mentioned on the HTTP trailers PR, and on the PR that introduced this module (I'm on my phone, difficult to provide links).
IMO either we change what we consider to be optional on those type hints, or we don't add the NotRequired.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The thing is that making it
Optional
implies that the server must set it to None, so every single server is immediately out of spec. UsingNotRequired
means that no changes are necessary to servers.