lua: add a shared vm key to tell the lua to share scripts across configurations (#47562)

Commit Message: lua: add a shared vm key to tell the lua to share
scripts across configurations
Additional Description:

Add a `shared_vm_id` to the Lua configuration. If the `shared_vm_id` is
set, then the parsed Lua scripts will be shared globally and the
`shared_vm_id` + script + package paths will be used to the unique cache
key.


Risk Level: low.
Testing: unit.
Docs Changes: n/a.
Release Notes: added.
Platform Specific Features: n/a.

---------

Signed-off-by: wbpcode <wbphub@gmail.com>

Author: wbpcode

api/envoy/extensions/filters/http/lua/v3/lua.proto

@@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // Lua :ref:`configuration overview <config_http_filters_lua>`.
 // [#extension: envoy.filters.http.lua]
 
-// [#next-free-field: 9]
+// [#next-free-field: 10]
 message Lua {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.http.lua.v2.Lua";
@@ -127,9 +127,39 @@ message Lua {
   // ``package.cpath``, i.e. modules which are loadable C libraries rather than Lua source, for
   // example ``/etc/envoy/lua/?.so``.
   repeated string package_cpaths = 8 [(validate.rules).repeated = {items {string {min_len: 1}}}];
+
+  // If set, the Lua VMs this filter builds are shared with every other Lua filter configuration
+  // that sets the same ``shared_vm_id`` and configures the same script, rather than each
+  // configuration building its own. This applies to every script this message configures:
+  // :ref:`default_source_code
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.default_source_code>`,
+  // :ref:`inline_code <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.inline_code>` and
+  // every entry of :ref:`source_codes
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.source_codes>`.
+  //
+  // Sharing is decided per script, not per configuration: two configurations that agree on this
+  // id share a VM only for the scripts whose contents match, and whose :ref:`package_paths
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.package_paths>` and
+  // :ref:`package_cpaths
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.package_cpaths>` match, since a
+  // script that resolves its ``require`` calls differently does not produce an equivalent VM.
+  // A :ref:`LuaPerRoute.shared_vm_id
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.shared_vm_id>` participates in
+  // the same sharing, so a route's inline script can reuse a VM built here and the other way
+  // around.
+  //
+  // A VM is not only an amount of memory, it is also a set of Lua globals that outlive a request.
+  // Scripts sharing a VM therefore see each other's globals, exactly as separate requests through
+  // one configuration already do. Leave this field unset, which is the default, to keep every
+  // configuration's scripts in VMs of their own.
+  //
+  // A shared VM lives for as long as at least one configuration using it is alive. Once the last
+  // one is drained the VM is torn down, and the next configuration asking for that id and script
+  // builds a fresh one.
+  string shared_vm_id = 9;
 }
 
-// [#next-free-field: 7]
+// [#next-free-field: 8]
 message LuaPerRoute {
   oneof override {
     // Disable the Lua filter for this particular vhost or route. If disabled is specified in
@@ -178,4 +208,16 @@ message LuaPerRoute {
   // <envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.package_paths>`, but for
   // ``package.cpath``.
   repeated string package_cpaths = 6 [(validate.rules).repeated = {items {string {min_len: 1}}}];
+
+  // As :ref:`Lua.shared_vm_id
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.shared_vm_id>`, but for the VM built
+  // from this route's :ref:`source_code
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.source_code>`. Routes and
+  // filter configurations share one pool of VMs, so a route setting the same id as a filter
+  // configuration reuses that configuration's VM when the script matches.
+  //
+  // Setting this has no effect when this route selects a script by :ref:`name
+  // <envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.name>`, or configures no
+  // script at all, since that VM belongs to the filter and follows the filter's setting.
+  string shared_vm_id = 7;
 }

changelogs/current/new_features/lua__shared-vm-id.rst

@@ -0,0 +1,6 @@
+Added :ref:`shared_vm_id <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.shared_vm_id>` and
+:ref:`LuaPerRoute.shared_vm_id
+<envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.shared_vm_id>` to the Lua filter.
+Configurations that set the same id share one set of Lua VMs for every script whose contents and
+package search paths match, instead of each building its own. This is off by default: with the
+field unset the filter keeps building one set of VMs per configured script.

docs/root/configuration/http/http_filters/lua_filter.rst

@@ -170,6 +170,50 @@ well. A route which selects a script by :ref:`name
 script at all, runs in a VM belonging to the filter and already has the filter-level patterns; its
 own patterns are unused.
 
+.. _config_http_filters_lua_shared_vm_id:
+
+Sharing Lua VMs between configurations
+--------------------------------------
+
+Every configured script gets its own set of Lua VMs: one per worker thread plus one on the main
+thread. A deployment that repeats the same script across many listeners, filter chains or routes
+therefore pays for the same code many times over. Setting :ref:`shared_vm_id
+<envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.shared_vm_id>` opts a configuration into
+sharing those VMs with every other Lua configuration that sets the same id:
+
+.. code-block:: yaml
+
+  http_filters:
+  - name: envoy.filters.http.lua
+    typed_config:
+      "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
+      shared_vm_id: my_scripts
+      default_source_code:
+        filename: /etc/envoy/lua/common.lua
+
+Sharing is decided per script rather than per configuration. Two configurations that agree on the
+id share a VM only for the scripts whose contents match and whose :ref:`package_paths
+<envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.package_paths>` and :ref:`package_cpaths
+<envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.package_cpaths>` match, since a script that
+resolves its ``require`` calls elsewhere does not produce an equivalent VM. The id applies to every
+script the configuration defines: the default script, the deprecated ``inline_code``, and each
+entry of :ref:`source_codes <envoy_v3_api_field_extensions.filters.http.lua.v3.Lua.source_codes>`.
+Routes draw from the same pool, so a route setting :ref:`LuaPerRoute.shared_vm_id
+<envoy_v3_api_field_extensions.filters.http.lua.v3.LuaPerRoute.shared_vm_id>` can reuse a VM a
+filter configuration already built, and the other way around.
+
+.. attention::
+
+  A Lua VM is not only an amount of memory, it is also a set of Lua globals that outlive a
+  request. Scripts sharing a VM see each other's globals, exactly as separate requests through one
+  configuration already do. Only share VMs between configurations whose scripts are prepared for
+  that.
+
+A shared VM lives for as long as at least one configuration using it is alive. Once the last one is
+drained the VM is torn down, and the next configuration asking for that id and script builds a
+fresh one. Leaving the field unset, which is the default, keeps every configuration's scripts in
+VMs of their own.
+
 Upstream Filter
 ---------------
 
@@ -196,7 +240,8 @@ individual filter instance/script can be tracked by providing a per-filter
 In addition, a single process-wide ``lua.lua_vm_count`` gauge (not affected by ``stat_prefix``) tracks
 the total number of active Lua VMs across every filter-config-level and route-level Lua script
 configured in the process. Each configured script accounts for ``concurrency + 1`` VMs (one per
-worker thread, plus the main thread).
+worker thread, plus the main thread), except that scripts sharing VMs through :ref:`shared_vm_id
+<config_http_filters_lua_shared_vm_id>` are counted once between them.
 
 Script examples
 ---------------

source/extensions/filters/http/lua/BUILD

@@ -20,9 +20,12 @@ envoy_cc_library(
         ":wrappers_lib",
         "//envoy/http:codes_interface",
         "//envoy/http:filter_interface",
+        "//envoy/singleton:manager_interface",
         "//envoy/upstream:cluster_manager_interface",
         "//source/common/buffer:buffer_lib",
         "//source/common/common:enum_to_int",
+        "//source/common/common:hex_lib",
+        "//source/common/common:thread_lib",
         "//source/common/config:datasource_lib",
         "//source/common/crypto:utility_lib",
         "//source/common/http:message_lib",
@@ -31,6 +34,7 @@ envoy_cc_library(
         "//source/extensions/filters/common/lua:protobuf_converter_lib",
         "//source/extensions/filters/common/lua:wrappers_lib",
         "//source/extensions/filters/http/common:factory_base_lib",
+        "@abseil-cpp//absl/container:flat_hash_map",
         "@abseil-cpp//absl/strings",
         "@envoy_api//envoy/extensions/filters/http/lua/v3:pkg_cc_proto",
     ],

source/extensions/filters/http/lua/config.cc

@@ -16,10 +16,10 @@ absl::StatusOr<Envoy::Http::FilterFactoryCb> LuaFilterConfig::createHttpFilterFa
     Server::Configuration::ServerFactoryContext& context,
     Server::Configuration::ExtraFactoryContext& extra_context) {
   absl::Status creation_status = absl::OkStatus();
-  FilterConfigConstSharedPtr filter_config(
-      new FilterConfig{proto_config, context.threadLocal(), context.clusterManager(), context.api(),
-                       extra_context.scopeOr(context), extra_context.stats_prefix,
-                       context.options().concurrency(), creation_status});
+  FilterConfigConstSharedPtr filter_config(new FilterConfig{
+      proto_config, context.threadLocal(), context.clusterManager(), context.api(),
+      extra_context.scopeOr(context), extra_context.stats_prefix, context.options().concurrency(),
+      context.singletonManager(), creation_status});
   RETURN_IF_NOT_OK_REF(creation_status);
   auto& time_source = context.mainThreadDispatcher().timeSource();
   return [filter_config, &time_source](Http::FilterChainFactoryCallbacks& callbacks) -> void {

source/extensions/filters/http/lua/lua_filter.cc

@@ -13,12 +13,16 @@
 #include "source/common/buffer/buffer_impl.h"
 #include "source/common/common/assert.h"
 #include "source/common/common/enum_to_int.h"
+#include "source/common/common/hex.h"
+#include "source/common/common/thread.h"
 #include "source/common/config/datasource.h"
 #include "source/common/crypto/crypto_impl.h"
 #include "source/common/crypto/utility.h"
 #include "source/common/http/message_impl.h"
 
+#include "absl/container/flat_hash_map.h"
 #include "absl/strings/escaping.h"
+#include "absl/strings/str_cat.h"
 #include "absl/strings/str_join.h"
 
 namespace Envoy {
@@ -212,6 +216,85 @@ Stats::Gauge& lookupLuaVmCountGauge(Stats::Scope& server_scope) {
 
 } // namespace
 
+SINGLETON_MANAGER_REGISTRATION(lua_shared_http_filter_code_setups);
+
+namespace {
+
+// Identifies a shareable VM setup. The digest covers the package search paths as well as the
+// code, because two configurations that agree on an id and on a script but disagree on where
+// `require` looks for modules do not describe equivalent VMs and must not share one. Each part
+// is length-prefixed so that no two distinct inputs produce the same string to digest.
+std::string sharedVmKey(absl::string_view shared_vm_id, absl::string_view lua_code,
+                        const Filters::Common::Lua::PackagePaths& package_paths) {
+  const std::string digest_input =
+      absl::StrCat(lua_code.size(), ":", lua_code, package_paths.path.size(), ":",
+                   package_paths.path, package_paths.cpath.size(), ":", package_paths.cpath);
+  // The digest is a fixed-length hex string at the end of the key, so an id that happens to
+  // contain the separator cannot be mistaken for a different id with a different digest.
+  return absl::StrCat(
+      shared_vm_id, "/",
+      Hex::encode(Envoy::Common::Crypto::UtilitySingleton::get().getSha256Digest(digest_input)));
+}
+
+SharedLuaCodeSetupRegistrySharedPtr sharedCodeSetupRegistry(Singleton::Manager& singleton_manager) {
+  return singleton_manager.getTyped<SharedLuaCodeSetupRegistry>(
+      SINGLETON_MANAGER_REGISTERED_NAME(lua_shared_http_filter_code_setups),
+      [] { return std::make_shared<SharedLuaCodeSetupRegistry>(); });
+}
+
+// Builds the VM setup for one configured script, reusing an already built one when the
+// configuration opted into sharing. `registry` is null when it did not, which keeps the
+// original behavior of one dedicated set of VMs per configured script.
+PerLuaCodeSetupSharedPtr
+createPerLuaCodeSetup(const SharedLuaCodeSetupRegistrySharedPtr& registry,
+                      absl::string_view shared_vm_id, const std::string& lua_code,
+                      const Filters::Common::Lua::PackagePaths& package_paths,
+                      ThreadLocal::SlotAllocator& tls, Stats::Gauge& vm_count_gauge,
+                      uint32_t concurrency, absl::Status& creation_status) {
+  if (registry == nullptr) {
+    return std::make_shared<PerLuaCodeSetup>(lua_code, package_paths, tls, vm_count_gauge,
+                                             concurrency, creation_status);
+  }
+  return registry->getOrCreate(shared_vm_id, lua_code, package_paths, tls, vm_count_gauge,
+                               concurrency, creation_status);
+}
+
+} // namespace
+
+PerLuaCodeSetupSharedPtr SharedLuaCodeSetupRegistry::getOrCreate(
+    absl::string_view shared_vm_id, const std::string& lua_code,
+    const Filters::Common::Lua::PackagePaths& package_paths, ThreadLocal::SlotAllocator& tls,
+    Stats::Gauge& vm_count_gauge, uint32_t concurrency, absl::Status& creation_status) {
+  // Filter and route configurations are only ever built on the main thread, so the map needs no
+  // lock. Nothing touches it when a setup is released, which is what makes that safe: a setup
+  // whose last owner goes away on a worker thread just leaves an expired entry behind.
+  ASSERT_IS_MAIN_OR_TEST_THREAD();
+
+  const std::string key = sharedVmKey(shared_vm_id, lua_code, package_paths);
+  const auto it = setups_.find(key);
+  if (it != setups_.end()) {
+    if (PerLuaCodeSetupSharedPtr setup = it->second.lock()) {
+      ENVOY_LOG(debug, "reusing shared Lua VM for shared_vm_id '{}'", shared_vm_id);
+      return setup;
+    }
+  }
+
+  PerLuaCodeSetupSharedPtr setup = std::make_shared<PerLuaCodeSetup>(
+      lua_code, package_paths, tls, vm_count_gauge, concurrency, creation_status);
+  if (!creation_status.ok()) {
+    // A script that does not parse is rejected for this configuration; it must not be handed to
+    // the next one that asks for the same id.
+    return nullptr;
+  }
+
+  // Drop the entries whose last user has gone away, so that a server churning through scripts
+  // over its lifetime does not accumulate dead keys.
+  absl::erase_if(setups_, [](const auto& entry) { return entry.second.expired(); });
+  setups_[key] = setup;
+  ENVOY_LOG(debug, "created shared Lua VM for shared_vm_id '{}'", shared_vm_id);
+  return setup;
+}
+
 PerLuaCodeSetup::PerLuaCodeSetup(const std::string& lua_code,
                                  const Filters::Common::Lua::PackagePaths& package_paths,
                                  ThreadLocal::SlotAllocator& tls, Stats::Gauge& vm_count_gauge,
@@ -925,7 +1008,8 @@ FilterConfig::FilterConfig(const envoy::extensions::filters::http::lua::v3::Lua&
                            ThreadLocal::SlotAllocator& tls,
                            Upstream::ClusterManager& cluster_manager, Api::Api& api,
                            Stats::Scope& scope, const std::string& stats_prefix,
-                           uint32_t concurrency, absl::Status& creation_status)
+                           uint32_t concurrency, Singleton::Manager& singleton_manager,
+                           absl::Status& creation_status)
     : cluster_manager_(cluster_manager),
       clear_route_cache_(
           proto_config.has_clear_route_cache() ? proto_config.clear_route_cache().value() : true),
@@ -938,6 +1022,11 @@ FilterConfig::FilterConfig(const envoy::extensions::filters::http::lua::v3::Lua&
   Stats::Gauge& vm_count_gauge = lookupLuaVmCountGauge(api.rootScope());
   const Filters::Common::Lua::PackagePaths package_paths =
       packagePaths(proto_config.package_paths(), proto_config.package_cpaths());
+  // Left null when no id is configured, which is what tells the helper below to build VMs that
+  // belong to this configuration alone.
+  if (!proto_config.shared_vm_id().empty()) {
+    shared_code_setup_registry_ = sharedCodeSetupRegistry(singleton_manager);
+  }
 
   if (proto_config.has_default_source_code()) {
     if (!proto_config.inline_code().empty()) {
@@ -949,21 +1038,23 @@ FilterConfig::FilterConfig(const envoy::extensions::filters::http::lua::v3::Lua&
 
     auto code_or = Config::DataSource::read(proto_config.default_source_code(), true, api);
     SET_AND_RETURN_IF_NOT_OK(code_or.status(), creation_status);
-    default_lua_code_setup_ = std::make_unique<PerLuaCodeSetup>(
-        code_or.value(), package_paths, tls, vm_count_gauge, concurrency, creation_status);
+    default_lua_code_setup_ = createPerLuaCodeSetup(
+        shared_code_setup_registry_, proto_config.shared_vm_id(), code_or.value(), package_paths,
+        tls, vm_count_gauge, concurrency, creation_status);
     RETURN_ONLY_IF_NOT_OK_REF(creation_status);
   } else if (!proto_config.inline_code().empty()) {
-    default_lua_code_setup_ =
-        std::make_unique<PerLuaCodeSetup>(proto_config.inline_code(), package_paths, tls,
-                                          vm_count_gauge, concurrency, creation_status);
+    default_lua_code_setup_ = createPerLuaCodeSetup(
+        shared_code_setup_registry_, proto_config.shared_vm_id(), proto_config.inline_code(),
+        package_paths, tls, vm_count_gauge, concurrency, creation_status);
     RETURN_ONLY_IF_NOT_OK_REF(creation_status);
   }
 
   for (const auto& source : proto_config.source_codes()) {
     auto code_or = Config::DataSource::read(source.second, true, api);
     SET_AND_RETURN_IF_NOT_OK(code_or.status(), creation_status);
-    auto per_lua_code_setup_ptr = std::make_unique<PerLuaCodeSetup>(
-        code_or.value(), package_paths, tls, vm_count_gauge, concurrency, creation_status);
+    auto per_lua_code_setup_ptr = createPerLuaCodeSetup(
+        shared_code_setup_registry_, proto_config.shared_vm_id(), code_or.value(), package_paths,
+        tls, vm_count_gauge, concurrency, creation_status);
     RETURN_ONLY_IF_NOT_OK_REF(creation_status);
     per_lua_code_setups_map_[source.first] = std::move(per_lua_code_setup_ptr);
   }
@@ -982,9 +1073,13 @@ FilterConfigPerRoute::FilterConfigPerRoute(
     auto code_or = Config::DataSource::read(config.source_code(), true, context.api());
     SET_AND_RETURN_IF_NOT_OK(code_or.status(), creation_status);
     Stats::Gauge& vm_count_gauge = lookupLuaVmCountGauge(context.api().rootScope());
-    per_lua_code_setup_ptr_ = std::make_unique<PerLuaCodeSetup>(
-        code_or.value(), packagePaths(config.package_paths(), config.package_cpaths()),
-        context.threadLocal(), vm_count_gauge, context.options().concurrency(), creation_status);
+    if (!config.shared_vm_id().empty()) {
+      shared_code_setup_registry_ = sharedCodeSetupRegistry(context.singletonManager());
+    }
+    per_lua_code_setup_ptr_ = createPerLuaCodeSetup(
+        shared_code_setup_registry_, config.shared_vm_id(), code_or.value(),
+        packagePaths(config.package_paths(), config.package_cpaths()), context.threadLocal(),
+        vm_count_gauge, context.options().concurrency(), creation_status);
   }
 }