iOS: add a way to disable network monitoring

docs/root/api/starting_envoy.rst

@@ -370,19 +370,19 @@ Specify a closure to be called by Envoy to access arbitrary strings from Platfor
   builder.addStringAccessor(name: "demo-accessor", accessor: { return "PlatformString" })
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``enableNetworkPathMonitor``
+``setNetworkMonitoringMode``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configure the engine to use ``NWPathMonitor`` rather than ``SCNetworkReachability``
-to update the preferred Envoy network cluster (e.g. WLAN vs WWAN). Defaults to true.
+Configure how the engine observes network reachability state changes to update the preferred Envoy network cluster (e.g. WLAN vs WWAN).
+Defaults to ``NWPathMonitor``, but can be configured to use ``SCNetworkReachability`` or be disabled completely.
 
 **Example**::
 
   // Kotlin
   // N/A
 
   // Swift
-  builder.enableNetworkPathMonitor(false)
+  builder.setNetworkMonitoringMode(.pathMonitor)
 
 ~~~~~~~~~~~~~~~~~~~~~~~
 ``enableHappyEyeballs``

docs/root/intro/version_history.rst

@@ -12,6 +12,7 @@ Breaking changes:
 - net: enable happy eyeballs by default (:issue:`#2272 <2272>`)
 - iOS: remove support for installing via CocoaPods, which had not worked since 2020 (:issue:`#2215 <2215>`)
 - iOS: enable usage of ``NWPathMonitor`` by default (:issue:`#2329 <2329>`)
+- iOS: replace ``enableNetworkPathMonitor`` with a new ``setNetworkMonitoringMode`` API to allow disabling monitoring (:issue:`#2345 <2345>`)
 
 Bugfixes:
 

library/objective-c/EnvoyEngine.h

@@ -456,13 +456,12 @@ extern const int kEnvoyFailure;
  running.
  @param logger Logging interface.
  @param eventTracker Event tracking interface.
- @param enableNetworkPathMonitor Configure the engine to use `NWPathMonitor` to observe network
- reachability.
+ @param networkMonitoringMode Configure how the engines observe network reachability.
  */
 - (instancetype)initWithRunningCallback:(nullable void (^)())onEngineRunning
                                  logger:(nullable void (^)(NSString *))logger
                            eventTracker:(nullable void (^)(EnvoyEvent *))eventTracker
-               enableNetworkPathMonitor:(BOOL)enableNetworkPathMonitor;
+                  networkMonitoringMode:(int)networkMonitoringMode;
 /**
  Run the Envoy engine with the provided configuration and log level.
 

library/objective-c/EnvoyEngineImpl.m

@@ -452,7 +452,7 @@ @implementation EnvoyEngineImpl {
 - (instancetype)initWithRunningCallback:(nullable void (^)())onEngineRunning
                                  logger:(nullable void (^)(NSString *))logger
                            eventTracker:(nullable void (^)(EnvoyEvent *))eventTracker
-               enableNetworkPathMonitor:(BOOL)enableNetworkPathMonitor {
+                  networkMonitoringMode:(int)networkMonitoringMode {
   self = [super init];
   if (!self) {
     return nil;
@@ -483,10 +483,10 @@ - (instancetype)initWithRunningCallback:(nullable void (^)())onEngineRunning
   _engineHandle = init_engine(native_callbacks, native_logger, native_event_tracker);
   _networkMonitor = [[EnvoyNetworkMonitor alloc] initWithEngine:_engineHandle];
 
-  if (enableNetworkPathMonitor) {
-    [_networkMonitor startPathMonitor];
-  } else {
+  if (networkMonitoringMode == 1) {
     [_networkMonitor startReachability];
+  } else if (networkMonitoringMode == 2) {
+    [_networkMonitor startPathMonitor];
   }
 
   return self;

library/swift/BUILD

@@ -19,6 +19,7 @@ swift_library(
         "HeadersBuilder.swift",
         "KeyValueStore.swift",
         "LogLevel.swift",
+        "NetworkMonitoringMode.swift",
         "PulseClient.swift",
         "PulseClientImpl.swift",
         "RequestHeaders.swift",

library/swift/EngineBuilder.swift

@@ -40,7 +40,7 @@ open class EngineBuilder: NSObject {
   private var onEngineRunning: (() -> Void)?
   private var logger: ((String) -> Void)?
   private var eventTracker: (([String: String]) -> Void)?
-  private(set) var enableNetworkPathMonitor = true
+  private(set) var monitoringMode: NetworkMonitoringMode = .pathMonitor
   private var nativeFilterChain: [EnvoyNativeFilterConfig] = []
   private var platformFilterChain: [EnvoyHTTPFilterFactory] = []
   private var stringAccessors: [String: EnvoyStringAccessor] = [:]
@@ -401,13 +401,13 @@ open class EngineBuilder: NSObject {
     return self
   }
 
-  /// Configure the engine to use `NWPathMonitor` to observe network reachability.
-  /// Defaults to `true`. Set to `false` to use `SCNetworkReachability`.
+  /// Configure how the engine observes network reachability state changes.
+  /// Defaults to `.pathMonitor`.
   ///
   /// - returns: This builder.
   @discardableResult
-  public func enableNetworkPathMonitor(_ enableNetworkPathMonitor: Bool) -> Self {
-    self.enableNetworkPathMonitor = enableNetworkPathMonitor
+  public func setNetworkMonitoringMode(_ mode: NetworkMonitoringMode) -> Self {
+    self.monitoringMode = mode
     return self
   }
 
@@ -460,7 +460,7 @@ open class EngineBuilder: NSObject {
   public func build() -> Engine {
     let engine = self.engineType.init(runningCallback: self.onEngineRunning, logger: self.logger,
                                       eventTracker: self.eventTracker,
-                                      enableNetworkPathMonitor: self.enableNetworkPathMonitor)
+                                      networkMonitoringMode: Int32(self.monitoringMode.rawValue))
     let config = EnvoyConfiguration(
       adminInterfaceEnabled: self.adminInterfaceEnabled,
       grpcStatsDomain: self.grpcStatsDomain,

library/swift/NetworkMonitoringMode.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+/// The different ways Envoy Mobile can monitor network reachability
+/// state.
+@objc
+public enum NetworkMonitoringMode: Int {
+  /// Do not monitor changes to the network reachability state.
+  case disabled = 0
+  /// Monitor changes to the network reachability state using `SCNetworkReachability`.
+  case reachability = 1
+  /// Monitor changes to the network reachability state using `NWPathMonitor`.
+  case pathMonitor = 2
+}

library/swift/mocks/MockEnvoyEngine.swift

@@ -4,7 +4,7 @@ import Foundation
 /// Mock implementation of `EnvoyEngine`. Used internally for testing the bridging layer & mocking.
 final class MockEnvoyEngine: NSObject {
   init(runningCallback onEngineRunning: (() -> Void)? = nil, logger: ((String) -> Void)? = nil,
-       eventTracker: (([String: String]) -> Void)? = nil, enableNetworkPathMonitor: Bool = true) {}
+       eventTracker: (([String: String]) -> Void)? = nil, networkMonitoringMode: Int32 = 0) {}
 
   /// Closure called when `run(withConfig:)` is called.
   static var onRunWithConfig: ((_ config: EnvoyConfiguration, _ logLevel: String?) -> Void)?

test/swift/EngineBuilderTests.swift

@@ -28,17 +28,17 @@ final class EngineBuilderTests: XCTestCase {
     MockEnvoyEngine.onRunWithTemplate = nil
   }
 
-  func testEnableNetworkPathMonitorDefaultsToTrue() {
+  func testMonitoringModeDefaultsToPathMonitor() {
     let builder = EngineBuilder()
-    XCTAssertTrue(builder.enableNetworkPathMonitor)
+    XCTAssertEqual(builder.monitoringMode, .pathMonitor)
   }
 
-  func testEnableNetworkPathMonitorSetsToValue() {
+  func testMonitoringModeSetsToValue() {
     let builder = EngineBuilder()
-      .enableNetworkPathMonitor(false)
-    XCTAssertFalse(builder.enableNetworkPathMonitor)
-    builder.enableNetworkPathMonitor(true)
-    XCTAssertTrue(builder.enableNetworkPathMonitor)
+      .setNetworkMonitoringMode(.disabled)
+    XCTAssertEqual(builder.monitoringMode, .disabled)
+    builder.setNetworkMonitoringMode(.reachability)
+    XCTAssertEqual(builder.monitoringMode, .reachability)
   }
 
   func testCustomConfigTemplateUsesSpecifiedYAMLWhenRunningEnvoy() {