feat(bridge): 桥接 API 面 Channel 契约 + 三端原生骨架 [tsk_iP5-_Ztq5THx]

MethodChannel pangolin/vpn (start/stop/getStatus/selectOutbound/ getActiveOutbound/setKillSwitch) + 双 EventChannel (status/stats) 契约定义在 lib/bridge/vpn_bridge.dart 头部注释冻结。 - Dart: VpnBridge 抽象接口 + VpnNativeBridge 原生实现 + VpnBridgeMock 假内核（含 connectDelay/statsInterval 可配参数） - Dart 桌面: kernel_process.dart KernelProcess/ClashApiClient 接口骨架 - Android: PangolinVpnService (VpnService 骨架 + 前台通知占位) + VpnEventBus 解耦总线 + MainActivity MethodChannel/EventChannel 注册 - iOS: PacketTunnelProvider (NEPacketTunnelProvider 骨架) + VpnManager (NETunnelProviderManager + NEVPNStatus 订阅) + AppDelegate 通道注册 + Xcode project.pbxproj 添加 PacketTunnel extension target - Widget: VpnStatus enum 迁移至 bridge/vpn_bridge.dart (+error 态)， connect_button/home_shell 更新穷举匹配 - Test: test/bridge/vpn_bridge_mock_test.dart 覆盖 start→connecting→on →stop→off 序列、stats 周期推帧、selectOutbound 重连序列、schema 回测 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-13 12:06:03 +08:00
parent 787151245e
commit 4992d916d0
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])
+    }
+}