asgi-listeners 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- asgi_listeners-0.0.1/PKG-INFO +220 -0
- asgi_listeners-0.0.1/README.md +212 -0
- asgi_listeners-0.0.1/pyproject.toml +60 -0
- asgi_listeners-0.0.1/setup.cfg +4 -0
- asgi_listeners-0.0.1/src/asgi_listeners/__init__.py +17 -0
- asgi_listeners-0.0.1/src/asgi_listeners/config.py +67 -0
- asgi_listeners-0.0.1/src/asgi_listeners/lifespan.py +121 -0
- asgi_listeners-0.0.1/src/asgi_listeners/listeners.py +63 -0
- asgi_listeners-0.0.1/src/asgi_listeners/py.typed +0 -0
- asgi_listeners-0.0.1/src/asgi_listeners/routing.py +44 -0
- asgi_listeners-0.0.1/src/asgi_listeners/server.py +323 -0
- asgi_listeners-0.0.1/src/asgi_listeners/types.py +10 -0
- asgi_listeners-0.0.1/src/asgi_listeners.egg-info/PKG-INFO +220 -0
- asgi_listeners-0.0.1/src/asgi_listeners.egg-info/SOURCES.txt +20 -0
- asgi_listeners-0.0.1/src/asgi_listeners.egg-info/dependency_links.txt +1 -0
- asgi_listeners-0.0.1/src/asgi_listeners.egg-info/requires.txt +1 -0
- asgi_listeners-0.0.1/src/asgi_listeners.egg-info/top_level.txt +1 -0
- asgi_listeners-0.0.1/tests/test_config.py +92 -0
- asgi_listeners-0.0.1/tests/test_listeners.py +381 -0
- asgi_listeners-0.0.1/tests/test_routing.py +60 -0
- asgi_listeners-0.0.1/tests/test_server.py +555 -0
- asgi_listeners-0.0.1/tests/test_signals.py +95 -0
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: asgi-listeners
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Serve named ASGI application listeners with coordinated startup and shutdown.
|
|
5
|
+
Requires-Python: >=3.11
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
Requires-Dist: uvicorn<0.53,>=0.52.1
|
|
8
|
+
|
|
9
|
+
# asgi-listeners
|
|
10
|
+
|
|
11
|
+
Запуск ASGI-приложений на именованных TCP listener в одном процессе Uvicorn.
|
|
12
|
+
Число listener задаёт приложение: один, три или больше. Python 3.11+,
|
|
13
|
+
Uvicorn `>=0.52.1,<0.53`; FastAPI и DI-фреймворк не входят в runtime-зависимости.
|
|
14
|
+
|
|
15
|
+
[Репозиторий](https://gitlab.2a2i.org/intelligent-distributed-engine-for-ai-models/libraries/asgi-listeners).
|
|
16
|
+
До первого релиза библиотеку можно установить из Git:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
uv add 'asgi-listeners @ git+https://gitlab.2a2i.org/intelligent-distributed-engine-for-ai-models/libraries/asgi-listeners.git@dev'
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Приложение и адрес в одном объявлении
|
|
23
|
+
|
|
24
|
+
```python
|
|
25
|
+
from fastapi import FastAPI
|
|
26
|
+
from asgi_listeners import LifespanMode, Listener, Server, ServerConfig
|
|
27
|
+
|
|
28
|
+
api = Listener(name="api", app=FastAPI(), port=8000)
|
|
29
|
+
metrics = Listener(name="metrics", app=FastAPI(), port=9000)
|
|
30
|
+
admin = Listener(name="admin", app=FastAPI(), host="127.0.0.1", port=9001)
|
|
31
|
+
|
|
32
|
+
@api.app.get("/ping")
|
|
33
|
+
async def ping():
|
|
34
|
+
return {"status": "ok"}
|
|
35
|
+
|
|
36
|
+
server = Server(
|
|
37
|
+
listeners=[api, metrics, admin],
|
|
38
|
+
config=ServerConfig(graceful_timeout=60),
|
|
39
|
+
)
|
|
40
|
+
await server.serve()
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`Listener` связывает `app`, `host` и `port` в одном объекте. Его можно объявить
|
|
44
|
+
рядом с приложением или передать существующую factory:
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
listener = Listener(name="api", app=create_app(), host="0.0.0.0", port=settings.port)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Конкретный тип `app` сохраняется: `Listener(app=FastAPI(), ...).app` имеет тип
|
|
51
|
+
FastAPI, поэтому декораторы и автодополнение работают без cast. Сам сервер
|
|
52
|
+
принимает любой ASGI callable. Сетевой адрес относится к listener; прикладная
|
|
53
|
+
factory может оставаться независимой от конфигурации запуска.
|
|
54
|
+
|
|
55
|
+
## Объекты интерфейса
|
|
56
|
+
|
|
57
|
+
| Объект | Назначение |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `Listener(name=..., app=..., port=..., host="127.0.0.1")` | Неизменяемая привязка приложения к адресу |
|
|
60
|
+
| `ServerConfig(...)` | Неизменяемые настройки runtime, без приложений и портов |
|
|
61
|
+
| `Server(listeners=[...], config=...)` | Однократно запускаемый сервер; config необязателен |
|
|
62
|
+
| `BoundListener(name=..., host=..., port=...)` | Фактический адрес после bind |
|
|
63
|
+
| `server.addresses["api"]` | Фактический адрес конкретного listener |
|
|
64
|
+
|
|
65
|
+
DTO используют неизменяемые dataclass и именованные аргументы.
|
|
66
|
+
Они проверяют значения при создании и не читают env. `Server` сохраняет
|
|
67
|
+
неизменяемый снимок переданного списка listener.
|
|
68
|
+
|
|
69
|
+
Имена должны быть непустыми и уникальными. Host задаётся IPv4/IPv6-адресом
|
|
70
|
+
без scope ID; hostname не поддерживается. Пересекающиеся bind запрещены,
|
|
71
|
+
например `0.0.0.0:8000` вместе с `127.0.0.1:8000`. Один номер порта разрешён
|
|
72
|
+
на разных непересекающихся интерфейсах. IPv6 listener использует IPV6_V6ONLY.
|
|
73
|
+
|
|
74
|
+
`port=0` просит ОС выделить свободный порт. После bind `server.addresses`
|
|
75
|
+
содержит read-only mapping имён в `BoundListener`, с фактическими ненулевыми
|
|
76
|
+
портами. До bind обращение к этому свойству вызывает RuntimeError.
|
|
77
|
+
|
|
78
|
+
## Lifespan и общие ресурсы
|
|
79
|
+
|
|
80
|
+
Режим задаётся enum `LifespanMode` в параметре `Server(lifespan_mode=...)`:
|
|
81
|
+
|
|
82
|
+
| Режим | Поведение |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| `LifespanMode.ALL` | По умолчанию: lifespan каждого уникального приложения, отдельный state |
|
|
85
|
+
| `LifespanMode.FIRST` | Только lifespan первого listener в списке, его state доступен всем listener |
|
|
86
|
+
|
|
87
|
+
В `ALL` сервер выполняет lifespan каждого **уникального объекта
|
|
88
|
+
приложения**. Startup идёт в порядке первого появления приложений в списке,
|
|
89
|
+
shutdown — в обратном порядке. Один объект можно привязать к нескольким
|
|
90
|
+
listener: его lifespan выполняется один раз.
|
|
91
|
+
|
|
92
|
+
Каждое приложение получает собственный lifespan state. В каждый request
|
|
93
|
+
передаётся поверхностная копия состояния соответствующего приложения.
|
|
94
|
+
Объекты внутри state сохраняют свою идентичность, request-local ключи
|
|
95
|
+
не переносятся в соседние запросы.
|
|
96
|
+
|
|
97
|
+
Для приложений с единым владельцем общих ресурсов выберите `FIRST`:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
server = Server(
|
|
101
|
+
listeners=[api, metrics, admin],
|
|
102
|
+
lifespan_mode=LifespanMode.FIRST,
|
|
103
|
+
)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
В этом режиме выполняется только lifespan приложения `listeners[0]`.
|
|
107
|
+
Его state доступен запросам всех listener; lifespan остальных приложений
|
|
108
|
+
не запускается. Владельца определяет порядок переданного списка; имена
|
|
109
|
+
listener используются для диагностики и доступа к адресам. Перестановка
|
|
110
|
+
первого элемента меняет владельца. Порядок резервирования сокетов на выбор
|
|
111
|
+
lifespan не влияет.
|
|
112
|
+
|
|
113
|
+
Параметр принимает член enum. Строку из конфигурации можно явно преобразовать
|
|
114
|
+
через `LifespanMode(value)`.
|
|
115
|
+
|
|
116
|
+
Библиотека не создаёт и не копирует DI-контейнеры или `app.state`.
|
|
117
|
+
Их подключает composition root приложения. Ресурсы также могут иметь
|
|
118
|
+
внешнего владельца:
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
async with application_resources() as resources:
|
|
122
|
+
server = Server(listeners=create_listeners(resources))
|
|
123
|
+
await server.serve()
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Если bootstrap заранее создал ресурсы, которые закрывает первый lifespan,
|
|
127
|
+
в режиме `FIRST` можно передать `startup_cleanup=container.close`.
|
|
128
|
+
Этот callback вызывается только до передачи startup-события владельцу,
|
|
129
|
+
включая ошибку bind или построения middleware. После передачи события
|
|
130
|
+
владелец обязан закрыть свои ресурсы сам. В режиме `ALL` callback
|
|
131
|
+
запрещён: для независимых приложений используйте их lifespan или внешний
|
|
132
|
+
контекст, явно владеющий ресурсами.
|
|
133
|
+
|
|
134
|
+
Поддержка ASGI lifespan обязательна для управляемых приложений. FastAPI
|
|
135
|
+
предоставляет её и без пользовательского lifespan.
|
|
136
|
+
|
|
137
|
+
## Запуск и остановка
|
|
138
|
+
|
|
139
|
+
Сначала резервируются все сокеты, затем запускаются приложения. Запросы
|
|
140
|
+
принимаются после успешного startup всех управляемых приложений. Ошибка
|
|
141
|
+
любого bind освобождает предыдущие сокеты; ошибка startup закрывает уже
|
|
142
|
+
запущенные приложения. Ошибка одного shutdown не пропускает cleanup остальных.
|
|
143
|
+
|
|
144
|
+
Маршрутизация использует локальные IP-адрес и порт соединения, учитывая
|
|
145
|
+
wildcard bind. Заголовки `Host` и forwarded headers не выбирают приложение.
|
|
146
|
+
|
|
147
|
+
| Метод / свойство | Поведение |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| `await server.serve()` | Работает до остановки; ошибки передаёт вызывающему коду |
|
|
150
|
+
| `server.request_shutdown()` | Запрашивает graceful shutdown из потока event loop |
|
|
151
|
+
| `server.should_exit = True` | Интерфейс для внешнего supervisor |
|
|
152
|
+
| `server.started` | Transport запущен; после завершения serve — False |
|
|
153
|
+
|
|
154
|
+
Один экземпляр используется один раз; запрос остановки нельзя отозвать.
|
|
155
|
+
При остановке закрываются listener, завершаются или отменяются запросы,
|
|
156
|
+
ожидаются их finalizers, затем закрываются application lifespan.
|
|
157
|
+
Отмена `serve()` выполняет cleanup и передаёт CancelledError вызывающему коду.
|
|
158
|
+
|
|
159
|
+
В главном потоке runtime перехватывает SIGINT/SIGTERM на startup, serving
|
|
160
|
+
и cleanup. После сигнала `serve()` возвращается, позволяя закрыть внешние
|
|
161
|
+
контексты; предыдущие handlers восстанавливаются. Библиотека не вызывает
|
|
162
|
+
sys.exit и не отправляет сигнал повторно. Для внешнего владельца сигналов
|
|
163
|
+
задайте `handle_signals=False`.
|
|
164
|
+
|
|
165
|
+
## Настройки runtime
|
|
166
|
+
|
|
167
|
+
| ServerConfig | По умолчанию | Назначение |
|
|
168
|
+
| --- | --- | --- |
|
|
169
|
+
| `startup_timeout` | 30 с | Общий бюджет startup всех приложений |
|
|
170
|
+
| `graceful_timeout` | 30 с, целое число | Завершение активных запросов средствами Uvicorn |
|
|
171
|
+
| `shutdown_timeout` | 30 с | Бюджет ожидания finalizers запросов и отдельный бюджет каждого application shutdown |
|
|
172
|
+
| `keep_alive_timeout` | 5 с | HTTP keep-alive |
|
|
173
|
+
| `backlog` | 2048 | Очередь соединений |
|
|
174
|
+
| `limit_concurrency` | None | Общий лимит Uvicorn для всех listener |
|
|
175
|
+
| `log_level` | None | Уровень логирования Uvicorn |
|
|
176
|
+
| `access_log` | False | Access log Uvicorn |
|
|
177
|
+
| `proxy_headers` | False | Обработка forwarded headers |
|
|
178
|
+
| `forwarded_allow_ips` | () | Явно доверенные peers; обязательны при proxy_headers=True |
|
|
179
|
+
| `handle_signals` | True | Обработка SIGINT/SIGTERM в главном потоке |
|
|
180
|
+
|
|
181
|
+
Конфигурацию logging задаёт приложение: runtime использует `log_config=None`.
|
|
182
|
+
Пользовательские coroutine должны сотрудничать с отменой. Асинхронный cleanup
|
|
183
|
+
в AnyIO cancel scopes, включая streaming-генераторы Starlette, должен быть
|
|
184
|
+
защищён от отмены самим приложением. Внешний grace period должен учитывать
|
|
185
|
+
drain, request finalizers и последовательное закрытие всех lifespan.
|
|
186
|
+
|
|
187
|
+
Все listener используют один процесс, event loop и Uvicorn server state;
|
|
188
|
+
лимиты CPU, памяти и concurrency общие. Runtime использует `Server.serve()`
|
|
189
|
+
и transport hooks Uvicorn без вызова приватного `_serve()`.
|
|
190
|
+
TLS, process workers, reload supervisor, унаследованные и Unix sockets
|
|
191
|
+
в текущий интерфейс не входят.
|
|
192
|
+
|
|
193
|
+
## Разработка и релиз
|
|
194
|
+
|
|
195
|
+
```sh
|
|
196
|
+
uv sync --locked
|
|
197
|
+
make check
|
|
198
|
+
uv run python examples/fastapi_app.py
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
Пример запускает три приложения: api `127.0.0.1:8000`, metrics
|
|
202
|
+
`127.0.0.1:8001`, admin `127.0.0.1:8002`, с режимом `LifespanMode.FIRST`.
|
|
203
|
+
Тесты используют локальные TCP-сокеты и дочерние процессы для сигналов.
|
|
204
|
+
CI проверяет Python 3.11–3.14, минимальные Uvicorn 0.52.1 и FastAPI 0.141.1,
|
|
205
|
+
покрытие от 80%, содержимое wheel/sdist и независимый импорт wheel.
|
|
206
|
+
|
|
207
|
+
Версия вычисляется из Git-тегов через `setuptools-scm`. Для релиза создайте
|
|
208
|
+
тег, например `v0.1.0`: версия пакета будет `0.1.0`. Вручную менять
|
|
209
|
+
`pyproject.toml` и `uv.lock` для выпуска версии не требуется.
|
|
210
|
+
В tag pipeline GitLab передаёт тег через
|
|
211
|
+
`SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ASGI_LISTENERS`, поэтому сборка работает
|
|
212
|
+
и в slim-образе без Git CLI. CI проверяет соответствие версий собранных wheel
|
|
213
|
+
и sdist тегу перед публикацией. Branch pipeline выполняет проверки; tag
|
|
214
|
+
pipeline дополнительно собирает пакет и публикует его в PyPI через Twine.
|
|
215
|
+
Между тегами Git checkout получает dev-версию. Для снимка исходников без
|
|
216
|
+
Git-метаданных используется `0.0.0`; официальный sdist сохраняет версию релиза.
|
|
217
|
+
Для публикации нужны CI variables `TWINE_USERNAME=__token__` и
|
|
218
|
+
`TWINE_PASSWORD`; `TWINE_REPOSITORY_URL` позволяет выбрать другой registry.
|
|
219
|
+
|
|
220
|
+
Обоснование интерфейса: [docs/design.md](docs/design.md).
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
# asgi-listeners
|
|
2
|
+
|
|
3
|
+
Запуск ASGI-приложений на именованных TCP listener в одном процессе Uvicorn.
|
|
4
|
+
Число listener задаёт приложение: один, три или больше. Python 3.11+,
|
|
5
|
+
Uvicorn `>=0.52.1,<0.53`; FastAPI и DI-фреймворк не входят в runtime-зависимости.
|
|
6
|
+
|
|
7
|
+
[Репозиторий](https://gitlab.2a2i.org/intelligent-distributed-engine-for-ai-models/libraries/asgi-listeners).
|
|
8
|
+
До первого релиза библиотеку можно установить из Git:
|
|
9
|
+
|
|
10
|
+
```sh
|
|
11
|
+
uv add 'asgi-listeners @ git+https://gitlab.2a2i.org/intelligent-distributed-engine-for-ai-models/libraries/asgi-listeners.git@dev'
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Приложение и адрес в одном объявлении
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
from fastapi import FastAPI
|
|
18
|
+
from asgi_listeners import LifespanMode, Listener, Server, ServerConfig
|
|
19
|
+
|
|
20
|
+
api = Listener(name="api", app=FastAPI(), port=8000)
|
|
21
|
+
metrics = Listener(name="metrics", app=FastAPI(), port=9000)
|
|
22
|
+
admin = Listener(name="admin", app=FastAPI(), host="127.0.0.1", port=9001)
|
|
23
|
+
|
|
24
|
+
@api.app.get("/ping")
|
|
25
|
+
async def ping():
|
|
26
|
+
return {"status": "ok"}
|
|
27
|
+
|
|
28
|
+
server = Server(
|
|
29
|
+
listeners=[api, metrics, admin],
|
|
30
|
+
config=ServerConfig(graceful_timeout=60),
|
|
31
|
+
)
|
|
32
|
+
await server.serve()
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`Listener` связывает `app`, `host` и `port` в одном объекте. Его можно объявить
|
|
36
|
+
рядом с приложением или передать существующую factory:
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
listener = Listener(name="api", app=create_app(), host="0.0.0.0", port=settings.port)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Конкретный тип `app` сохраняется: `Listener(app=FastAPI(), ...).app` имеет тип
|
|
43
|
+
FastAPI, поэтому декораторы и автодополнение работают без cast. Сам сервер
|
|
44
|
+
принимает любой ASGI callable. Сетевой адрес относится к listener; прикладная
|
|
45
|
+
factory может оставаться независимой от конфигурации запуска.
|
|
46
|
+
|
|
47
|
+
## Объекты интерфейса
|
|
48
|
+
|
|
49
|
+
| Объект | Назначение |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `Listener(name=..., app=..., port=..., host="127.0.0.1")` | Неизменяемая привязка приложения к адресу |
|
|
52
|
+
| `ServerConfig(...)` | Неизменяемые настройки runtime, без приложений и портов |
|
|
53
|
+
| `Server(listeners=[...], config=...)` | Однократно запускаемый сервер; config необязателен |
|
|
54
|
+
| `BoundListener(name=..., host=..., port=...)` | Фактический адрес после bind |
|
|
55
|
+
| `server.addresses["api"]` | Фактический адрес конкретного listener |
|
|
56
|
+
|
|
57
|
+
DTO используют неизменяемые dataclass и именованные аргументы.
|
|
58
|
+
Они проверяют значения при создании и не читают env. `Server` сохраняет
|
|
59
|
+
неизменяемый снимок переданного списка listener.
|
|
60
|
+
|
|
61
|
+
Имена должны быть непустыми и уникальными. Host задаётся IPv4/IPv6-адресом
|
|
62
|
+
без scope ID; hostname не поддерживается. Пересекающиеся bind запрещены,
|
|
63
|
+
например `0.0.0.0:8000` вместе с `127.0.0.1:8000`. Один номер порта разрешён
|
|
64
|
+
на разных непересекающихся интерфейсах. IPv6 listener использует IPV6_V6ONLY.
|
|
65
|
+
|
|
66
|
+
`port=0` просит ОС выделить свободный порт. После bind `server.addresses`
|
|
67
|
+
содержит read-only mapping имён в `BoundListener`, с фактическими ненулевыми
|
|
68
|
+
портами. До bind обращение к этому свойству вызывает RuntimeError.
|
|
69
|
+
|
|
70
|
+
## Lifespan и общие ресурсы
|
|
71
|
+
|
|
72
|
+
Режим задаётся enum `LifespanMode` в параметре `Server(lifespan_mode=...)`:
|
|
73
|
+
|
|
74
|
+
| Режим | Поведение |
|
|
75
|
+
| --- | --- |
|
|
76
|
+
| `LifespanMode.ALL` | По умолчанию: lifespan каждого уникального приложения, отдельный state |
|
|
77
|
+
| `LifespanMode.FIRST` | Только lifespan первого listener в списке, его state доступен всем listener |
|
|
78
|
+
|
|
79
|
+
В `ALL` сервер выполняет lifespan каждого **уникального объекта
|
|
80
|
+
приложения**. Startup идёт в порядке первого появления приложений в списке,
|
|
81
|
+
shutdown — в обратном порядке. Один объект можно привязать к нескольким
|
|
82
|
+
listener: его lifespan выполняется один раз.
|
|
83
|
+
|
|
84
|
+
Каждое приложение получает собственный lifespan state. В каждый request
|
|
85
|
+
передаётся поверхностная копия состояния соответствующего приложения.
|
|
86
|
+
Объекты внутри state сохраняют свою идентичность, request-local ключи
|
|
87
|
+
не переносятся в соседние запросы.
|
|
88
|
+
|
|
89
|
+
Для приложений с единым владельцем общих ресурсов выберите `FIRST`:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
server = Server(
|
|
93
|
+
listeners=[api, metrics, admin],
|
|
94
|
+
lifespan_mode=LifespanMode.FIRST,
|
|
95
|
+
)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
В этом режиме выполняется только lifespan приложения `listeners[0]`.
|
|
99
|
+
Его state доступен запросам всех listener; lifespan остальных приложений
|
|
100
|
+
не запускается. Владельца определяет порядок переданного списка; имена
|
|
101
|
+
listener используются для диагностики и доступа к адресам. Перестановка
|
|
102
|
+
первого элемента меняет владельца. Порядок резервирования сокетов на выбор
|
|
103
|
+
lifespan не влияет.
|
|
104
|
+
|
|
105
|
+
Параметр принимает член enum. Строку из конфигурации можно явно преобразовать
|
|
106
|
+
через `LifespanMode(value)`.
|
|
107
|
+
|
|
108
|
+
Библиотека не создаёт и не копирует DI-контейнеры или `app.state`.
|
|
109
|
+
Их подключает composition root приложения. Ресурсы также могут иметь
|
|
110
|
+
внешнего владельца:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
async with application_resources() as resources:
|
|
114
|
+
server = Server(listeners=create_listeners(resources))
|
|
115
|
+
await server.serve()
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Если bootstrap заранее создал ресурсы, которые закрывает первый lifespan,
|
|
119
|
+
в режиме `FIRST` можно передать `startup_cleanup=container.close`.
|
|
120
|
+
Этот callback вызывается только до передачи startup-события владельцу,
|
|
121
|
+
включая ошибку bind или построения middleware. После передачи события
|
|
122
|
+
владелец обязан закрыть свои ресурсы сам. В режиме `ALL` callback
|
|
123
|
+
запрещён: для независимых приложений используйте их lifespan или внешний
|
|
124
|
+
контекст, явно владеющий ресурсами.
|
|
125
|
+
|
|
126
|
+
Поддержка ASGI lifespan обязательна для управляемых приложений. FastAPI
|
|
127
|
+
предоставляет её и без пользовательского lifespan.
|
|
128
|
+
|
|
129
|
+
## Запуск и остановка
|
|
130
|
+
|
|
131
|
+
Сначала резервируются все сокеты, затем запускаются приложения. Запросы
|
|
132
|
+
принимаются после успешного startup всех управляемых приложений. Ошибка
|
|
133
|
+
любого bind освобождает предыдущие сокеты; ошибка startup закрывает уже
|
|
134
|
+
запущенные приложения. Ошибка одного shutdown не пропускает cleanup остальных.
|
|
135
|
+
|
|
136
|
+
Маршрутизация использует локальные IP-адрес и порт соединения, учитывая
|
|
137
|
+
wildcard bind. Заголовки `Host` и forwarded headers не выбирают приложение.
|
|
138
|
+
|
|
139
|
+
| Метод / свойство | Поведение |
|
|
140
|
+
| --- | --- |
|
|
141
|
+
| `await server.serve()` | Работает до остановки; ошибки передаёт вызывающему коду |
|
|
142
|
+
| `server.request_shutdown()` | Запрашивает graceful shutdown из потока event loop |
|
|
143
|
+
| `server.should_exit = True` | Интерфейс для внешнего supervisor |
|
|
144
|
+
| `server.started` | Transport запущен; после завершения serve — False |
|
|
145
|
+
|
|
146
|
+
Один экземпляр используется один раз; запрос остановки нельзя отозвать.
|
|
147
|
+
При остановке закрываются listener, завершаются или отменяются запросы,
|
|
148
|
+
ожидаются их finalizers, затем закрываются application lifespan.
|
|
149
|
+
Отмена `serve()` выполняет cleanup и передаёт CancelledError вызывающему коду.
|
|
150
|
+
|
|
151
|
+
В главном потоке runtime перехватывает SIGINT/SIGTERM на startup, serving
|
|
152
|
+
и cleanup. После сигнала `serve()` возвращается, позволяя закрыть внешние
|
|
153
|
+
контексты; предыдущие handlers восстанавливаются. Библиотека не вызывает
|
|
154
|
+
sys.exit и не отправляет сигнал повторно. Для внешнего владельца сигналов
|
|
155
|
+
задайте `handle_signals=False`.
|
|
156
|
+
|
|
157
|
+
## Настройки runtime
|
|
158
|
+
|
|
159
|
+
| ServerConfig | По умолчанию | Назначение |
|
|
160
|
+
| --- | --- | --- |
|
|
161
|
+
| `startup_timeout` | 30 с | Общий бюджет startup всех приложений |
|
|
162
|
+
| `graceful_timeout` | 30 с, целое число | Завершение активных запросов средствами Uvicorn |
|
|
163
|
+
| `shutdown_timeout` | 30 с | Бюджет ожидания finalizers запросов и отдельный бюджет каждого application shutdown |
|
|
164
|
+
| `keep_alive_timeout` | 5 с | HTTP keep-alive |
|
|
165
|
+
| `backlog` | 2048 | Очередь соединений |
|
|
166
|
+
| `limit_concurrency` | None | Общий лимит Uvicorn для всех listener |
|
|
167
|
+
| `log_level` | None | Уровень логирования Uvicorn |
|
|
168
|
+
| `access_log` | False | Access log Uvicorn |
|
|
169
|
+
| `proxy_headers` | False | Обработка forwarded headers |
|
|
170
|
+
| `forwarded_allow_ips` | () | Явно доверенные peers; обязательны при proxy_headers=True |
|
|
171
|
+
| `handle_signals` | True | Обработка SIGINT/SIGTERM в главном потоке |
|
|
172
|
+
|
|
173
|
+
Конфигурацию logging задаёт приложение: runtime использует `log_config=None`.
|
|
174
|
+
Пользовательские coroutine должны сотрудничать с отменой. Асинхронный cleanup
|
|
175
|
+
в AnyIO cancel scopes, включая streaming-генераторы Starlette, должен быть
|
|
176
|
+
защищён от отмены самим приложением. Внешний grace period должен учитывать
|
|
177
|
+
drain, request finalizers и последовательное закрытие всех lifespan.
|
|
178
|
+
|
|
179
|
+
Все listener используют один процесс, event loop и Uvicorn server state;
|
|
180
|
+
лимиты CPU, памяти и concurrency общие. Runtime использует `Server.serve()`
|
|
181
|
+
и transport hooks Uvicorn без вызова приватного `_serve()`.
|
|
182
|
+
TLS, process workers, reload supervisor, унаследованные и Unix sockets
|
|
183
|
+
в текущий интерфейс не входят.
|
|
184
|
+
|
|
185
|
+
## Разработка и релиз
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
uv sync --locked
|
|
189
|
+
make check
|
|
190
|
+
uv run python examples/fastapi_app.py
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Пример запускает три приложения: api `127.0.0.1:8000`, metrics
|
|
194
|
+
`127.0.0.1:8001`, admin `127.0.0.1:8002`, с режимом `LifespanMode.FIRST`.
|
|
195
|
+
Тесты используют локальные TCP-сокеты и дочерние процессы для сигналов.
|
|
196
|
+
CI проверяет Python 3.11–3.14, минимальные Uvicorn 0.52.1 и FastAPI 0.141.1,
|
|
197
|
+
покрытие от 80%, содержимое wheel/sdist и независимый импорт wheel.
|
|
198
|
+
|
|
199
|
+
Версия вычисляется из Git-тегов через `setuptools-scm`. Для релиза создайте
|
|
200
|
+
тег, например `v0.1.0`: версия пакета будет `0.1.0`. Вручную менять
|
|
201
|
+
`pyproject.toml` и `uv.lock` для выпуска версии не требуется.
|
|
202
|
+
В tag pipeline GitLab передаёт тег через
|
|
203
|
+
`SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ASGI_LISTENERS`, поэтому сборка работает
|
|
204
|
+
и в slim-образе без Git CLI. CI проверяет соответствие версий собранных wheel
|
|
205
|
+
и sdist тегу перед публикацией. Branch pipeline выполняет проверки; tag
|
|
206
|
+
pipeline дополнительно собирает пакет и публикует его в PyPI через Twine.
|
|
207
|
+
Между тегами Git checkout получает dev-версию. Для снимка исходников без
|
|
208
|
+
Git-метаданных используется `0.0.0`; официальный sdist сохраняет версию релиза.
|
|
209
|
+
Для публикации нужны CI variables `TWINE_USERNAME=__token__` и
|
|
210
|
+
`TWINE_PASSWORD`; `TWINE_REPOSITORY_URL` позволяет выбрать другой registry.
|
|
211
|
+
|
|
212
|
+
Обоснование интерфейса: [docs/design.md](docs/design.md).
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "asgi-listeners"
|
|
3
|
+
dynamic = ["version"]
|
|
4
|
+
description = "Serve named ASGI application listeners with coordinated startup and shutdown."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
dependencies = ["uvicorn>=0.52.1,<0.53"]
|
|
8
|
+
|
|
9
|
+
[dependency-groups]
|
|
10
|
+
dev = [
|
|
11
|
+
"fastapi>=0.141.1,<1",
|
|
12
|
+
"httpx>=0.28.1,<0.29",
|
|
13
|
+
"pytest>=9,<10",
|
|
14
|
+
"pytest-asyncio>=1.4,<2",
|
|
15
|
+
"pytest-cov>=6,<8",
|
|
16
|
+
"ruff>=0.16,<0.17",
|
|
17
|
+
"mypy>=2.3,<3",
|
|
18
|
+
"packaging>=26,<27",
|
|
19
|
+
]
|
|
20
|
+
|
|
21
|
+
[build-system]
|
|
22
|
+
requires = ["setuptools>=64", "setuptools-scm>=8"]
|
|
23
|
+
build-backend = "setuptools.build_meta"
|
|
24
|
+
|
|
25
|
+
[tool.setuptools_scm]
|
|
26
|
+
# Keep installs from source snapshots usable when Git metadata is unavailable.
|
|
27
|
+
# Tagged CI builds provide the version through the distribution-specific override.
|
|
28
|
+
fallback_version = "0.0.0"
|
|
29
|
+
|
|
30
|
+
[tool.setuptools.packages.find]
|
|
31
|
+
where = ["src"]
|
|
32
|
+
include = ["asgi_listeners*"]
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.package-data]
|
|
35
|
+
asgi_listeners = ["py.typed"]
|
|
36
|
+
|
|
37
|
+
[tool.uv]
|
|
38
|
+
cache-keys = [
|
|
39
|
+
{ file = "pyproject.toml" },
|
|
40
|
+
{ git = { commit = true, tags = true } },
|
|
41
|
+
{ env = "SETUPTOOLS_SCM_PRETEND_VERSION_FOR_ASGI_LISTENERS" },
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[tool.pytest.ini_options]
|
|
45
|
+
testpaths = ["tests"]
|
|
46
|
+
asyncio_mode = "auto"
|
|
47
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
48
|
+
addopts = "-q -ra"
|
|
49
|
+
|
|
50
|
+
[tool.ruff]
|
|
51
|
+
target-version = "py311"
|
|
52
|
+
line-length = 100
|
|
53
|
+
|
|
54
|
+
[tool.ruff.lint]
|
|
55
|
+
select = ["E", "F", "I", "B", "UP", "ASYNC"]
|
|
56
|
+
|
|
57
|
+
[tool.mypy]
|
|
58
|
+
python_version = "3.11"
|
|
59
|
+
strict = true
|
|
60
|
+
files = ["src", "examples"]
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Named ASGI application listeners with coordinated startup and shutdown."""
|
|
2
|
+
|
|
3
|
+
from .config import LifespanMode, ServerConfig
|
|
4
|
+
from .lifespan import LifespanError
|
|
5
|
+
from .listeners import BoundListener, Listener
|
|
6
|
+
from .server import Server
|
|
7
|
+
from .types import ASGIApp
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"ASGIApp",
|
|
11
|
+
"BoundListener",
|
|
12
|
+
"LifespanError",
|
|
13
|
+
"LifespanMode",
|
|
14
|
+
"Listener",
|
|
15
|
+
"Server",
|
|
16
|
+
"ServerConfig",
|
|
17
|
+
]
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""Immutable, framework-independent configuration DTOs."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from enum import StrEnum
|
|
5
|
+
from math import isfinite
|
|
6
|
+
from typing import Literal
|
|
7
|
+
|
|
8
|
+
LogLevel = Literal["critical", "error", "warning", "info", "debug", "trace"]
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class LifespanMode(StrEnum):
|
|
12
|
+
"""Run the first listener's lifespan or every distinct application's lifespan."""
|
|
13
|
+
|
|
14
|
+
FIRST = "first"
|
|
15
|
+
ALL = "all"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _integer(name: str, value: int, minimum: int, maximum: int) -> None:
|
|
19
|
+
if type(value) is not int:
|
|
20
|
+
raise TypeError(f"{name} must be an integer")
|
|
21
|
+
if not minimum <= value <= maximum:
|
|
22
|
+
raise ValueError(f"{name} must be between {minimum} and {maximum}")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
@dataclass(frozen=True, slots=True, kw_only=True)
|
|
26
|
+
class ServerConfig:
|
|
27
|
+
"""Runtime policy shared by all listeners; application bindings live in Listener."""
|
|
28
|
+
|
|
29
|
+
startup_timeout: float = 30.0
|
|
30
|
+
graceful_timeout: int = 30
|
|
31
|
+
shutdown_timeout: float = 30.0
|
|
32
|
+
keep_alive_timeout: int = 5
|
|
33
|
+
backlog: int = 2048
|
|
34
|
+
limit_concurrency: int | None = None
|
|
35
|
+
log_level: LogLevel | int | None = None
|
|
36
|
+
access_log: bool = False
|
|
37
|
+
proxy_headers: bool = False
|
|
38
|
+
forwarded_allow_ips: tuple[str, ...] = ()
|
|
39
|
+
handle_signals: bool = True
|
|
40
|
+
|
|
41
|
+
def __post_init__(self) -> None:
|
|
42
|
+
for name in ("startup_timeout", "shutdown_timeout"):
|
|
43
|
+
value = getattr(self, name)
|
|
44
|
+
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
|
45
|
+
raise TypeError(f"{name} must be a number")
|
|
46
|
+
if not isfinite(value) or value <= 0:
|
|
47
|
+
raise ValueError(f"{name} must be positive and finite")
|
|
48
|
+
_integer("keep_alive_timeout", self.keep_alive_timeout, 0, 86400)
|
|
49
|
+
_integer("graceful_timeout", self.graceful_timeout, 1, 86400)
|
|
50
|
+
_integer("backlog", self.backlog, 1, 65535)
|
|
51
|
+
if self.limit_concurrency is not None:
|
|
52
|
+
_integer("limit_concurrency", self.limit_concurrency, 1, 2**31 - 1)
|
|
53
|
+
for name in ("access_log", "proxy_headers", "handle_signals"):
|
|
54
|
+
if type(getattr(self, name)) is not bool:
|
|
55
|
+
raise TypeError(f"{name} must be a boolean")
|
|
56
|
+
if not isinstance(self.forwarded_allow_ips, tuple) or not all(
|
|
57
|
+
isinstance(peer, str) and peer for peer in self.forwarded_allow_ips
|
|
58
|
+
):
|
|
59
|
+
raise TypeError("forwarded_allow_ips must be a tuple of nonempty strings")
|
|
60
|
+
if self.proxy_headers and not self.forwarded_allow_ips:
|
|
61
|
+
raise ValueError("proxy_headers requires explicit forwarded_allow_ips")
|
|
62
|
+
if self.log_level is not None:
|
|
63
|
+
if isinstance(self.log_level, str):
|
|
64
|
+
if self.log_level not in {"critical", "error", "warning", "info", "debug", "trace"}:
|
|
65
|
+
raise ValueError("unsupported log_level")
|
|
66
|
+
elif type(self.log_level) is not int or self.log_level < 0:
|
|
67
|
+
raise ValueError("log_level must be a supported name or nonnegative integer")
|