envoyproxy · jpsim · Jun 14, 2022 · Jun 15, 2022 · Jun 15, 2022 · Jun 15, 2022
diff --git a/docs/root/api/starting_envoy.rst b/docs/root/api/starting_envoy.rst
@@ -313,13 +313,16 @@ completes. This interface provides the ability to observe when Envoy has complet
 ready to start dispatching requests. Any requests sent through Envoy before this setup completes
 will be queued automatically, and this function is typically used purely for observability.
 
+The closure passes an opaque handle to the engine so that it can be passed to Envoy's C++ APIs if
+desired.
+
 **Example**::
 
   // Kotlin
-  builder.setOnEngineRunning { /*do something*/ }
+  builder.setOnEngineRunning { engineHandle -> /* do something */ }
 
   // Swift
-  builder.setOnEngineRunning { /*do something*/ }
+  builder.setOnEngineRunning { engineHandle in /* do something */ }
 
 ~~~~~~~~~~~~~
 ``setLogger``

diff --git a/docs/root/intro/version_history.rst b/docs/root/intro/version_history.rst
@@ -14,6 +14,7 @@ Breaking changes:
 - 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>`)
 - iOS: release artifacts no longer embed bitcode
+- api: the ``setOnEngineRunning`` closure now passes the engine's opaque ID so it can be passed to Envoy's C++ APis
 
 Bugfixes:
 

diff --git a/examples/java/hello_world/MainActivity.java b/examples/java/hello_world/MainActivity.java
@@ -60,7 +60,7 @@ protected void onCreate(Bundle savedInstanceState) {
 
     engine = new AndroidEngineBuilder(getApplication())
                  .addLogLevel(LogLevel.DEBUG)
-                 .setOnEngineRunning(() -> {
+                 .setOnEngineRunning((ignored) -> {
                    Log.d("MainActivity", "Envoy async internal setup completed");
                    return null;
                  })

diff --git a/examples/objective-c/hello_world/ViewController.m b/examples/objective-c/hello_world/ViewController.m
@@ -39,7 +39,7 @@ - (void)startEnvoy {
   NSLog(@"starting Envoy...");
   EngineBuilder *builder = [[EngineBuilder alloc] init];
   [builder addLogLevel:LogLevelDebug];
-  [builder setOnEngineRunningWithClosure:^{
+  [builder setOnEngineRunningWithClosure:^(NSInteger) {
     NSLog(@"Envoy async internal setup completed");
   }];
 

diff --git a/examples/swift/hello_world/ViewController.swift b/examples/swift/hello_world/ViewController.swift
@@ -24,7 +24,7 @@ final class ViewController: UITableViewController {
       .addPlatformFilter(AsyncDemoFilter.init)
       // swiftlint:disable:next line_length
       .addNativeFilter(name: "envoy.filters.http.buffer", typedConfig: "{\"@type\":\"type.googleapis.com/envoy.extensions.filters.http.buffer.v3.Buffer\",\"max_request_bytes\":5242880}")
-      .setOnEngineRunning { NSLog("Envoy async internal setup completed") }
+      .setOnEngineRunning { _ in NSLog("Envoy async internal setup completed") }
       .addStringAccessor(name: "demo-accessor", accessor: { return "PlatformString" })
       .setEventTracker { NSLog("Envoy event emitted: \($0)") }
       .build()

diff --git a/library/cc/engine_builder.cc b/library/cc/engine_builder.cc
@@ -18,7 +18,7 @@ EngineBuilder& EngineBuilder::addLogLevel(LogLevel log_level) {
   return *this;
 }
 
-EngineBuilder& EngineBuilder::setOnEngineRunning(std::function<void()> closure) {
+EngineBuilder& EngineBuilder::setOnEngineRunning(std::function<void(envoy_engine_t)> closure) {
   this->callbacks_->on_engine_running = closure;
   return *this;
 }

diff --git a/library/cc/engine_builder.h b/library/cc/engine_builder.h
@@ -16,7 +16,7 @@ class EngineBuilder {
   EngineBuilder();
 
   EngineBuilder& addLogLevel(LogLevel log_level);
-  EngineBuilder& setOnEngineRunning(std::function<void()> closure);
+  EngineBuilder& setOnEngineRunning(std::function<void(envoy_engine_t)> closure);
 
   EngineBuilder& addGrpcStatsDomain(const std::string& stats_domain);
   EngineBuilder& addConnectTimeoutSeconds(int connect_timeout_seconds);

diff --git a/library/cc/engine_callbacks.cc b/library/cc/engine_callbacks.cc
@@ -5,9 +5,9 @@ namespace Platform {
 
 namespace {
 
-void c_on_engine_running(void* context) {
+void c_on_engine_running(envoy_engine_t engine, void* context) {
   auto engine_callbacks = *static_cast<EngineCallbacksSharedPtr*>(context);
-  engine_callbacks->on_engine_running();
+  engine_callbacks->on_engine_running(engine);
 }
 
 void c_on_exit(void* context) {

diff --git a/library/cc/engine_callbacks.h b/library/cc/engine_callbacks.h
@@ -10,7 +10,7 @@ namespace Envoy {
 namespace Platform {
 
 struct EngineCallbacks : public std::enable_shared_from_this<EngineCallbacks> {
-  std::function<void()> on_engine_running;
+  std::function<void(envoy_engine_t)> on_engine_running;
   // unused:
   // std::function<void()> on_exit;
 

diff --git a/library/common/engine.cc b/library/common/engine.cc
@@ -122,7 +122,9 @@ envoy_status_t Engine::main(const std::string config, const std::string log_leve
                                                         server_->api().randomGenerator());
           dispatcher_->drain(server_->dispatcher());
           if (callbacks_.on_engine_running != nullptr) {
-            callbacks_.on_engine_running(callbacks_.context);
+            // TODO(jpsim): Update when singleton is removed
+            // reinterpret_cast<envoy_engine_t>(this)
+            callbacks_.on_engine_running(1, callbacks_.context);
           }
         });
   } // mutex_

diff --git a/library/common/jni/jni_interface.cc b/library/common/jni/jni_interface.cc
@@ -26,7 +26,7 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
 
 // JniLibrary
 
-static void jvm_on_engine_running(void* context) {
+static void jvm_on_engine_running(envoy_engine_t engine_handle, void* context) {
   if (context == nullptr) {
     return;
   }
@@ -36,8 +36,8 @@ static void jvm_on_engine_running(void* context) {
   jobject j_context = static_cast<jobject>(context);
   jclass jcls_JvmonEngineRunningContext = env->GetObjectClass(j_context);
   jmethodID jmid_onEngineRunning = env->GetMethodID(
-      jcls_JvmonEngineRunningContext, "invokeOnEngineRunning", "()Ljava/lang/Object;");
-  env->CallObjectMethod(j_context, jmid_onEngineRunning);
+      jcls_JvmonEngineRunningContext, "invokeOnEngineRunning", "(J)Ljava/lang/Object;");
+  env->CallObjectMethod(j_context, jmid_onEngineRunning, static_cast<jlong>(engine_handle));
 
   env->DeleteLocalRef(jcls_JvmonEngineRunningContext);
   // TODO(goaway): This isn't re-used by other engine callbacks, so it's safe to delete here.

diff --git a/library/common/types/c_types.h b/library/common/types/c_types.h
@@ -406,7 +406,7 @@ typedef void (*envoy_on_exit_f)(void* context);
  * @param context, contains the necessary state to carry out platform-specific dispatch and
  * execution.
  */
-typedef void (*envoy_on_engine_running_f)(void* context);
+typedef void (*envoy_on_engine_running_f)(envoy_engine_t engine, void* context);
 
 /**
  * Called when envoy's logger logs data.

diff --git a/library/java/io/envoyproxy/envoymobile/engine/types/EnvoyOnEngineRunning.java b/library/java/io/envoyproxy/envoymobile/engine/types/EnvoyOnEngineRunning.java
@@ -2,5 +2,5 @@
 
 /* Interface used to support lambdas being passed from Kotlin for engine setup completion. */
 public interface EnvoyOnEngineRunning {
-  Object invokeOnEngineRunning();
+  Object invokeOnEngineRunning(long engineHandle);
 }
diff --git a/library/java/org/chromium/net/impl/CronetUrlRequestContext.java b/library/java/org/chromium/net/impl/CronetUrlRequestContext.java
@@ -83,7 +83,7 @@ public CronetUrlRequestContext(NativeCronetEngineBuilderImpl builder) {
         builder.threadPriority(THREAD_PRIORITY_BACKGROUND + THREAD_PRIORITY_MORE_FAVORABLE);
     mUserAgent = builder.getUserAgent();
     synchronized (mLock) {
-      mEngine = builder.createEngine(() -> {
+      mEngine = builder.createEngine((ignored) -> {
         mNetworkThread = Thread.currentThread();
         android.os.Process.setThreadPriority(threadPriority);
         mInitCompleted.open();

diff --git a/library/kotlin/io/envoyproxy/envoymobile/EngineBuilder.kt b/library/kotlin/io/envoyproxy/envoymobile/EngineBuilder.kt
@@ -21,7 +21,7 @@ class Custom(val yaml: String) : BaseConfiguration()
 open class EngineBuilder(
   private val configuration: BaseConfiguration = Standard()
 ) {
-  protected var onEngineRunning: (() -> Unit) = {}
+  protected var onEngineRunning: ((Long) -> Unit) = {}
   protected var logger: ((String) -> Unit)? = null
   protected var eventTracker: ((Map<String, String>) -> Unit)? = null
   private var engineType: () -> EnvoyEngine = {
@@ -435,7 +435,7 @@ open class EngineBuilder(
    *
    * @return this builder.
    */
-  fun setOnEngineRunning(closure: () -> Unit): EngineBuilder {
+  fun setOnEngineRunning(closure: (Long) -> Unit): EngineBuilder {
     this.onEngineRunning = closure
     return this
   }

diff --git a/library/objective-c/EnvoyEngine.h b/library/objective-c/EnvoyEngine.h
@@ -462,7 +462,7 @@ extern const int kEnvoyFailure;
  @param eventTracker Event tracking interface.
  @param networkMonitoringMode Configure how the engines observe network reachability.
  */
-- (instancetype)initWithRunningCallback:(nullable void (^)())onEngineRunning
+- (instancetype)initWithRunningCallback:(nullable void (^)(NSInteger))onEngineRunning
                                  logger:(nullable void (^)(NSString *))logger
                            eventTracker:(nullable void (^)(EnvoyEvent *))eventTracker
                   networkMonitoringMode:(int)networkMonitoringMode;
@@ -586,7 +586,7 @@ extern const int kEnvoyFailure;
 // Concrete implementation of the `EnvoyEngine` interface.
 @interface EnvoyEngineImpl : NSObject <EnvoyEngine>
 
-@property (nonatomic, copy, nullable) void (^onEngineRunning)();
+@property (nonatomic, copy, nullable) void (^onEngineRunning)(NSInteger);
 
 @end
 

diff --git a/library/objective-c/EnvoyEngineImpl.m b/library/objective-c/EnvoyEngineImpl.m
@@ -12,13 +12,13 @@
 #import <UIKit/UIKit.h>
 #endif
 
-static void ios_on_engine_running(void *context) {
+static void ios_on_engine_running(envoy_engine_t engine, void *context) {
   // This code block runs inside the Envoy event loop. Therefore, an explicit autoreleasepool block
   // is necessary to act as a breaker for any Objective-C allocation that happens.
   @autoreleasepool {
     EnvoyEngineImpl *engineImpl = (__bridge EnvoyEngineImpl *)context;
     if (engineImpl.onEngineRunning) {
-      engineImpl.onEngineRunning();
+      engineImpl.onEngineRunning(engine);
     }
   }
 }
@@ -435,7 +435,7 @@ @implementation EnvoyEngineImpl {
   EnvoyNetworkMonitor *_networkMonitor;
 }
 
-- (instancetype)initWithRunningCallback:(nullable void (^)())onEngineRunning
+- (instancetype)initWithRunningCallback:(nullable void (^)(NSInteger))onEngineRunning
                                  logger:(nullable void (^)(NSString *))logger
                            eventTracker:(nullable void (^)(EnvoyEvent *))eventTracker
                   networkMonitoringMode:(int)networkMonitoringMode {

diff --git a/library/python/engine_builder_shim.cc b/library/python/engine_builder_shim.cc
@@ -8,7 +8,8 @@ namespace EngineBuilder {
 
 Platform::EngineBuilder& setOnEngineRunningShim(Platform::EngineBuilder& self,
                                                 std::function<void()> closure) {
-  return self.setOnEngineRunning([closure]() {
+  // TODO(jpsim): Expose engine handle in the Python API
+  return self.setOnEngineRunning([closure](envoy_engine_t) {
     py::gil_scoped_acquire acquire;
     closure();
   });

diff --git a/library/swift/EngineBuilder.swift b/library/swift/EngineBuilder.swift
@@ -39,7 +39,7 @@ open class EngineBuilder: NSObject {
   private var appVersion: String = "unspecified"
   private var appId: String = "unspecified"
   private var virtualClusters: String = "[]"
-  private var onEngineRunning: (() -> Void)?
+  private var onEngineRunning: ((Int) -> Void)?
   private var logger: ((String) -> Void)?
   private var eventTracker: (([String: String]) -> Void)?
   private(set) var monitoringMode: NetworkMonitoringMode = .pathMonitor
@@ -394,11 +394,12 @@ open class EngineBuilder: NSObject {
 
   /// Set a closure to be called when the engine finishes its async startup and begins running.
   ///
-  /// - parameter closure: The closure to be called.
+  /// - parameter closure: The closure to be called. Passes an engine handle that can be used
+  ///                      to interoperate with Envoy's C++ APIs.
   ///
   /// - returns: This builder.
   @discardableResult
-  public func setOnEngineRunning(closure: @escaping () -> Void) -> Self {
+  public func setOnEngineRunning(closure: @escaping (Int) -> Void) -> Self {
     self.onEngineRunning = closure
     return self
   }

diff --git a/library/swift/mocks/MockEnvoyEngine.swift b/library/swift/mocks/MockEnvoyEngine.swift
@@ -3,7 +3,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,
+  init(runningCallback onEngineRunning: ((Int) -> Void)? = nil, logger: ((String) -> Void)? = nil,
        eventTracker: (([String: String]) -> Void)? = nil, networkMonitoringMode: Int32 = 0) {}
 
   /// Closure called when `run(withConfig:)` is called.

diff --git a/test/cc/integration/lifetimes_test.cc b/test/cc/integration/lifetimes_test.cc
@@ -82,7 +82,7 @@ void sendRequestEndToEnd() {
   absl::Notification engine_running;
   auto engine_builder = Platform::EngineBuilder(CONFIG_TEMPLATE);
   engine = engine_builder.addLogLevel(Platform::LogLevel::debug)
-               .setOnEngineRunning([&]() { engine_running.Notify(); })
+               .setOnEngineRunning([&](envoy_engine_t) { engine_running.Notify(); })
                .build();
   engine_running.WaitForNotification();
 

diff --git a/test/cc/integration/send_headers_test.cc b/test/cc/integration/send_headers_test.cc
@@ -60,7 +60,7 @@ TEST(TestSendHeaders, CanSendHeaders) {
   absl::Notification engine_running;
   auto engine_builder = Platform::EngineBuilder(CONFIG_TEMPLATE);
   engine = engine_builder.addLogLevel(Platform::LogLevel::debug)
-               .setOnEngineRunning([&]() { engine_running.Notify(); })
+               .setOnEngineRunning([&](envoy_engine_t) { engine_running.Notify(); })
                .build();
   engine_running.WaitForNotification();
 

diff --git a/test/common/engine_test.cc b/test/common/engine_test.cc
@@ -70,7 +70,7 @@ TEST_F(EngineTest, EarlyExit) {
   const std::string level = "debug";
 
   engine_test_context test_context{};
-  envoy_engine_callbacks callbacks{[](void* context) -> void {
+  envoy_engine_callbacks callbacks{[](envoy_engine_t, void* context) -> void {
                                      auto* engine_running =
                                          static_cast<engine_test_context*>(context);
                                      engine_running->on_engine_running.Notify();
@@ -97,7 +97,7 @@ TEST_F(EngineTest, AccessEngineAfterInitialization) {
   const std::string level = "debug";
 
   engine_test_context test_context{};
-  envoy_engine_callbacks callbacks{[](void* context) -> void {
+  envoy_engine_callbacks callbacks{[](envoy_engine_t, void* context) -> void {
                                      auto* engine_running =
                                          static_cast<engine_test_context*>(context);
                                      engine_running->on_engine_running.Notify();