http-service-patterns

用途：构建基于 FastAPI 的 HTTP 服务，处理请求之外还需后台循环协调状态、代理 WebSocket、并在上一实例未干净退出时仍能可靠启动。\n\n主要能力：1）预绑定端口清理，启动前用 lsof 查找并 SIGTERM 占用进程，避免 TIME_WAIT 导致 systemd 反复重启；2）FastAPI lifespan 管理启动/关闭，用 asyncio.create_task 启动后台轮询或监控与看门狗循环，关闭时取消任务并释放 httpx 客户端；3）WebSocket 双向中继，先在 accept 前完成鉴权与后端存活检查，再并发运行客户端→后端、后端→客户端两个任务，任一完成即取消另一；4）从 JSONL 文件尾部读取并以 SSE 流式推送事件，含等待文件出现的轮询与终态关闭条件。\n\n使用方式：可参考模板，先调用 kill_stale_port_holder(port) 再启动服务；在 lifespan 中创建并在退出时取消后台任务；WebSocket 端点单独做鉴权，因为 BaseHTTPMiddleware 不覆盖 WebSocket 作用域；SSE 使用 StreamingResponse，media_type 为 text/event-stream。\n\n适用场景：需要后台协调循环的 Python Web 服务、浏览器终端类 WebSocket 代理、容器或实例事件流推送。\n\n限制与注意：自签名 TLS 的 WebSocket 上游需显式信任证书；子进程服务应在启动时清理孤儿进程；示例代码需按实际后端协议与端口调整。