docs: explain Foundry HTTP module registration [skip ci]

This commit is contained in:
2026-11-16 21:18:25 +08:00
parent 1090591503
commit 00fd89af1a
+26 -1
View File
@@ -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())
}