This isn't intended as an actionable point right now, rather just a point of conversation. I think it's worth bringing up given that ASGI is pre-PEP at this point. (And that we might still just about be at a point where we could adapt things if we felt it worthwhile enough.)

I'm starting to wonder (again) if the double-callable structure if neccessarily a better trade-off than a single-callable. eg. the difference between:

ASGI as it stands:

class App:
    def __init__(self, scope):
        self.scope = scope

    async def __call__(self, receive, send):
        await send({
            'type': 'http.response.start',
            'status': 200,
            'headers': [
                [b'content-type', b'text/plain'],
            ]
        })
        await send({
            'type': 'http.response.body',
            'body': b'Hello, world!',
        })

An alternative interface:

async def app(scope, receive, send):
    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [
            [b'content-type', b'text/plain'],
        ]
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, world!',
    })

The double-callable does allow classes to directly implement the ASGI interface, and for class based endpoint implementations it ends up being simpler.

However it's more complex for function based endpoint implementations, for middleware implementation patterns, and for instantiate-to-configure application implementations.

In each of those cases you end up either with a closure around an inner function, or partially-bound functools.partial. Both of those cases make for less easy-to-understand concepts and more awkward flows.

E.g. A typical middleware pattern with ASGI...

class Middleware:
    def __init__(self, app, **middleware_config):
        self.app = app
        ...

    def __call__(self, scope):
        return functools.partial(self.asgi, scope=scope)

    async def asgi(self, receive, send, scope):
        ...

An alternative:

class Middleware:
    def __init__(self, app, **middleware_config):
        self.app = app
        ...

    async def __call__(self, scope, receive, send):
        ...

Similarly with instantiate-to-configure ASGI applications, you currently end up having to return a partially bound method:

StaticFiles as ASGI...

class StaticFiles:
    def __init__(self, directory):
        self.directory = directory
        ...

    def __call__(self, scope):
        return functools.partial(self.asgi, scope=scope)

    async def asgi(self, receive, send, scope):
        ...

Alternative:

class StaticFiles:
    def __init__(self, directory):
        self.directory = directory
        ...

    async def __call__(self, scope, receive, send):
        ...

The flip side with a single-callable is that you can't point directly at a class as an ASGI interface. For endpoint implementations, you end up needing to do something like this pattern instead...

class App:
    def __init__(self, scope, receive, send):
        self.scope = scope
        self.receive = receive
        self.send = send

    async def dispatch(self):
        await self.send({'type': 'http.response.start', ...})
        await self.send({'type': 'http.response.body', ...})

    @classmethod
    async def asgi(cls, scope, receive, send):
        instance = cls(scope, receive, send)
        await instance.dispatch()

# app = App.asgi

This all starts matters a little in Starlette, where ASGI is the interface all the way through - you end up with a more complex flow, and less easy-to-understand primitives. It also ends up with more indirect tracebacks.

(I noticed this in particular when considering how to improve the stack traces for 500 responses. I was hoping to delimit each frame as "Inside the middleware stack", "Inside the router", "Inside the endpoint" - that's easy to do if the traceback frames match up directly to the ASGI functions themselves, but it's not do-able if the frames are from a function that's been returned from another function.)

Anyways, not asking for any action on this neccessarily, but it's something I've been thinking over that I wanted to make visible while ASGI is still pre-PEP.

The CGI RFC provides for a REMOTE_USER variable, which holds the username of the user who has been authenticated by the front-end Web server. For a WSGI application, this can be obtained as environ["REMOTE_USER"], since a WSGI application gets access to all CGI variables. It would be nice if an ASGI application could get access to the same thing.

I am writing on behalf of my employer, sentry.io.

I am not sure whether this issue should be filed against Django or asgiref. Starting with Django 3.1, signal handlers for got_request_exception are executed with the wrong contextvars context when running as part of an ASGI request. This can be easily demonstrated by wrapping the Django ASGI app in a middleware that stores something on the context, and trying to retreive that same value from that signal handler.

This is how I became aware of Django's custom context local implementation that is shipped as part of asgiref. I understand why you do the things you do, but consider that this will break a lot of tracing tooling for Python that may only be orthogonal to Django or ASGI. The situation around context locals is already awful enough, it would be terrible if Sentry and tools like it had to implement a codepath specifically for Django 3 applications, or anything that uses asgiref.local.

I can see the following options:

1. avoid releasing Django 3.1 with whatever changes just happened that made errorhandlers execute in the wrong contextvars context. Considering that Django 3.1 is already in alpha I would at least consider this as a stopgap measure.
2. modify asgiref.sync_to_async and its inverse to "drive" contextvars if they are available such that contextvars always behave identically to asgiref.local
3. drop asgiref.local entirely and swap it out for the aiocontextvars package on PyPI, as the primary purpose of implementing asgiref.local from scratch seemed to have been to support Python 3.6. One would still have to implement 2) for this to work, but the advantage here is that aiocontextvars seems to be significantly more popular across frameworks than asgiref.local.

Those options are not mutually exclusive.

Thanks for considering.

Hi 👋 and thanks for the excellent specification! I would like to propose a change to allow looping endpoints to cleanly exit when an ASGI application shuts down.

Use Case

An ASGI application exposes an indefinitely looping endpoint using Server-Sent Events to push unidirectional data to browser clients without client polling or WebSockets.

Example

A counter event-stream sends incrementing numbers to a connected client until they disconnect, or the server shuts down.

import asyncio

state = {"should_exit": False, "counter": 0}


async def is_disconnected(receive) -> bool:
    """Check for a "http.disconnect" message"""
    receive_task = asyncio.create_task(receive())
    try:
        await asyncio.wait_for(receive_task, 1)
        message = receive_task.result()
        if message["type"] == "http.disconnect":
            print("disconnect received")
            return True
    except asyncio.TimeoutError:
        receive_task.cancel()
    return False


async def lifespan(scope, receive, send):
    """Handle lifespan events"""
    while True:
        message = await receive()
        if message["type"] == "lifespan.startup":
            print("startup received")
            await send({"type": "lifespan.startup.complete"})
        elif message["type"] == "lifespan.shutdown.notice":
            state["should_exit"] = True
            print("shutdown notice received")
        elif message["type"] == "lifespan.shutdown":
            print("shutdown received")
            await send({"type": "lifespan.shutdown.complete"})
            return


async def http(scope, receive, send):
    message = await receive()
    assert message["type"] == "http.request"

    while message.get("more_body"):
        message = await receive()

    await send(
        {
            "type": "http.response.start",
            "status": 200,
            "headers": [
                (b"cache-control", b"no-cache"),
                (b"content-type", b"text/event-stream"),
                (b"connection", b"keep-alive"),
            ],
        }
    )

    while True:
        await send(
            {
                "type": "http.response.body",
                "body": f"data: {state['counter']}\n\n".encode("utf-8"),
                "more_body": True,
            }
        )
        state["counter"] += 1
        # Check to see if the client disconnected
        if await is_disconnected(receive):
            break
        else:
            print(f"counter = {state['counter']}")

        # The lifespan.shutdown.notice event fired
        if state["should_exit"]:
            print("shutdown notice received, exiting loop")
            await send(
                {
                    "type": "http.response.body",
                    "more_body": False,
                }
            )
            break

        await asyncio.sleep(3)


async def app(scope, receive, send):
    if scope["type"] == "lifespan":
        await lifespan(scope, receive, send)
    elif scope["type"] == "http":
        await http(scope, receive, send)

Problem

With version 2.0 of the lifespan extension, this app can't terminate gracefully without going outside the spec, because the lifespan.shutdown event fires "when the server has stopped accepting connections and closed all active connections."

In most cases, firing a shutdown event after all connections have been closed is fine because requests complete and return. However, when you have looping applications that need to break on shutdown, they can't add shutdown handlers to trigger the breakout because they won't fire until the connection has exited.

Proposal

I explored the minimal changes to support this use-case. Creating a new event looks like the lowest impact way of adding support for signaling connections to gracefully exit. It limits the breakage in existing ASGI frameworks by leaving the "and closed all active connections" requirement for firing shutdown while allowing for looping endpoints to exit during application shutdown.

The path currently gets unquoted / percent-decoded, which results in unrecoverable loss of information: a request to /foo/bar is the same as /foo%2Fbar.

With WSGI there seems to exist workarounds via RAW_URI / REQUEST_URI (e.g. in gunicorn, https://github.com/etianen/aiohttp-wsgi/pull/17).

I think it would be nice to have raw_path officially in the spec. I am not sure if it should be a unicode string, or bytes (to avoid another field later on).

(I do not think that raw_uri (path + query info) is necessary, since query_string is already given as bytes)

Current spec: https://asgi.readthedocs.io/en/latest/specs/www.html#id1 (Via https://github.com/encode/uvicorn/pull/354)

In situations where an application server is happens to be returning template-rendered data, it's hugely valuable for the template and context information to be sent in the ASGI messaging, alongside the actual rendered content.

Right now we use this in Starlette, so that an ASGI-based test client is able to provide response.template and response.context information back to the user.

Formalising this, would allow us to support this kind of usage:

# This client calls directly into an ASGI app, rather than making network requests.
client = httpx.AsyncClient(app=app)

# Make the request.
response = await client.get("http://testserver/")
assert response.status_code == 200

# This information is made available through the "http.response.template" extension.
# Ensure that we're on the homepage, and that no messages are displayed.
assert response.template == "homepage.html"
assert response.context["user_messages"] == []

It's not totally obvious if an extension such as this should strictly focus on template/context info, or if there's a more general purpose "extra info" extension that ought to be considered here, but I figure it's worth opening this for discussion.

Informally, here's ~how the existing Starlette implementation looks...

# If the ASGI `http.response.template` extension is supported,
# then we can send this style of message...
{
    "type": "http.response.template",
    "template": "homepage.html",
    "context": {"user_messages": []}
}

As far as I can tell, ASGI follows the precedent set by WSGI in providing only a %-decoded string representation of the path. I believe this is a mistake. In particular, %2F is not a path separator by the URI RFC, but an application can't tell it apart from /.

I suggest either providing a raw_path byte string, or deserializing the path properly and passing it as a list.

In https://asgi.readthedocs.io/en/latest/specs/www.html#disconnect-receive-event-ws it does not say code is optional, yet it says "as per websocket spec", where code is optional ("may contain"). Later on in Close - send event it explicitly mentions that the code there is optional. In the first link should code be optional or required?

If code is optional I would be happy to submit a PR to this repo to update the docs.

This is not just a theoretical question, as we are facing a bug that may be related to this. In https://github.com/django/channels/blob/38324816c115567e198a573bc294d8345df5e8a9/channels/generic/websocket.py#L105 channels assumes that the code key exists, but in our case it doesn't exist and a KeyError is raised.

get_running_loop raise RuntimeError with any django-channels runworker command because there is no running event loop...

patch?

diff --git a/asgiref/server.py b/asgiref/server.py
index fb1c394..d1d27f4 100644
--- a/asgiref/server.py
+++ b/asgiref/server.py
@@ -56,8 +56,8 @@ class StatelessServer:
         """
         Runs the asyncio event loop with our handler loop.
         """
-        event_loop = get_running_loop()
-        asyncio.ensure_future(self.application_checker())
+        event_loop = asyncio.get_event_loop()
+        asyncio.ensure_future(self.application_checker(), loop=event_loop)
         try:
             event_loop.run_until_complete(self.handle())
         except KeyboardInterrupt:

When I upgrade from version 3.2.10 to 3.3.0(daphne:2.5.0, python:3.8.2, django:2.2.16), the server looks like hang there randomly, no error info found in access.log and asgi.log.

the supervisord.conf as follow:

[fcgi-program:om]
directory=./
socket=tcp://0.0.0.0:8000
command=daphne -u ./daphne%(process_num)d.sock --fd 0 --access-log ./logs/access.log --proxy-headers MyProject.asgi:application
numprocs=4
process_name=asgi%(process_num)d
stdout_logfile=./logs/asgi.log
redirect_stderr=true

Now, I downgrade to 3.2.10, everything is OK.

Maybe modification about thread has some bugs or something I should do to adapt it.

WWW Spec: Allow for a HTTP response before Websocket handshake acceptance

This allows HTTP responses such as 401, authentication required to be sent to the client by a framework that requires authenticated websocket connections. It would also allow for redirect responses or other more exotic framework responses.

WWW Spec: Add a server push message

This specifies how a client should indicate that a HTTP/2 server push should be initiated.

While testing, I noticed that nesting calls to async_to_sync and sync_to_async causes two calls to sync_to_async(thread_sensitive=True) to run in different threads if you call sync_to_async(thread_sensitive=False) in between those two calls. It seems that once sync_to_async is called with thread_sensitive=False, all subsequent (nested) calls with thread_sensitive=True will run on the new parent thread rather than the main thread.

Example Code

import threading
from asgiref.sync import async_to_sync, sync_to_async


def method5():
    print(f"Third call to sync_to_sync: {threading.get_ident()}")


async def method4():
    print(f"Third call to async_to_sync: {threading.get_ident()}")
    await sync_to_async(method5)()


def method3():
    print(f"Second call to sync_to_async: {threading.get_ident()}")
    async_to_sync(method4)()


async def method2():
    print(f"Second call to async_to_sync: {threading.get_ident()}")
    await sync_to_async(method3, thread_sensitive=False)()


def method1():
    print(f"First call to sync_to_async: {threading.get_ident()}")
    async_to_sync(method2)()


async def start():
    print(f"First call to async_to_sync: {threading.get_ident()}")
    await sync_to_async(method1)()

print(f"Main thread: {threading.get_ident()}")
async_to_sync(start)()

Output

Main thread: 4593313280
First call to async_to_sync: 123145368514560
First call to sync_to_async: 4593313280
Second call to async_to_sync: 123145368514560
Second call to sync_to_async: 123145373769728
Third call to async_to_sync: 123145368514560
Third call to sync_to_sync: 123145373769728

As you can see, the main thread is 4593313280. The first call to sync_to_async(thread_sensitive=True) runs on the main thread, as expected. The second call to sync_to_async(thread_sensitive=False) creates a new thread (123145373769728), as expected. However, the third and fourth calls to sync_to_async(thread_sensitive=True) run on thread 123145373769728 rather than the main thread.

This seems to contradict the behavior described in the README:

All synchronous code called through SyncToAsync and marked with thread_sensitive should run in the same thread as each other (and if the outer layer of the program is synchronous, the main thread)

Is this a bug? Or is this expected behavior, and merely a gap in the documentation?

Thanks! Charlie

I ran into a weird deadlock when writing a django async view and trying to use asyncio.wait_for() in conjunction with sync_to_async to call a sync function but timeout if it takes longer than a few seconds. Internally, wait_for() creates a couple of async tasks using create_task(). So calling create_task() on the return of sync_to_async hangs forever.

Here's a simple asgi application that reproduces the problem. I'm on asgiref 3.5.2, and I've tested this with both daphne and uvicorn. The swing between the async context and the sync context is meant to replicate the control flow used in django if you have a sync middleware in your middleware stack.

import asyncio

from asgiref.sync import sync_to_async, async_to_sync, ThreadSensitiveContext


def some_sync_function():
    print("Some_sync_function")


async def django_async_view():
    print("django_async_view")
    # Works:
    #await sync_to_async(some_sync_function)()

    # Doesn't work, times out:
    await asyncio.wait_for(sync_to_async(some_sync_function, thread_sensitive=True)(), timeout=5)

    # Also doesn't work, hangs forever:
    #await asyncio.create_task(sync_to_async(some_sync_function, thread_sensitive=True)())


def django_sync_middleware():
    print("django_sync_middleware")
    async_to_sync(django_async_view)()


async def application(scope, receive, send):

    # Gets a "Single thread executor already being used, would deadlock" error
    #await sync_to_async(django_sync_middleware, thread_sensitive=True)()

    # Gets an asyncio.TimeoutError:
    async with ThreadSensitiveContext():
        await sync_to_async(django_sync_middleware, thread_sensitive=True)()

    await send(
        {
            "type": "http.response.start",
            "status": 200,
            "headers": [
                (b"content-type", b"text/plain"),
            ],
        }
    )
    await send(
        {
            "type": "http.response.body",
            "body": b"Hello, world!",
        }
    )

Am I doing something wrong? Or is this a bug?

The spec currently defines a lot of details without any example apps (except in the lifespan section). It would be good to include basic examples, perhaps function and class versions for both full apps and middleware.

See https://github.com/pgjones/hypercorn/issues/75 where Starlette changes the scope["path"], should ASGI frameworks do this or consider the existing values immutable? (I don't think the specification says - I may work around by passing a copy to the framework)

There is already a PR open regarding this. I wanted to open this to add options to the discussion. I did the uvicorn implementation.

As stated in the other proposal PR this works a bit differently. This adds a new message type http.response.trailers and a new trailers bool property to http.response.start. IMO this simplifies the implementation.

My original POC did not account for chunked trailers but this would be easy to add with a more_trailers property similar to the more_body property.

Personally I like the more_body being set to false when the body is done and trailers being sent after. It makes more sense to me, but at the end of the day if any trailers get added I will be happy.