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
2026-07-15 16:08:13 +08:00
parent 15dab96872
commit 59e3059246
39 changed files with 2350 additions and 4361 deletions
@@ -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
+}