Web 服务器¶
canary_framework.web.asgi.server 的 Server 是一个监听端口的单元:监听是它的 @start,
关闭是它的 @stop。它站在 ASGI 协议的服务器一侧,服务任何 ASGI 应用——本框架的
应用单元、一个 FastAPI 对象、手写的 async def app(scope, receive, send)。
暂行 API
扩展包在稳定之前可能在次版本中调整,见版本与兼容性。
依赖即服务¶
from canary_framework import dep
from canary_framework.web.asgi.server import Server
class Gateway(Server):
api = dep(LibraryApi) # 一个应用单元,应答 /
metrics = dep(Metrics) # 另一个,应答 /metrics
host = "0.0.0.0"
port = 8010
async with Gateway():
...
Server 直接依赖的单元里,可调用并且声明了 path 的就是应用,各自在它的端口上应答
自己的 path。两个条件缺一不可:数据库、配置不可调用;一个恰好写了 __call__ 的策略对象
没有 path——它们都只是普通依赖。
| 阶段 | Server 做的事 |
|---|---|
@start |
绑定端口并开始服务。它依赖的单元此时都已启动 |
@stop |
停止接收新连接,等在途请求结束 |
应用是被依赖的一方,所以它们的 @start 先于监听、@stop 晚于关闭——数据库也一样。这就是
依赖顺序,不需要另外安排。
- 端口被占用时
start()抛出OSError,已启动的依赖照常回收。 port = 0由系统分配端口。服务期间server.port是实际端口,停止后还原成 0,所以重启会 重新分配。- 两个应用的
path相同时,start()抛出LifecycleError。 - 同一个应用单元可以被两个
Server依赖,例如对外一个端口、对内一个端口;它仍然只有一个 实例。
手写的应用单元¶
一个可调用、声明了 path 的单元就是应用单元,不需要继承什么:
class Metrics(Canary):
registry = dep(Registry)
path = "/metrics"
async def __call__(self, scope, receive, send) -> None:
await self.registry.asgi_app(scope, receive, send)
别的框架的应用¶
在 @init 里给 self.app 赋任何一个 ASGI 应用。赋了值就以它为准,依赖的应用单元不再自动
加入:
fastapi_app = FastAPI()
class Gateway(Server):
port = 8010
@init
def build(self) -> None:
self.app = fastapi_app
应用自己的 lifespan¶
Server 默认不向应用发 ASGI 的 lifespan 消息:启动与回收归 Canary 的生命周期。这对"先只换
服务器"的迁移是个坑——老应用写在 lifespan / on_event("startup") 里的连接池、缓存预热会
悄悄不执行,而接口照样能通。两种处理:
- 用类参数打开:
class Gateway(Server, lifespan="on")。应用的启动发生在Server的@start里、监听之前,回收发生在@stop里;应用启动失败就是Server启动失败,已启动的依赖 照常回收。本框架的应用单元此时已由 Canary 启动,只会应答,不会被重复驱动。 它只对赋给self.app的那个应用生效:dispatch对 lifespan 只应答、不转发, 经它拼进去的应用收不到这些消息。 - 或者把那部分搬成一个单元的
@start/@stop,让Server依赖它——迁移的终点通常是这个。
在别的框架的接口里用单元¶
别的框架的接口是模块级函数,不是单元的方法,依赖没法写成 dep(),要在请求时去图上取。
以 FastAPI 为例,这座桥十来行:
from canary_framework import Canary
from canary_framework.test import unit
from fastapi import Depends, FastAPI, Request
def attach(app: FastAPI, root: Canary) -> None:
app.state.graph = root # 在 Server 的 @init 里调用:attach(fastapi_app, self)
def use[T: Canary](cls: type[T]) -> T:
async def resolve(request: Request) -> T: # 必须是 async def
return unit(request.app.state.graph, cls)
return Depends(resolve)
@fastapi_app.get("/readers/{reader_id}")
async def show(reader_id: int, readers: ReaderService = use(ReaderService)) -> Reader:
return await readers.get(reader_id)
两点:
- 依赖函数写成
async def。 FastAPI 会把同步的依赖函数放进线程池,每个请求多一次线程 切换;这里只是查一次字典,实测写成同步的会让吞吐掉到三分之一。 - 按类型取单元用
canary_framework.test.unit。 它虽然放在test包里,做的就是"从一张 图上按类型取回单元"这一件事,生产代码里用它没有问题。
路径怎么分发¶
请求按最长前缀交给应用,前缀按整段匹配:/api 应答 /api 与 /api/...,不应答
/apix;/ 应答其余一切。没有匹配时 HTTP 得到 404。
只转发,不改写:应用看到的仍是完整路径,所以应用自己的路由要包含这个前缀。这不是 Starlette 意义上的"挂载"。
自动拼装用的是 canary_framework.web.asgi.dispatch,需要手动拼时直接用它:
from canary_framework.web.asgi import dispatch
class Gateway(Server):
api = dep(LibraryApi)
port = 8010
@init
def build(self) -> None:
self.app = dispatch({"/legacy": legacy_app, "/": self.api})
uvicorn 的配置¶
Server 内部用 uvicorn。类参数原样传给 uvicorn.Config,子类继承父类的类参数,只覆盖自己
写出的那些:
timeout_graceful_shutdown 值得设。不设时 @stop 会一直等到在途请求全部结束:一个不结束
的长连接就能让停机卡住,排在它后面的数据库等依赖也得不到回收,进程最后被强行杀掉。
地址用 host / port 类属性。app、host、port、uds、fd、reload、workers 在这里
另有归属,不能作为类参数,传了会在定义类时抛出 TypeError。lifespan 默认是 "off",见上文。
uvicorn 本身不带 WebSocket 实现,canary-framework[server] 一并装上 wsproto,服务器单元默认用它
(ws="wsproto")。没有选 uvicorn 在装了 websockets 时默认的 websockets-sansio:应用以 HTTP
响应拒绝握手时(见 Web 应用 › WebSocket),它会误报一条 "ASGI callable
returned without completing handshake." 错误日志。要换实现,写类参数 ws=...。
进程归 Canary¶
生命周期由 Canary 驱动,因此:
- 服务器不接管信号,何时退出由进程入口决定;
- 没有
--reload与--workers。需要它们时不用Server,把应用单元直接交给 uvicorn。
响应信号的入口:
async def main() -> None:
stop = asyncio.Event()
loop = asyncio.get_running_loop()
for sig in (signal.SIGINT, signal.SIGTERM):
loop.add_signal_handler(sig, stop.set)
async with Gateway():
await stop.wait()
Server 不必是根单元。守护进程顺带开一个管理端口,就是根上多一条 dep(AdminServer)。