rebuild: split core into separate repo; move wg-go integration to internal/ctr/corebind
- go.mod: require git.zkcoi.com/zkcoi/meshray/core, replace => ../Meshray - internal/ctr/corebind: EnhancedBind + registry + adapter (wg-go integration isolated) - cmd/mr-wg migrated from old core/cmd/meshray-core - core/ removed; CHANGELOG updated; fix checkdb vet warning
This commit is contained in:
@@ -0,0 +1,186 @@
|
||||
// Package contract 定义 Meshray 开源管理器与闭源 meshray-core 增强层之间的契约。
|
||||
//
|
||||
// 本包为开源叶子模块：不依赖管理器（meshray）也不依赖增强层（meshray-core），
|
||||
// 二者均 import 本包，从而避免 module 级循环依赖。
|
||||
//
|
||||
// 设计目标（来自架构决策：多仓解耦 + 编译期注入）：
|
||||
// - 管理器默认构建不 import meshray-core，因此可独立编译、以标准 WireGuard 直连运行；
|
||||
// - 增强构建（go build -tags meshray_core）空白导入 meshray-core，触发其 init() 把
|
||||
// 自定义 conn.Bind 工厂与 EngineProvider 注册到本包的全局注册表；
|
||||
// - 无 meshray-core 时，GetBindFactory(false) 返回 wireguard-go 默认 Bind（原生直连），
|
||||
// NewEngineController 返回 ErrCoreNotAvailable（增强模式优雅降级）。
|
||||
package contract
|
||||
|
||||
import (
|
||||
"errors"
|
||||
|
||||
"go.uber.org/zap"
|
||||
"golang.zx2c4.com/wireguard/conn"
|
||||
)
|
||||
|
||||
// ===== 候选地址与传输层 =====
|
||||
|
||||
// Candidate 对端候选地址（由信令层经 meshray-core 转发下发）
|
||||
type Candidate struct {
|
||||
Addr string `json:"addr"` // 候选地址（ip:port）
|
||||
Type string `json:"type"` // 候选类型：host/srflx/relay
|
||||
Priority int `json:"priority"` // 优先级
|
||||
Protocol string `json:"protocol"` // 协议：udp/tcp
|
||||
}
|
||||
|
||||
// Layer 传输层类型（9 层策略），数值与 meshray-core 内部 connect.Layer 对齐
|
||||
type Layer int
|
||||
|
||||
const (
|
||||
LayerDirectUDP Layer = iota
|
||||
LayerFakeTCP
|
||||
LayerRealTCP
|
||||
LayerTURNUDP
|
||||
LayerTURNQUIC
|
||||
LayerTURNTCP
|
||||
LayerTURNTLS
|
||||
LayerWebRTC
|
||||
LayerWS
|
||||
LayerCount
|
||||
)
|
||||
|
||||
// String 实现 Stringer
|
||||
func (l Layer) String() string {
|
||||
switch l {
|
||||
case LayerDirectUDP:
|
||||
return "Direct-UDP"
|
||||
case LayerFakeTCP:
|
||||
return "Direct-FakeTCP"
|
||||
case LayerRealTCP:
|
||||
return "Direct-RealTCP"
|
||||
case LayerTURNUDP:
|
||||
return "TURN-UDP"
|
||||
case LayerTURNQUIC:
|
||||
return "TURN-QUIC"
|
||||
case LayerTURNTCP:
|
||||
return "TURN-TCP"
|
||||
case LayerTURNTLS:
|
||||
return "TURN-TLS"
|
||||
case LayerWebRTC:
|
||||
return "WebRTC"
|
||||
case LayerWS:
|
||||
return "WS/WSS"
|
||||
default:
|
||||
return "Unknown"
|
||||
}
|
||||
}
|
||||
|
||||
// DefaultLayerOrder 默认优先级顺序（从最优到兜底）
|
||||
var DefaultLayerOrder = []Layer{
|
||||
LayerDirectUDP,
|
||||
LayerFakeTCP,
|
||||
LayerRealTCP,
|
||||
LayerTURNUDP,
|
||||
LayerTURNQUIC,
|
||||
LayerTURNTCP,
|
||||
LayerTURNTLS,
|
||||
LayerWebRTC,
|
||||
LayerWS,
|
||||
}
|
||||
|
||||
// ICEConfig ICE 配置（STUN/TURN 服务器），用于 WebRTC 等传输层
|
||||
type ICEConfig struct {
|
||||
STUNServers []string
|
||||
TURNServers []string
|
||||
}
|
||||
|
||||
// ===== 状态 =====
|
||||
|
||||
// PeerStatus 单 Peer 状态
|
||||
type PeerStatus struct {
|
||||
PeerKey string `json:"peer_key"`
|
||||
Connected bool `json:"connected"`
|
||||
Layer string `json:"layer,omitempty"`
|
||||
}
|
||||
|
||||
// EngineStatus 增强引擎状态
|
||||
type EngineStatus struct {
|
||||
PeerCount int `json:"peer_count"`
|
||||
Peers map[string]*PeerStatus `json:"peers"`
|
||||
ActiveConnections int64 `json:"active_connections"`
|
||||
TotalConnections int64 `json:"total_connections"`
|
||||
BytesSent uint64 `json:"bytes_sent"`
|
||||
BytesReceived uint64 `json:"bytes_received"`
|
||||
StrategyFallbacks int64 `json:"strategy_fallbacks"`
|
||||
LastSwitchTime int64 `json:"last_switch_time"`
|
||||
}
|
||||
|
||||
// ===== 增强引擎控制面契约 =====
|
||||
//
|
||||
// EngineController 由 meshray-core 实现，供管理器（开源）在 enhanced 模式调用。
|
||||
type EngineController interface {
|
||||
Start() error
|
||||
Stop() error
|
||||
// NotifyPeerCandidates 由信令层调用：注入对端候选地址并触发 P2P 建连
|
||||
NotifyPeerCandidates(peerKey string, candidates []Candidate) error
|
||||
// SetICEConfig 更新 ICE/STUN/TURN 配置
|
||||
SetICEConfig(cfg ICEConfig) error
|
||||
// SetLayerOrder 设置传输层优先级顺序（策略核心配置）
|
||||
SetLayerOrder(order []Layer) error
|
||||
// GetStatus 查询引擎状态
|
||||
GetStatus() (*EngineStatus, error)
|
||||
}
|
||||
|
||||
// EngineProvider 创建 EngineController 的工厂（由 meshray-core 注册）
|
||||
type EngineProvider func(networkID string, logger *zap.Logger) (EngineController, error)
|
||||
|
||||
var (
|
||||
engineProvider EngineProvider
|
||||
errCoreNotAvail = errors.New("meshray-core 未启用：增强模式不可用（仅原生直连可用）")
|
||||
)
|
||||
|
||||
// RegisterEngineProvider 由 meshray-core 在 init 中注册
|
||||
func RegisterEngineProvider(p EngineProvider) {
|
||||
engineProvider = p
|
||||
}
|
||||
|
||||
// EngineProviderRegistered 是否已注册增强引擎提供方
|
||||
func EngineProviderRegistered() bool {
|
||||
return engineProvider != nil
|
||||
}
|
||||
|
||||
// NewEngineController 创建增强引擎；未注册 core 时返回 errCoreNotAvail
|
||||
func NewEngineController(networkID string, logger *zap.Logger) (EngineController, error) {
|
||||
if engineProvider == nil {
|
||||
return nil, errCoreNotAvail
|
||||
}
|
||||
return engineProvider(networkID, logger)
|
||||
}
|
||||
|
||||
// ===== WireGuard conn.Bind 工厂契约 =====
|
||||
//
|
||||
// BindFactory 创建接管 WG 收发的 conn.Bind。原生模式用 wireguard-go 默认 Bind；
|
||||
// 增强模式由 meshray-core 注册自定义 Bind（在 Send/Recv 中插入 9 层传输与打洞）。
|
||||
type BindFactory func(listenPort int, networkID string, logger *zap.Logger) (conn.Bind, error)
|
||||
|
||||
var (
|
||||
nativeBindFactory = func(listenPort int, networkID string, logger *zap.Logger) (conn.Bind, error) {
|
||||
return conn.NewDefaultBind(), nil
|
||||
}
|
||||
enhancedBindFactory BindFactory
|
||||
errBindNotEnhanced = errors.New("meshray-core 未启用：enhanced 模式无法创建自定义 Bind")
|
||||
)
|
||||
|
||||
// RegisterEnhancedBindFactory 由 meshray-core 在 init 中注册
|
||||
func RegisterEnhancedBindFactory(f BindFactory) {
|
||||
enhancedBindFactory = f
|
||||
}
|
||||
|
||||
// GetBindFactory 获取 Bind 工厂：
|
||||
// - enhanced=true 且已注册 core → 返回 core 的自定义 Bind 工厂；
|
||||
// - enhanced=true 但未注册 core → 返回 errBindNotEnhanced；
|
||||
// - enhanced=false → 返回 wireguard-go 默认 Bind（原生直连）。
|
||||
func GetBindFactory(enhanced bool) (BindFactory, error) {
|
||||
if enhanced {
|
||||
if enhancedBindFactory == nil {
|
||||
return nil, errBindNotEnhanced
|
||||
}
|
||||
return enhancedBindFactory, nil
|
||||
}
|
||||
return nativeBindFactory, nil
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
module git.zkcoi.com/zkcoi/meshray-contract
|
||||
|
||||
go 1.26.0
|
||||
|
||||
require (
|
||||
go.uber.org/zap v1.27.0
|
||||
golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb
|
||||
)
|
||||
|
||||
require (
|
||||
go.uber.org/multierr v1.10.0 // indirect
|
||||
golang.org/x/net v0.39.0 // indirect
|
||||
golang.org/x/sys v0.32.0 // indirect
|
||||
)
|
||||
@@ -0,0 +1,20 @@
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
|
||||
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
|
||||
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
|
||||
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
|
||||
go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
|
||||
go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
|
||||
go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
|
||||
go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
|
||||
golang.org/x/net v0.39.0 h1:ZCu7HMWDxpXpaiKdhzIfaltL9Lp31x/3fCP11bc6/fY=
|
||||
golang.org/x/net v0.39.0/go.mod h1:X7NRbYVEA+ewNkCNyJ513WmMdQ3BineSwVtN2zD/d+E=
|
||||
golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20=
|
||||
golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
|
||||
golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb h1:whnFRlWMcXI9d+ZbWg+4sHnLp52d5yiIPUxMBSt4X9A=
|
||||
golang.zx2c4.com/wireguard v0.0.0-20250521234502-f333402bd9cb/go.mod h1:rpwXGsirqLqN2L0JDJQlwOboGHmptD5ZD6T2VmcqhTw=
|
||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
Reference in New Issue
Block a user