-
Notifications
You must be signed in to change notification settings - Fork 4.8k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
dynamic_modules: scaffolds ABI header and compatibility check (#35626)
Commit Message: dynamic_modules: scaffolds ABI header and compatibility check Additional Description: This commit scaffolds the ABI header and implements the version check. sha256 hash will be calculated on the ABI headers, and the result value is used to check the compatibility. Risk Level: N/A Testing: unit Docs Changes: N/A Release Notes: N/A Platform Specific Features: [Optional Runtime guard:] [Optional Fixes #Issue] [Optional Fixes commit #PR or SHA] [Optional Deprecated:] [Optional [API Considerations](https://github.com/envoyproxy/envoy/blob/main/api/review_checklist.md):] --------- Signed-off-by: Takeshi Yoneda <t.y.mathetake@gmail.com>
- Loading branch information
Showing
16 changed files
with
264 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
#pragma once | ||
|
||
// NOLINT(namespace-envoy) | ||
|
||
// This is a pure C header file that defines the ABI of the core of dynamic modules used by Envoy. | ||
// | ||
// This must not contain any dependencies besides standard library since it is not only used by | ||
// Envoy itself but also by dynamic module SDKs written in non-C++ languages. | ||
// | ||
// Currently, compatibility is only guaranteed by an exact version match between the Envoy | ||
// codebase and the dynamic module SDKs. In the future, after the ABI is stabilized, we will revisit | ||
// this restriction and hopefully provide a wider compatibility guarantee. Until then, Envoy | ||
// checks the hash of the ABI header files to ensure that the dynamic modules are built against the | ||
// same version of the ABI. | ||
|
||
#ifdef __cplusplus | ||
#include <cstddef> | ||
|
||
extern "C" { | ||
#else | ||
#include <stddef.h> | ||
#endif | ||
|
||
// ----------------------------------------------------------------------------- | ||
// ---------------------------------- Types ------------------------------------ | ||
// ----------------------------------------------------------------------------- | ||
// | ||
// Types used in the ABI. The name of a type must be prefixed with "envoy_dynamic_module_type_". | ||
|
||
/** | ||
* envoy_dynamic_module_type_abi_version represents a null-terminated string that contains the ABI | ||
* version of the dynamic module. This is used to ensure that the dynamic module is built against | ||
* the compatible version of the ABI. | ||
*/ | ||
typedef const char* envoy_dynamic_module_type_abi_version; // NOLINT(modernize-use-using) | ||
|
||
// ----------------------------------------------------------------------------- | ||
// ------------------------------- Event Hooks --------------------------------- | ||
// ----------------------------------------------------------------------------- | ||
// | ||
// Event hooks are functions that are called by Envoy in response to certain events. | ||
// The module must implement and export these functions in the dynamic module object file. | ||
// | ||
// Each event hook is defined as a function prototype. The symbol must be prefixed with | ||
// "envoy_dynamic_module_on_". | ||
|
||
/** | ||
* envoy_dynamic_module_on_program_init is called by the main thread exactly when the module is | ||
* loaded. The function returns the ABI version of the dynamic module. If null is returned, the | ||
* module will be unloaded immediately. | ||
* | ||
* For Envoy, the return value will be used to check the compatibility of the dynamic module. | ||
* | ||
* For dynamic modules, this is useful when they need to perform some process-wide | ||
* initialization or check if the module is compatible with the platform, such as CPU features. | ||
* Note that initialization routines of a dynamic module can also be performed without this function | ||
* through constructor functions in an object file. However, normal constructors cannot be used | ||
* to check compatibility and gracefully fail the initialization because there is no way to | ||
* report an error to Envoy. | ||
* | ||
* @return envoy_dynamic_module_type_abi_version is the ABI version of the dynamic module. Null | ||
* means the error and the module will be unloaded immediately. | ||
*/ | ||
envoy_dynamic_module_type_abi_version envoy_dynamic_module_on_program_init(); | ||
|
||
#ifdef __cplusplus | ||
} | ||
#endif |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
#pragma once | ||
#ifdef __cplusplus | ||
namespace Envoy { | ||
namespace Extensions { | ||
namespace DynamicModules { | ||
#endif | ||
// This is the ABI version calculated as a sha256 hash of the ABI header files. When the ABI | ||
// changes, this value must change, and the correctness of this value is checked by the test. | ||
const char* kAbiVersion = "749b1e6bf97309b7d171009700a80e651ac61e35f9770c24a63460d765895a51"; | ||
|
||
#ifdef __cplusplus | ||
} // namespace DynamicModules | ||
} // namespace Extensions | ||
} // namespace Envoy | ||
#endif |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
#include <memory> | ||
|
||
#include "envoy/common/exception.h" | ||
|
||
#include "source/common/common/hex.h" | ||
#include "source/common/crypto/utility.h" | ||
#include "source/extensions/dynamic_modules/abi_version.h" | ||
|
||
#include "test/test_common/environment.h" | ||
#include "test/test_common/utility.h" | ||
|
||
#include "gtest/gtest.h" | ||
|
||
namespace Envoy { | ||
namespace Extensions { | ||
namespace DynamicModules { | ||
|
||
// This test ensure that abi_version.h contains the correct sha256 hash of ABI header files. | ||
TEST(DynamicModules, ABIVersionCheck) { | ||
const auto abi_header_path = | ||
TestEnvironment::substitute("{{ test_rundir }}/source/extensions/dynamic_modules/abi.h"); | ||
// Read the header file and calculate the sha256 hash. | ||
const std::string abi_header = TestEnvironment::readFileToStringForTest(abi_header_path); | ||
const std::string sha256 = | ||
Hex::encode(Envoy::Common::Crypto::UtilitySingleton::get().getSha256Digest( | ||
Buffer::OwnedImpl(abi_header))); | ||
EXPECT_EQ(sha256, kAbiVersion); | ||
} | ||
|
||
} // namespace DynamicModules | ||
} // namespace Extensions | ||
} // namespace Envoy |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
load("//test/extensions/dynamic_modules/test_data/c:test_data.bzl", "test_program") | ||
|
||
licenses(["notice"]) # Apache 2 | ||
|
||
package(default_visibility = ["//test/extensions/dynamic_modules:__pkg__"]) | ||
|
||
test_program(name = "no_op") | ||
|
||
test_program(name = "no_program_init") | ||
|
||
test_program(name = "program_init_fail") | ||
|
||
test_program(name = "abi_version_mismatch") |
5 changes: 5 additions & 0 deletions
5
test/extensions/dynamic_modules/test_data/c/abi_version_mismatch.c
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
#include "source/extensions/dynamic_modules/abi.h" | ||
|
||
envoy_dynamic_module_type_abi_version envoy_dynamic_module_on_program_init() { | ||
return "invalid-version-hash"; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
#include "source/extensions/dynamic_modules/abi.h" | ||
#include "source/extensions/dynamic_modules/abi_version.h" | ||
|
||
int getSomeVariable() { | ||
static int some_variable = 0; | ||
some_variable++; | ||
return some_variable; | ||
} | ||
|
||
envoy_dynamic_module_type_abi_version envoy_dynamic_module_on_program_init() { return kAbiVersion; } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
int foo() { return 0; } |
3 changes: 3 additions & 0 deletions
3
test/extensions/dynamic_modules/test_data/c/program_init_fail.c
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
#include "source/extensions/dynamic_modules/abi.h" | ||
|
||
envoy_dynamic_module_type_abi_version envoy_dynamic_module_on_program_init() { return NULL; } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.