Feat/gateway starter

[Nexisato]

概述

实现 swanlab-core（Go）的进程启动与生命周期框架（Owner Mode）：

• gRPC 服务启动与端点回报（port-file 最小协议）
• Owner 生命周期：parent PID 监控、Teardown RPC、信号处理
• 同一 core 下的多 run 会话路由（run_handle）
• 本地信任模型：安全边界由 UDS 与文件系统权限承担
• fork 回调注册表改用弱引用持有 bound method，注册不延长实例生命周期（为 CoreGo after-fork 预留）

功能点

启动与端点回报

Python SDK 通过 subprocess.Popen 启动 swanlab-core。未指定 --listen 时按平台自选端点：POSIX 使用 runtime 目录内的 UDS，listen 失败记录 warning 后回退 127.0.0.1:0；Windows 使用回环 TCP。listen 与 gRPC server 初始化成功后原子写入 port-file（同目录临时文件 + chmod 0600 + rename），Python 轮询该文件完成握手。显式 --listen 视为调用方指定端点，失败报错；tcp:// 限定回环地址。

port-file 为最小协议，承担临时 endpoint discovery，不携带鉴权或身份字段：

protocol=1
pid=<core-pid>
unix=<absolute-socket-path>   # Windows 或 UDS 回退时为 sock=<loopback-port>
EOF

信任模型

POSIX 使用 UDS（socket 文件位于 owner-only 私有 runtime 目录），port-file 以 0600 权限发布；loopback TCP 回退不隔离本机用户，能连接端口的本机进程可调用全部 RPC。

生命周期与 run 路由

• 状态机 NOT_READY → READY → STOPPING → CLOSED：SpinupService 幂等置 READY，READY 前 run 级 RPC 返回 FAILED_PRECONDITION；
• DeliverRunStart 创建随机 run_handle 存入并发安全 registry，run 级 RPC 按 handle 路由；
• ConfirmRunFinish 在对应 run 的 DeliverRunFinish 交付后原子释放 session（提前调用返回 FAILED_PRECONDITION，会话保留），不关闭 gRPC Server；TeardownService 在独立 goroutine 执行 GracefulStop，避免 handler 内自等待；
• Teardown、SIGINT/SIGTERM、父进程退出、Serve 异常汇入 controller 的关闭路径（GracefulStop + 超时强制 Stop 兜底）；
• 退出清理按 port-file 的 pid 字段判定归属，路径被后启动实例覆盖时不误删。

父进程监控

Linux 使用 PDEATHSIG 快路径，另有进程级兜底：先使用 pidfd，不可用时低频轮询 PID/PPID，覆盖从非主线程 spawn、spawn 线程先退出的场景；监控通知 controller，不在监控 goroutine 中执行关闭。

detached 预留

--detach 与 --idle-timeout 为 detached 模式预留，当前版本接受传值但作为 no-op 忽略并记录 warning，core 仍以 Owner Mode 运行，当前实现暂不添加 detached 运行逻辑。

协议调整

core.proto 新增 Spinup/Teardown RPC；DeliverRunStart 响应返回 run_handle，upsert/finish/stats/confirm 等 run 级请求携带该 handle；Python/Go stub 重新生成。

启动流程

Python SDK: subprocess.Popen(swanlab-core)
  │
  ▼
swanlab-core
  ├─ 选择端点                  # POSIX UDS，失败回退 127.0.0.1:0；Windows loopback TCP
  ├─ 建立父进程退出监控         # PDEATHSIG 快路径 + pidfd/PPID 轮询兜底
  ├─ 创建 gRPC Server          # NOT_READY
  └─ 原子写 port-file          # protocol/pid/endpoint，chmod 0600 + rename
       │
       ▼  Python 读 port-file → channel ready → SpinupService
  NOT_READY → READY            # 幂等；READY 前 run RPC 返回 FAILED_PRECONDITION
       │
       ▼  DeliverRunStart(start_record, core_settings)
  创建 run_handle + RunSession # 并发安全 registry，run 级 RPC 按 handle 路由

一次 run 上报结束（ConfirmRunFinish）与服务退出（TeardownService）在协议层分离

风险提示

升级后的发行版暂不支持 alpine 镜像，rpc 通信需要依赖标准的 grpcio 库，要求基础镜像中必须携带 glibc 库，与 numpy 保留同级环境要求