From 00fd89af1ac3a47b6726101b2e477a3d8c291fc5 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Mon, 16 Nov 2026 21:18:25 +0800 Subject: [PATCH] docs: explain Foundry HTTP module registration [skip ci] --- cmd/foundry/main.go | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/cmd/foundry/main.go b/cmd/foundry/main.go index 2de3f2a..5b8d55a 100644 --- a/cmd/foundry/main.go +++ b/cmd/foundry/main.go @@ -63,11 +63,17 @@ func main() { if err != nil { log.Fatal(err) } + // auth.New 先构造认证子路由器:邮箱/OAuth、会话及 healthz/readyz 都注册在其内部。 + // 返回的 handler 尚未接到主路由器;下面通过 mux.Handle("/", handler) 统一挂载。 handler, err := auth.New(db, callbacks, origin.ResolveReference(&url.URL{Path: "/auth/google/callback"}).String(), id, secret, email, slack) if err != nil { log.Fatal(err) } + + // 所有对外 HTTP 模块共享这个主路由器;Register 是普通装配函数,不是自动扫描插件。 + // ServeMux 按方法和路径的匹配规则选更具体的模式,不以注册先后决定谁优先处理请求。 mux := http.NewServeMux() + // 研究数据使用可选、独立且只读的连接池;配置后必须在五秒启动探测内可访问。 var papers research.Repository if researchDSN := os.Getenv("FOUNDRY_RESEARCH_DATABASE_URL"); researchDSN != "" { @@ -95,22 +101,41 @@ func main() { } papers = repository } - // 先注册具体业务路径,最后的根处理器承接认证及健康探测请求。 + + // 研究 API:只挂载 GET /projects/{project}/research/papers 及论文详情路径。 + // 未配置研究库时 papers 为 nil,Register 直接返回,不安装这些可选路由。 research.Register(mux, papers, callbacks) + + // 独立执行 API:配置完整时挂载 POST /projects/{project}/codex/exec,转发到私有 Unix socket。 + // 这里使用专用项目授权令牌;不是平台业务 API 的普通用户会话认证。 + // socket/grants 全缺省时不安装路由,只配置其中一项则启动失败,避免半配置服务。 if err := codex.Register(mux, callbacks, os.Getenv("FOUNDRY_CODEX_SOCKET"), os.Getenv("FOUNDRY_CODEX_GRANTS")); err != nil { log.Fatal(err) } + + // 解析各项目的首次使用引导配置;这里只准备配置,具体路由由 platform.Register 安装。 onboarding, err := platform.ParseOnboarding(os.Getenv("FOUNDRY_ONBOARDING"), callbacks) if err != nil { log.Fatal(err) } + + // 平台 API:共享主数据库和项目配置,注册工作区、素材、画布、附件、分享及 AI 等业务路径。 + // 各业务 handler 通常经 platform.protected 做会话/身份检查,领域层再检查资源权限和事务条件; + // 它们不是先经过上面的 auth handler 再进入平台。公开短链接等路径有各自处理方式。 + // CanvasClient 与独立 exec API 共用 worker socket,但由平台组织画布任务;无 socket 时为 nil, + // 有客户端时 Register 还会启动画布 AI 后台队列,不能把它理解为只有路由表登记。 platform.Register(mux, db, callbacks, origin.Scheme+"://"+origin.Host, onboarding, codex.NewCanvasClient(os.Getenv("FOUNDRY_CODEX_SOCKET"))) + + // 将认证子路由器挂在主路由器的根路径:认证/健康检查由它继续分派,未知路径也交其处理。 + // "/" 是兜底匹配;具体平台/研究/exec 路由优先,不因它在最后注册而获得特殊中间件语义。 mux.Handle("/", handler) + // HOST 默认只监听回环,容器部署显式覆盖;较长写超时用于耗时业务响应。 server := &http.Server{ Addr: net.JoinHostPort(env("HOST", "127.0.0.1"), env("PORT", "8080")), Handler: mux, ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 110 * time.Second, IdleTimeout: 60 * time.Second, } + // 上面的 HTTP 路由装配完成后才开始监听;请求从 server.Handler 进入主 mux,再分派到对应模块。 log.Fatal(server.ListenAndServe()) }