merge: maestro/tsk_iP5-_Ztq5THx [桥接 API 面 Channel 契约 + 三端原生骨架] [tsk_rcNKc3GQHBUd]

合并冲突补救：原分支从 merge base 7871512 分叉，仅修改 client/ 目录，与 main 新增的 server/(apierr/idgen/CONVENTIONS.md) 完全不重叠，无真实文件冲突，手动应用 feature branch 的全部 client/ 改动。 client 侧新增： - lib/bridge/vpn_bridge.dart — Dart↔原生通道契约（冻结） - lib/bridge/vpn_bridge_mock.dart — 假内核，UI 联调用 - lib/bridge/kernel_process.dart — 桌面子进程管理接口 - ios/PacketTunnel/{Info.plist,PacketTunnelProvider.swift} — NEPacketTunnel 骨架 - ios/Runner/VpnManager.swift — NETunnelProviderManager 封装 - android/.../PangolinVpnService.kt — VpnService 骨架 - android/.../VpnEventBus.kt — Application 级状态总线 - test/bridge/vpn_bridge_mock_test.dart — 桥接层单元测试 client 侧修改： - android/.../MainActivity.kt — 注册三通道（MethodChannel + 2×EventChannel） - android/.../AndroidManifest.xml — 声明 FOREGROUND_SERVICE + PangolinVpnService - ios/Runner/AppDelegate.swift — 注册通道 + VpnManager 初始化 - ios/Runner/Info.plist — 新增 NSVPNUsageDescription - ios/Runner.xcodeproj/project.pbxproj — 添加 PacketTunnel extension target - lib/widgets/connect_button.dart — VpnStatus 迁移到 bridge/vpn_bridge.dart - lib/widgets/home_shell.dart — error 状态 UI 分支补全
2026-06-13 14:58:38 +08:00
parent 30e73b31c2
commit c84b6ea7da
16 changed files with 1677 additions and 11 deletions
@@ -1,13 +1,98 @@
+// AppDelegate.swift — Flutter ↔ 原生通道注册
+//
+// 通道契约（见 lib/bridge/vpn_bridge.dart 头部注释）：
+//   MethodChannel  : pangolin/vpn
+//   EventChannel   : pangolin/vpn/status  → VpnStatusStreamHandler
+//   EventChannel   : pangolin/vpn/stats   → VpnStatsStreamHandler
+//
+// VpnManager.shared 持有 NETunnelProviderManager 与 NEVPNStatus 订阅。
+
 import UIKit
 import Flutter
+import NetworkExtension

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
-  override func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-  ) -> Bool {
-    GeneratedPluginRegistrant.register(with: self)
-    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-  }
+
+    override func application(
+        _ application: UIApplication,
+        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+    ) -> Bool {
+        GeneratedPluginRegistrant.register(with: self)
+
+        guard let controller = window?.rootViewController as? FlutterViewController else {
+            return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+        }
+        let messenger = controller.binaryMessenger
+
+        // ── MethodChannel ────────────────────────────────────────
+        let vpnChannel = FlutterMethodChannel(name: "pangolin/vpn", binaryMessenger: messenger)
+        vpnChannel.setMethodCallHandler { [weak self] call, result in
+            self?.handleVpnMethod(call: call, result: result)
+        }
+
+        // ── EventChannel: status ─────────────────────────────────
+        FlutterEventChannel(name: "pangolin/vpn/status", binaryMessenger: messenger)
+            .setStreamHandler(VpnStatusStreamHandler.shared)
+
+        // ── EventChannel: stats ──────────────────────────────────
+        FlutterEventChannel(name: "pangolin/vpn/stats", binaryMessenger: messenger)
+            .setStreamHandler(VpnStatsStreamHandler.shared)
+
+        // 预加载 VPN 偏好设置（首次为空，静默失败）
+        VpnManager.shared.loadFromPreferences { error in
+            if let error = error {
+                NSLog("VpnManager: loadFromPreferences error: %@", error.localizedDescription)
+            }
+        }
+
+        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+    }
+
+    // ── MethodChannel handler ─────────────────────────────────────
+
+    private func handleVpnMethod(call: FlutterMethodCall, result: @escaping FlutterResult) {
+        switch call.method {
+
+        case "start":
+            let configJson = call.arguments as? String ?? "{}"
+            VpnManager.shared.start(configJson: configJson) { error in
+                if let error = error {
+                    result(FlutterError(
+                        code: "START_FAILED",
+                        message: error.localizedDescription,
+                        details: nil
+                    ))
+                } else {
+                    result(nil)
+                }
+            }
+
+        case "stop":
+            VpnManager.shared.stop()
+            result(nil)
+
+        case "getStatus":
+            result(VpnManager.shared.statusString)
+
+        case "selectOutbound":
+            let tag = call.arguments as? String ?? "auto"
+            NSLog("VPN: selectOutbound tag=%@", tag)
+            // TODO(11F): sendProviderMessage → PacketTunnelProvider outbound selector
+            result(nil)
+
+        case "getActiveOutbound":
+            // TODO(11F): query from PacketTunnelProvider via sendProviderMessage
+            result("auto")
+
+        case "setKillSwitch":
+            let on = call.arguments as? Bool ?? false
+            NSLog("VPN: setKillSwitch on=%d", on ? 1 : 0)
+            // TODO(11F): 通过 include/excludeRoutes 实现 Kill Switch
+            result(nil)
+
+        default:
+            result(FlutterMethodNotImplemented)
+        }
+    }
 }
@@ -47,5 +47,8 @@
 	<true/>
 	<key>UIApplicationSupportsIndirectInputEvents</key>
 	<true/>
+	<!-- VPN 使用说明（App Store 审核必填） -->
+	<key>NSVPNUsageDescription</key>
+	<string>穿山甲使用 VPN 为您的网络连接提供加密保护。</string>
 </dict>
 </plist>
@@ -0,0 +1,187 @@
+// VpnManager.swift — 主 App 侧 NETunnelProviderManager 封装
+//
+// 职责：
+//   1. loadAllFromPreferences / saveToPreferences — 首次安装时建立 VPN 配置条目
+//   2. start / stop — 通过 NETunnelProviderSession 驱动 PacketTunnel extension
+//   3. sendProviderMessage — 透传 IPC 消息到 PacketTunnelProvider.handleAppMessage
+//
+// AppDelegate 持有本类单例，在 MethodChannel handler 中调用其方法。
+//
+// TODO(11F): 实现 start/stop 前的证书/权限检查；订阅 NEVPNStatus 通知并
+//            通过 VpnStatusStreamHandler.shared.eventSink 推送到 Dart 侧。
+
+import Foundation
+import NetworkExtension
+
+// ── 流处理器（Flutter EventChannel stream handlers）───────────────
+
+/// status 流：推送 "off" / "connecting" / "on" / "error" 字符串
+class VpnStatusStreamHandler: NSObject, FlutterStreamHandler {
+    static let shared = VpnStatusStreamHandler()
+    private(set) var eventSink: FlutterEventSink?
+
+    func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
+        eventSink = events
+        return nil
+    }
+
+    func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        eventSink = nil
+        return nil
+    }
+
+    func push(_ status: String) {
+        DispatchQueue.main.async { self.eventSink?(status) }
+    }
+}
+
+/// stats 流：推送 [String: Any] 字典，字段同 vpn_bridge.dart VpnStatsEvent schema
+class VpnStatsStreamHandler: NSObject, FlutterStreamHandler {
+    static let shared = VpnStatsStreamHandler()
+    private(set) var eventSink: FlutterEventSink?
+
+    func onListen(withArguments arguments: Any?, eventSink events: @escaping FlutterEventSink) -> FlutterError? {
+        eventSink = events
+        return nil
+    }
+
+    func onCancel(withArguments arguments: Any?) -> FlutterError? {
+        eventSink = nil
+        return nil
+    }
+
+    func push(_ stats: [String: Any]) {
+        DispatchQueue.main.async { self.eventSink?(stats) }
+    }
+}
+
+// ── VPN 管理器 ────────────────────────────────────────────────────
+
+class VpnManager: NSObject {
+
+    static let shared = VpnManager()
+
+    private var tunnelManager: NETunnelProviderManager?
+
+    // Bundle ID 与 PacketTunnel target PRODUCT_BUNDLE_IDENTIFIER 保持同步
+    private let extensionBundleId = "com.pangolin.pangolinVpn.PacketTunnel"
+
+    private var statusObserver: NSObjectProtocol?
+
+    private override init() {
+        super.init()
+        subscribeToVpnStatus()
+    }
+
+    // ── 偏好设置加载与保存 ─────────────────────────────────────
+
+    /// 从系统偏好加载已存在的 VPN 配置（首次为空列表）。
+    /// 必须在调用 start() 前完成。
+    func loadFromPreferences(completion: @escaping (Error?) -> Void) {
+        NETunnelProviderManager.loadAllFromPreferences { [weak self] managers, error in
+            guard let self = self else { return }
+            if let error = error {
+                completion(error)
+                return
+            }
+            self.tunnelManager = managers?.first(where: {
+                ($0.protocolConfiguration as? NETunnelProviderProtocol)?
+                    .providerBundleIdentifier == self.extensionBundleId
+            }) ?? NETunnelProviderManager()
+            completion(nil)
+        }
+    }
+
+    /// 创建或更新 VPN 配置条目（首次安装时调用一次）。
+    func saveConfiguration(serverAddress: String = "pangolin", completion: @escaping (Error?) -> Void) {
+        let manager = tunnelManager ?? NETunnelProviderManager()
+        let proto = NETunnelProviderProtocol()
+        proto.providerBundleIdentifier = extensionBundleId
+        proto.serverAddress = serverAddress
+        manager.protocolConfiguration = proto
+        manager.localizedDescription = "穿山甲 Pangolin VPN"
+        manager.isEnabled = true
+        manager.saveToPreferences { [weak self] error in
+            if error == nil { self?.tunnelManager = manager }
+            completion(error)
+        }
+    }
+
+    // ── 隧道控制 ──────────────────────────────────────────────
+
+    /// 启动 VPN 隧道（通过 NETunnelProviderSession）。
+    /// [configJson]: sing-box 配置 JSON，作为 options 传入 PacketTunnelProvider.startTunnel。
+    func start(configJson: String, completion: @escaping (Error?) -> Void) {
+        guard let manager = tunnelManager else {
+            completion(makeError("VpnManager: tunnelManager not loaded. Call loadFromPreferences first."))
+            return
+        }
+        do {
+            let options: [String: NSObject] = ["config": configJson as NSString]
+            try manager.connection.startVPNTunnel(options: options)
+            completion(nil)
+        } catch {
+            completion(error)
+        }
+    }
+
+    /// 停止 VPN 隧道。
+    func stop() {
+        tunnelManager?.connection.stopVPNTunnel()
+    }
+
+    /// 当前连接状态字符串（供 getStatus MethodChannel 方法使用）。
+    var statusString: String {
+        switch tunnelManager?.connection.status ?? .invalid {
+        case .invalid, .disconnected:  return "off"
+        case .connecting:              return "connecting"
+        case .connected:               return "on"
+        case .disconnecting:           return "connecting"
+        case .reasserting:             return "connecting"
+        @unknown default:              return "error"
+        }
+    }
+
+    // ── IPC 消息通道 ──────────────────────────────────────────
+
+    /// 向 PacketTunnelProvider.handleAppMessage 发送消息。
+    func sendProviderMessage(_ data: Data, responseHandler: ((Data?, Error?) -> Void)?) {
+        guard let session = tunnelManager?.connection as? NETunnelProviderSession else {
+            responseHandler?(nil, makeError("VpnManager: no active NETunnelProviderSession"))
+            return
+        }
+        do {
+            try session.sendProviderMessage(data) { responseData in
+                responseHandler?(responseData, nil)
+            }
+        } catch {
+            responseHandler?(nil, error)
+        }
+    }
+
+    // ── NEVPNStatus 订阅 ──────────────────────────────────────
+
+    private func subscribeToVpnStatus() {
+        statusObserver = NotificationCenter.default.addObserver(
+            forName: NSNotification.Name.NEVPNStatusDidChange,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            guard let self = self else { return }
+            let s = self.statusString
+            VpnStatusStreamHandler.shared.push(s)
+        }
+    }
+
+    deinit {
+        if let obs = statusObserver {
+            NotificationCenter.default.removeObserver(obs)
+        }
+    }
+
+    // ── 工具 ─────────────────────────────────────────────────
+
+    private func makeError(_ message: String) -> NSError {
+        NSError(domain: "VpnManager", code: -1, userInfo: [NSLocalizedDescriptionKey: message])
+    }
+}