mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-05 23:26:38 +08:00
feat(cordis): add OpenFlare Cordis 架构改造设计
docs(changelog): 修正表述笔误
refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本
按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。
验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。
docs(cordis): 记录 T1 清理结果与五个复用阻塞点
refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本
按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。
两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
副本，待与 infra 初始化一并迁移（已登记在清理计划）。
验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。
chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染
按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。
同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。
AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。
验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。
feat(cordis): server 插件化并改由内核挂载控制面路由
新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。
路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。
已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。
feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由
server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。
验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。
docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口
feat(cordis): agent/relay/flared 落地为内核驱动插件
三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。
入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。
验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。
refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层
backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。
验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。
feat(cordis): 落地 backend/share 共享层与上游同步脚本
跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。
go build 通过，go test ./... exit 0（142 包 ok），前端零改动。
refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核
按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。
行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。
style: 修正模块路径改写导致的 import 分组排序漂移
refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare
对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。
行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。
chore(cordis): 落地改造计划与 schema/路由基线
新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。
docs(cordis): add OpenFlare Cordis 架构改造设计
明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。
This commit is contained in:
ryan
@@ -0,0 +1,219 @@
|
||||
// Copyright 2026 Arctel.net
|
||||
// SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
package domain_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
|
||||
"Wavelet/core"
|
||||
"Wavelet/core/contracts"
|
||||
"Wavelet/core/extpoints"
|
||||
"Wavelet/plugins/domain/admin"
|
||||
"Wavelet/plugins/domain/message_gateway"
|
||||
"Wavelet/plugins/domain/user"
|
||||
)
|
||||
|
||||
// The kernel only gates a plugin's Apply on the services it DECLARES in Inject,
|
||||
// so a plugin that consumes contracts.AuthService without declaring it can be
|
||||
// mounted before auth exists. Those plugins fall back to a pass-through
|
||||
// middleware, which silently un-guards their routes.
|
||||
|
||||
func sentinelLogin(c *gin.Context) { c.Next() }
|
||||
func sentinelAdmin(c *gin.Context) { c.Next() }
|
||||
func sentinelNoToken(c *gin.Context) { c.Next() }
|
||||
|
||||
type stubAuthService struct{ contracts.AuthService }
|
||||
|
||||
func (stubAuthService) RequireAuthMiddleware() any { return gin.HandlerFunc(sentinelLogin) }
|
||||
func (stubAuthService) RequireAdminMiddleware() any { return gin.HandlerFunc(sentinelAdmin) }
|
||||
func (stubAuthService) DisallowTokenAuthMiddleware() any { return gin.HandlerFunc(sentinelNoToken) }
|
||||
|
||||
type stubDBService struct{ contracts.DBService }
|
||||
|
||||
// providerPlugin publishes a contract into the container at Apply time, the way
|
||||
// the real infra and domain plugins do.
|
||||
type providerPlugin struct {
|
||||
name string
|
||||
provide func(*core.Context) error
|
||||
}
|
||||
|
||||
func (p providerPlugin) Name() string { return p.name }
|
||||
|
||||
func (p providerPlugin) Apply(ctx *core.Context) error { return p.provide(ctx) }
|
||||
|
||||
func dbProvider() core.Plugin {
|
||||
return providerPlugin{name: "stub-database", provide: func(ctx *core.Context) error {
|
||||
core.Provide[contracts.DBService](ctx, stubDBService{})
|
||||
return nil
|
||||
}}
|
||||
}
|
||||
|
||||
func authProvider() core.Plugin {
|
||||
return providerPlugin{name: "stub-auth", provide: func(ctx *core.Context) error {
|
||||
core.Provide[contracts.AuthService](ctx, stubAuthService{})
|
||||
return nil
|
||||
}}
|
||||
}
|
||||
|
||||
func findRoute(routes []extpoints.RouteDefinition, method, path string) (extpoints.RouteDefinition, bool) {
|
||||
for _, rd := range routes {
|
||||
if rd.Method == method && rd.Path == path {
|
||||
return rd, true
|
||||
}
|
||||
}
|
||||
return extpoints.RouteDefinition{}, false
|
||||
}
|
||||
|
||||
// codePointer resolves the function code pointer of a registered handler so
|
||||
// identity can be compared without depending on gin internals.
|
||||
func codePointer(handler any) uintptr {
|
||||
switch fn := handler.(type) {
|
||||
case gin.HandlerFunc:
|
||||
return reflect.ValueOf(fn).Pointer()
|
||||
case func(*gin.Context):
|
||||
return reflect.ValueOf(fn).Pointer()
|
||||
default:
|
||||
return 0
|
||||
}
|
||||
}
|
||||
|
||||
func assertsMiddleware(t *testing.T, routes []extpoints.RouteDefinition, method, path string, want func(*gin.Context)) {
|
||||
t.Helper()
|
||||
|
||||
rd, ok := findRoute(routes, method, path)
|
||||
if !ok {
|
||||
t.Fatalf("route %s %s was never registered", method, path)
|
||||
}
|
||||
wantPtr := codePointer(gin.HandlerFunc(want))
|
||||
for _, h := range rd.Handlers {
|
||||
if codePointer(h) == wantPtr {
|
||||
return
|
||||
}
|
||||
}
|
||||
for _, m := range rd.Middlewares {
|
||||
if codePointer(m) == wantPtr {
|
||||
return
|
||||
}
|
||||
}
|
||||
t.Errorf("route %s %s is not guarded by the auth middleware: handlers=%d middlewares=%d",
|
||||
method, path, len(rd.Handlers), len(rd.Middlewares))
|
||||
}
|
||||
|
||||
// TestRoutesMountedBeforeAuthServiceAreGuarded 回归：cmd/app.go 把 user/message_gateway
|
||||
// 注册在 auth 之前，若插件未在 Inject 中声明 contracts.AuthService，reconcile 会先
|
||||
// Apply 它们，导致鉴权中间件退化为透传闭包，路由完全不受保护。
|
||||
func TestRoutesMountedBeforeAuthServiceAreGuarded(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
ctx := core.NewContext(context.Background())
|
||||
|
||||
// Registration order mirrors cmd/app.go: the auth provider comes last.
|
||||
app := core.NewApp(
|
||||
core.WithContext(ctx),
|
||||
core.WithPlugins(
|
||||
dbProvider(),
|
||||
user.New(),
|
||||
message_gateway.New(),
|
||||
authProvider(),
|
||||
),
|
||||
)
|
||||
require.NoError(t, app.ApplyPlugins())
|
||||
|
||||
routes := ctx.Router().Routes()
|
||||
|
||||
assertsMiddleware(t, routes, "POST", "/api/v1/user/change-password", sentinelLogin)
|
||||
assertsMiddleware(t, routes, "PUT", "/api/v1/user/profile", sentinelLogin)
|
||||
assertsMiddleware(t, routes, "GET", "/api/v1/user/access-tokens", sentinelLogin)
|
||||
assertsMiddleware(t, routes, "GET", "/api/v1/user/access-tokens", sentinelNoToken)
|
||||
assertsMiddleware(t, routes, "GET", "/api/v1/message-gateway/channels", sentinelLogin)
|
||||
assertsMiddleware(t, routes, "GET", "/api/v1/admin/message-gateway/channels", sentinelAdmin)
|
||||
}
|
||||
|
||||
// TestAuthConsumersDeclareAuthDependency 是同一缺陷的架构面：声明依赖是内核排序的唯一
|
||||
// 依据，漏声明会让正确性取决于注册表顺序。
|
||||
func TestAuthConsumersDeclareAuthDependency(t *testing.T) {
|
||||
want := reflect.TypeFor[contracts.AuthService]()
|
||||
for _, tc := range []struct {
|
||||
name string
|
||||
deps []reflect.Type
|
||||
}{
|
||||
{"user", user.New().Inject()},
|
||||
{"message_gateway", message_gateway.New().Inject()},
|
||||
} {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
assert.Contains(t, tc.deps, want,
|
||||
"%s resolves contracts.AuthService in Apply, so it must declare it in Inject", tc.name)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// firstGuard returns the outermost middleware registered for the first route
|
||||
// matching method and path prefix — the auth guard the plugin resolved at Apply.
|
||||
func firstGuard(t *testing.T, routes []extpoints.RouteDefinition, method, prefix string) gin.HandlerFunc {
|
||||
t.Helper()
|
||||
|
||||
for _, rd := range routes {
|
||||
if rd.Method != method || !strings.HasPrefix(rd.Path, prefix) {
|
||||
continue
|
||||
}
|
||||
for _, candidate := range rd.Middlewares {
|
||||
if mw, ok := candidate.(gin.HandlerFunc); ok {
|
||||
return mw
|
||||
}
|
||||
}
|
||||
for _, candidate := range rd.Handlers {
|
||||
if mw, ok := candidate.(gin.HandlerFunc); ok {
|
||||
return mw
|
||||
}
|
||||
}
|
||||
t.Fatalf("route %s %s has no inspectable guard", method, rd.Path)
|
||||
}
|
||||
t.Fatalf("no route registered for %s %s*", method, prefix)
|
||||
return nil
|
||||
}
|
||||
|
||||
// TestAuthGuardFailsClosed 回归：鉴权服务无法解析时兜底必须是拒绝。旧实现兜底为
|
||||
// c.Next()，所以任何装配缺失——例如 admin 的 OnDispose 调用 service.ResetServices
|
||||
// 把全局 authService 置 nil——都会让路由以“已登录”的姿态直达业务处理函数。
|
||||
func TestAuthGuardFailsClosed(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
apply func(*core.Context) error
|
||||
method string
|
||||
prefix string
|
||||
}{
|
||||
{"user", user.New().Apply, http.MethodPost, "/api/v1/user/change-password"},
|
||||
{"message_gateway", message_gateway.New().Apply, http.MethodGet, "/api/v1/message-gateway"},
|
||||
{"admin", admin.New().Apply, http.MethodGet, "/api/v1/admin"},
|
||||
}
|
||||
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
ctx := core.NewContext(context.Background())
|
||||
require.NoError(t, tc.apply(ctx))
|
||||
|
||||
guard := firstGuard(t, ctx.Router().Routes(), tc.method, tc.prefix)
|
||||
|
||||
w := httptest.NewRecorder()
|
||||
c, _ := gin.CreateTestContext(w)
|
||||
c.Request = httptest.NewRequest(tc.method, tc.prefix, nil)
|
||||
guard(c)
|
||||
|
||||
assert.True(t, c.IsAborted(),
|
||||
"%s guard must reject the request when contracts.AuthService is unavailable", tc.name)
|
||||
assert.NotEmpty(t, c.Errors,
|
||||
"%s guard must record why the request was rejected", tc.name)
|
||||
})
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user