Спецификация ASGI (интерфейс шлюза асинхронного сервера)¶

Область подключения¶

Каждое подключение пользователя к приложению ASGI приводит к созданию экземпляра этого приложения для данного подключения. Как долго он живет и какую информацию получает при создании, называется областью действия соединения.

Например, в HTTP область видимости соединения длится всего один запрос, но содержит большую часть данных запроса (кроме тела запроса HTTP, поскольку оно передается через события).

Однако в WebSocket область действия соединения длится до тех пор, пока сокет подключен. Область содержит такую информацию, как путь WebSocket, но такие детали, как входящие сообщения, передаются в виде событий.

Некоторые протоколы могут предоставлять вам область подключения с очень ограниченной информацией, потому что они инкапсулируют что-то вроде рукопожатия. Определение каждого протокола должно содержать информацию о том, как долго длится его область подключения, и какую информацию вы получите внутри нее.

Приложения не могут взаимодействовать с клиентом, когда они инициализируются и получают область подключения; они должны дождаться входа в свой цикл событий и, в зависимости от спецификации протокола, могут ждать начального сообщения об открытии.

События¶

ASGI декомпозирует протоколы на серию событий, на которые приложение должно реагировать. Для HTTP это просто два события по порядку - http.request и http.disconnect. Для чего-то вроде WebSocket это может быть больше похоже на websocket.connect, websocket.send, websocket.receive и, наконец, websocket.disconnect.

Каждое событие представляет собой dict с ключом верхнего уровня type, который содержит строку Unicode типа сообщения. Пользователи могут свободно придумывать свои собственные типы сообщений и отправлять их между экземплярами приложений для событий высокого уровня - например, приложение чата может отправлять сообщения чата с типом пользователя mychat.message. Предполагается, что приложения должны уметь обрабатывать смешанный набор событий, некоторые из которых исходят от входящего клиентского соединения, а некоторые - от других частей приложения.

Поскольку эти сообщения могут быть отправлены по сети, они должны быть сериализуемыми, и поэтому им разрешено содержать только следующие типы:

• Строки байтов

• Строки Юникода

• Целые числа (в пределах знакового 64-битного диапазона)

• Числа с плавающей точкой (в пределах диапазона двойной точности IEEE 754; без Nan или бесконечности)

• Списки (кортежи должны быть закодированы как списки)

• Dicts (ключи должны быть строками Unicode)

• Булевы

• None

Приложения¶

Приложения ASGI должны представлять собой один асинхронный вызываемый модуль:

coroutine application(scope, receive, send)

• scope: Область действия соединения, словарь, содержащий по крайней мере type ключ, определяющий входящий протокол.

• receive, ожидаемый вызываемый элемент, который будет выдавать новый словарь событий, когда он будет доступен

• send, ожидаемый вызываемый модуль, принимающий в качестве позиционного аргумента один словарь событий, который вернется, как только отправка будет завершена или соединение будет закрыто

Приложение вызывается один раз за «соединение». Определение соединения и его продолжительность диктуются спецификацией протокола. Например, для HTTP это один запрос, а для WebSocket - одно соединение WebSocket.

Как scope, так и формат сообщений, которые вы отправляете и получаете, определяются одним из прикладных протоколов. scope должен быть dict. Ключ scope["type"] всегда будет присутствовать и может быть использован для определения входящего протокола. Ключ scope["asgi"] также будет присутствовать как словарь, содержащий ключ scope["asgi"]["version"], который соответствует версии ASGI, которую реализует сервер. Если он отсутствует, версия должна быть по умолчанию "2.0".

Также может существовать версия, специфичная для конкретной спецификации, представленная как scope["asgi"]["spec_version"]. Это позволяет отдельным спецификациям протокола вносить улучшения без изменения общей версии ASGI.

Специфичные для протокола подспецификации охватывают эти области применения и форматы сообщений. Они эквивалентны спецификации ключей в дикте environ для WSGI.

Наследные приложения¶

Наследие (v2.0) ASGI-приложений определяется как вызываемое:

application(scope)

Который возвращает другой, ожидаемый callable:

coroutine application_instance(receive, send)

Значения scope, receive и send те же, что и в более новом одновызываемом приложении, но обратите внимание, что первый вызываемый элемент является синхронным.

Первый вызываемый элемент вызывается при запуске соединения, а второй вызываемый элемент вызывается сразу после этого.

Этот стиль был упразднен в версии 3.0, поскольку двухвызывная компоновка была признана ненужной. Сейчас он уже устарел, но существуют приложения, написанные в этом стиле, и поэтому важно поддерживать их.

В модуле asgiref.compatibility имеется набор совместимости, который позволяет обнаруживать устаревшие приложения и без проблем конвертировать их в новый однопротокольный стиль. Серверам рекомендуется поддерживать оба типа начиная с ASGI 3.0 и постепенно отказываться от поддержки по умолчанию с течением времени.

Спецификации протокола¶

Они описывают стандартизированную область применения и форматы сообщений для различных протоколов.

Одним общим ключом для всех диапазонов и сообщений является type - способ указать, какой тип диапазона или сообщения принимается.

В диапазонах ключ type должен быть строкой Unicode, например "http" или << 2 >>>, как определено в соответствующей спецификации протокола.

В сообщениях значение type должно быть обозначено как protocol.message_type, где protocol соответствует типу области видимости, а message_type определяется спецификацией протокола. Примеры значения сообщения type включают http.request и websocket.send.

Текущие спецификации протокола:

• HTTP and WebSocket

• Lifespan

Middleware¶

Можно иметь «промежуточное ПО» ASGI - код, который играет роль сервера и приложения, принимая область видимости и ожидаемые параметры отправки/получения, потенциально изменяя их, а затем вызывая внутреннее приложение.

Когда промежуточное ПО изменяет область видимости, оно должно сделать копию объекта области видимости, прежде чем изменить его и передать внутреннему приложению, так как в противном случае изменения могут просочиться наверх. В частности, вы не должны полагать, что копия scope, которую вы передаете приложению, является той, которую оно в итоге использует, так как на пути может стоять другое промежуточное ПО; поэтому не храните ссылку на него и не пытайтесь изменить его за пределами начального конструктора ASGI, который получает scope. Ваш единственный шанс добавить его - это сделать это до того, как вы передадите управление дочернему приложению.

Обработка ошибок¶

Если сервер получает некорректный словарь событий - например, с неизвестным type, отсутствующими ключами, которые должен иметь тип события, или с неправильными типами Python для объектов (например, строки Unicode для заголовков HTTP) - он должен поднять исключение из send, ожидаемое обратно в приложение.

Если приложение получает недопустимый словарь событий от receive, оно должно вызвать исключение.

В обоих случаях наличие дополнительных ключей в словаре событий не должно вызывать исключения. Это позволяет не нарушать спецификацию протокола с течением времени.

Серверы могут выводить ошибки, которые всплывают из запущенных экземпляров приложений, как им заблагорассудится - записывать в консоль, отправлять в syslog или использовать другие варианты - но они должны завершить экземпляр приложения и связанное с ним соединение, если это произойдет.

Обратите внимание, что сообщения, полученные сервером после закрытия соединения, не считаются ошибками. В этом случае вызываемая переменная send awaitable должна работать как no-op.

Дополнительные корутины¶

Фреймворки или приложения могут захотеть запустить дополнительные корутины в дополнение к корутине, запускаемой для каждого экземпляра приложения. Поскольку в Python 3.7 нет возможности сделать их родительскими по отношению к coroutine экземпляра, приложения должны убедиться, что все coroutine, запущенные в рамках выполнения экземпляра приложения, завершаются либо до, либо одновременно с coroutine экземпляра приложения.

Любые coroutines, которые продолжают выполняться вне этого окна, не имеют никаких гарантий относительно времени их жизни и могут быть завершены в любое время.

Расширения¶

Бывают случаи, когда серверы протоколов могут захотеть предоставить специфические для сервера расширения за пределами основной спецификации протокола ASGI, или когда изменения в спецификации тестируются перед внедрением.

Для этого случая использования мы определяем общий шаблон для extensions - именованных дополнений к спецификации протокола, которые являются необязательными, но которые, если они предоставлены сервером и понятны приложению, могут быть использованы для получения большей функциональности.

Это достигается через запись extensions в словаре scope, который сам является dict. Расширения имеют строковое имя Unicode, которое согласовывается между серверами и приложениями.

Если сервер поддерживает расширение, он должен поместить запись в словарь extensions под именем расширения, а значение этой записи должно быть dict. Серверы могут предоставить любую дополнительную информацию об области видимости, которая является частью расширения, внутри этого значения или, если расширение только указывает, что сервер принимает дополнительные события через вызываемый модуль send, оно может быть просто пустым dict.

В качестве примера представьте, что сервер протокола HTTP хочет предоставить расширение, позволяющее отправлять новое событие обратно на сервер, который пытается промыть буфер отправки по сети до уровня ОС. Он предоставляет пустую запись в словаре extensions, чтобы сигнализировать, что он может обрабатывать событие:

scope = {
    "type": "http",
    "method": "GET",
    ...
    "extensions": {
        "fullflush": {},
    },
}

Если приложение видит это, то оно знает, что может послать пользовательское событие (скажем, типа http.fullflush) через вызываемую переменную send.

Строки и Юникод¶

В этом документе и во всех подспецификациях байтовая строка относится к типу bytes в Python 3. Unicode string относится к типу str в Python 3.

В этом документе никогда не будет указано просто string - все строки являются одним из двух точных типов.

Все упомянутые ключи dict (включая ключи для scopes и events) являются строками Unicode.