feat: Host 中间件租户路由（纯ASGI覆盖WS/未知404/停用503暂停页/health豁免）

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-12 20:30:30 +08:00
parent 1824bb1590
commit eaa5bf7e51
5 changed files with 338 additions and 50 deletions
@@ -0,0 +1,99 @@
+"""TenantHostMiddleware——按 Host 头解析租户的纯 ASGI 中间件(Task 7)。
+
+为什么必须是纯 ASGI 类而不是 ``@app.middleware("http")``(前序审查实证过
+的坑): 那条路走 BaseHTTPMiddleware,只跑 http scope——WebSocket 请求会
+整个绕过租户解析落进 routes/runtime.py 的兜底,租户 A 的 WS 流量静默写进
+租户 B 的库(串库不崩溃,极难发现)。本类自己分发 http 与 websocket 两种
+scope type,两条路都先过租户解析。
+
+行为:
+- scope 非 http/websocket(lifespan 等)原样放行;
+- path 精确等于 ``/health`` 豁免(部署健康检查 ``curl 127.0.0.1:8018``
+  /health,Host 是 IP:端口必然未知;精确匹配,``/healthxxx`` 不豁免);
+- Host 头 → ``registry.resolve_site``: 未知 → http 404 / ws close(1008);
+  租户停用 → http 503 中性"服务暂停"页(不暴露租户信息)/ ws close(1013);
+- 解析成功把 tenant/site 写进 ``scope["state"]``——Request/WebSocket.state
+  与 scope["state"] 共享同一 dict(setdefault 保证),routes 的 get_runtime
+  即读到本中间件写入的 runtime。
+
+Registry 延迟取: ``add_middleware`` 实例化时 lifespan 还没跑、
+``app.state.registry`` 未挂,构造期拿不到——从 ``scope["app"].state``
+逐请求取(Starlette 在中间件栈外层保证 scope 带 app)。
+"""
+from starlette.responses import HTMLResponse, PlainTextResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+# 归一复用 registry 的私有实现——同一包内单一事实源,中间件与域名索引
+# 的建法永不漂移(resolve_site 内部也会再归一次,双保险无害)
+from app.platform.registry import (
+    TenantDisabledError,
+    UnknownTenantError,
+    _normalize_host,
+)
+
+# 中性"服务暂停"页: 不暴露租户 slug/域名/停用原因(可能是欠费等敏感信息)
+PAUSE_PAGE = (
+    "<!DOCTYPE html><html lang=\"zh-CN\"><head><meta charset=\"utf-8\">"
+    "<title>服务暂停</title></head>"
+    "<body style=\"font-family:system-ui,sans-serif;text-align:center;"
+    "padding:4rem 1rem;color:#333;\">"
+    "<p style=\"font-size:1.1rem;\">服务暂停维护中，请稍后再试。</p>"
+    "</body></html>"
+)
+
+
+def _host_from_scope(scope: Scope) -> str:
+    """ASGI headers(小写 bytes 键值对)里的 host → str 并归一。"""
+    for key, value in scope.get("headers") or []:
+        if key == b"host":
+            return _normalize_host(value.decode("latin-1"))
+    return ""
+
+
+async def _close_ws(receive: Receive, send: Send, code: int, reason: str) -> None:
+    """以 close 代 accept 拒绝 WS(ASGI 规范序列: 先收到 websocket.connect,
+    再回 websocket.close)。reason 中性,不带租户信息。"""
+    event = await receive()
+    if event["type"] == "websocket.connect":
+        await send({"type": "websocket.close", "code": code, "reason": reason})
+
+
+class TenantHostMiddleware:
+    """纯 ASGI 租户路由中间件(设计动机见模块 docstring)。"""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in ("http", "websocket"):
+            return await self.app(scope, receive, send)
+        if scope.get("path") == "/health":
+            return await self.app(scope, receive, send)
+
+        registry = getattr(scope["app"].state, "registry", None)
+        if registry is None:
+            raise RuntimeError(
+                "app.state.registry 未挂载——TenantHostMiddleware 需要 "
+                "lifespan(或测试注入缝)先加载 TenantRegistry")
+
+        try:
+            runtime, site = await registry.resolve_site(_host_from_scope(scope))
+        except UnknownTenantError:
+            if scope["type"] == "websocket":
+                await _close_ws(receive, send, 1008, "unknown host")
+            else:
+                await PlainTextResponse("Not Found", status_code=404)(
+                    scope, receive, send)
+            return
+        except TenantDisabledError:
+            if scope["type"] == "websocket":
+                await _close_ws(receive, send, 1013, "service paused")
+            else:
+                await HTMLResponse(PAUSE_PAGE, status_code=503)(
+                    scope, receive, send)
+            return
+
+        state = scope.setdefault("state", {})
+        state["tenant"] = runtime
+        state["site"] = site
+        await self.app(scope, receive, send)