#pragma once

// NOLINT(namespace-envoy)

// This is a pure C header, so we can't apply clang-tidy to it.

// NOLINTBEGIN

// 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.

//

// There are three kinds defined in this file:

//

//  * Types: type definitions used in the ABI.

//  * Events Hooks: functions that modules must implement to handle events from Envoy.

//  * Callbacks: functions that Envoy implements and modules can call to interact with Envoy.

//

// Types are prefixed with "envoy_dynamic_module_type_". Event Hooks are prefixed with

// "envoy_dynamic_module_on_". Callbacks are prefixed with "envoy_dynamic_module_callback_".

//

// Some functions are specified/defined under the assumptions that all dynamic modules are trusted

// and have the same privilege level as the main Envoy program. This is because they run inside the

// Envoy process, hence they can access all the memory and resources that the main Envoy process

// can, which makes it impossible to enforce any security boundaries between Envoy and the modules

// by nature. For example, we assume that modules will not try to pass invalid pointers to Envoy

// intentionally.

// This is the ABI version that we bump the minor version at least once for any ABI changes in same

// Envoy release cycle to indicate the ABI change.

//

// Break change in the ABI is not allowed except the ABI has not been released yet.

//

// Until we reach v1.0, we only guarantee backward

// compatibility in the next minor version. For example, v0.1.y is guaranteed to be compatible with

// v0.2.x, but not with v0.3.x.

//

// This is used only for tracking the ABI version of dynamic modules and emitting warnings when

// there's a mismatch.

//

// Note(internal): We could use the Envoy's version such as "v1.38.0" here, there are several

// reasons as to why we use a static version string instead:

// 1. Envoy's version is generated at the build time of Envoy while we need to make it available for

// SDK downstream users.

// 2. In the future, after the stable ABI is established, we may want to decouple the ABI version

// from Envoy's versioning scheme.

#ifdef __cplusplus

#include <cstdbool>

#include <cstddef>

#include <cstdint>

constexpr const char* envoy_dynamic_modules_abi_version = ENVOY_DYNAMIC_MODULES_ABI_VERSION;

extern "C" {

#else

const char* __attribute__((weak)) envoy_dynamic_modules_abi_version =

    ENVOY_DYNAMIC_MODULES_ABI_VERSION;

#include <stdbool.h>

#include <stddef.h>

#include <stdint.h>

#endif

// =============================================================================

// ==================================== Common =================================

// =============================================================================

// =============================================================================

// Common Types

// =============================================================================

/**

 * envoy_dynamic_module_type_abi_version_module_ptr 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.

 *

 * OWNERSHIP: Module owns the pointer. The string must remain valid until the end of

 * envoy_dynamic_module_on_program_init function.

 */

typedef const char* envoy_dynamic_module_type_abi_version_module_ptr;

/**

 * envoy_dynamic_module_type_buffer_module_ptr is a pointer to a buffer in the module. A buffer

 * represents a contiguous block of memory in bytes.

 *

 * OWNERSHIP: The module is responsible for managing the lifetime of the pointer. It depends on the

 * context where the buffer is used. See for the specific event hook or callback for more details.

 */

typedef const char* envoy_dynamic_module_type_buffer_module_ptr;

/**

 * envoy_dynamic_module_type_buffer_envoy_ptr is a pointer to a buffer in Envoy. A buffer represents

 * a contiguous block of memory in bytes.

 *

 * OWNERSHIP: Envoy owns the pointer. The lifetime depends on the context where the buffer is used.

 * See for the specific event hook or callback for more details.

 */

typedef const char* envoy_dynamic_module_type_buffer_envoy_ptr;

/**

 * envoy_dynamic_module_type_envoy_buffer represents a buffer owned by Envoy.

 * This is to give the direct access to the buffer in Envoy.

 */

typedef struct envoy_dynamic_module_type_envoy_buffer {

  envoy_dynamic_module_type_buffer_envoy_ptr ptr;

  size_t length;

} envoy_dynamic_module_type_envoy_buffer;

/**

 * envoy_dynamic_module_type_module_buffer represents a buffer owned by the module.

 */

typedef struct envoy_dynamic_module_type_module_buffer {

  envoy_dynamic_module_type_buffer_module_ptr ptr;

  size_t length;

} envoy_dynamic_module_type_module_buffer;

/**

 * envoy_dynamic_module_type_module_http_header represents a key-value pair of an HTTP header owned

 * by the module.

 */

typedef struct envoy_dynamic_module_type_module_http_header {

  envoy_dynamic_module_type_buffer_module_ptr key_ptr;

  size_t key_length;

  envoy_dynamic_module_type_buffer_module_ptr value_ptr;

  size_t value_length;

} envoy_dynamic_module_type_module_http_header;

/**

 * envoy_dynamic_module_type_envoy_http_header represents a key-value pair of an HTTP header owned

 * by Envoy's HeaderMap.

 */

typedef struct envoy_dynamic_module_type_envoy_http_header {

  envoy_dynamic_module_type_buffer_envoy_ptr key_ptr;

  size_t key_length;

  envoy_dynamic_module_type_buffer_envoy_ptr value_ptr;

  size_t value_length;

} envoy_dynamic_module_type_envoy_http_header;

typedef enum envoy_dynamic_module_type_http_header_type {

  envoy_dynamic_module_type_http_header_type_RequestHeader,

  envoy_dynamic_module_type_http_header_type_RequestTrailer,

  envoy_dynamic_module_type_http_header_type_ResponseHeader,

  envoy_dynamic_module_type_http_header_type_ResponseTrailer,

} envoy_dynamic_module_type_http_header_type;

/**

 * envoy_dynamic_module_type_log_level represents the log level passed to

 * envoy_dynamic_module_callback_log. This corresponds to the enum defined in

 * source/common/common/base_logger.h.

 */

typedef enum envoy_dynamic_module_type_log_level {

  envoy_dynamic_module_type_log_level_Trace,

  envoy_dynamic_module_type_log_level_Debug,

  envoy_dynamic_module_type_log_level_Info,

  envoy_dynamic_module_type_log_level_Warn,

  envoy_dynamic_module_type_log_level_Error,

  envoy_dynamic_module_type_log_level_Critical,

  envoy_dynamic_module_type_log_level_Off,

} envoy_dynamic_module_type_log_level;

/**

 * envoy_dynamic_module_type_http_callout_init_result represents the result of the HTTP callout

 * initialization after envoy_dynamic_module_callback_http_filter_http_callout is called.

 * Success means the callout is successfully initialized and ready to be used.

 * MissingRequiredHeaders means the callout is missing one of the required headers, :path, :method,

 * or host header. DuplicateCalloutId means the callout id is already used by another callout.

 * ClusterNotFound means the cluster is not found in the configuration. CannotCreateRequest means

 * the request cannot be created. That happens when, for example, there's no healthy upstream host

 * in the cluster.

 */

typedef enum envoy_dynamic_module_type_http_callout_init_result {

  envoy_dynamic_module_type_http_callout_init_result_Success,

  envoy_dynamic_module_type_http_callout_init_result_MissingRequiredHeaders,

  envoy_dynamic_module_type_http_callout_init_result_ClusterNotFound,

  envoy_dynamic_module_type_http_callout_init_result_DuplicateCalloutId,

  envoy_dynamic_module_type_http_callout_init_result_CannotCreateRequest,

} envoy_dynamic_module_type_http_callout_init_result;

/**

 * envoy_dynamic_module_type_http_callout_result represents the result of the HTTP callout.

 * This corresponds to `AsyncClient::FailureReason::*` in envoy/http/async_client.h plus Success.

 */

typedef enum envoy_dynamic_module_type_http_callout_result {

  envoy_dynamic_module_type_http_callout_result_Success,

  envoy_dynamic_module_type_http_callout_result_Reset,

  envoy_dynamic_module_type_http_callout_result_ExceedResponseBufferLimit,

} envoy_dynamic_module_type_http_callout_result;

/**

 * envoy_dynamic_module_type_http_stream_reset_reason represents the reason for a stream reset.

 * This corresponds to `AsyncClient::StreamResetReason::*` in envoy/http/async_client.h.

 */

typedef enum envoy_dynamic_module_type_http_stream_reset_reason {

  envoy_dynamic_module_type_http_stream_reset_reason_ConnectionFailure,

  envoy_dynamic_module_type_http_stream_reset_reason_ConnectionTermination,

  envoy_dynamic_module_type_http_stream_reset_reason_LocalReset,

  envoy_dynamic_module_type_http_stream_reset_reason_LocalRefusedStreamReset,

  envoy_dynamic_module_type_http_stream_reset_reason_Overflow,

  envoy_dynamic_module_type_http_stream_reset_reason_RemoteReset,

  envoy_dynamic_module_type_http_stream_reset_reason_RemoteRefusedStreamReset,

  envoy_dynamic_module_type_http_stream_reset_reason_ProtocolError,

} envoy_dynamic_module_type_http_stream_reset_reason;

/**

 * envoy_dynamic_module_type_metrics_result represents the result of the metrics operation.

 * Success means the operation was successful.

 * MetricNotFound means the metric was not found. This is usually an indication that a handle was

 * improperly initialized or stored. InvalidLabels means the labels are invalid. Frozen means a

 * metric was attempted to be created when the stats creation is frozen.

 */

typedef enum envoy_dynamic_module_type_metrics_result {

  envoy_dynamic_module_type_metrics_result_Success,

  envoy_dynamic_module_type_metrics_result_MetricNotFound,

  envoy_dynamic_module_type_metrics_result_InvalidLabels,

  envoy_dynamic_module_type_metrics_result_Frozen,

} envoy_dynamic_module_type_metrics_result;

/**

 * envoy_dynamic_module_type_metadata_source represents the location of metadata to get when calling

 * envoy_dynamic_module_callback_http_get_metadata_* functions.

 */

typedef enum envoy_dynamic_module_type_metadata_source {

  // stream's dynamic metadata.

  envoy_dynamic_module_type_metadata_source_Dynamic,

  // route metadata

  envoy_dynamic_module_type_metadata_source_Route,

  // cluster metadata

  envoy_dynamic_module_type_metadata_source_Cluster,

  // host (LbEndpoint in xDS) metadata

  envoy_dynamic_module_type_metadata_source_Host,

  // host locality (LocalityLbEndpoints in xDS) metadata

  envoy_dynamic_module_type_metadata_source_HostLocality,

} envoy_dynamic_module_type_metadata_source;

/**

 * envoy_dynamic_module_type_attribute_id represents an attribute described in

 * https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/advanced/attributes

 */

typedef enum envoy_dynamic_module_type_attribute_id {

  // request.path

  envoy_dynamic_module_type_attribute_id_RequestPath,

  // request.url_path

  envoy_dynamic_module_type_attribute_id_RequestUrlPath,

  // request.host

  envoy_dynamic_module_type_attribute_id_RequestHost,

  // request.scheme

  envoy_dynamic_module_type_attribute_id_RequestScheme,

  // request.method

  envoy_dynamic_module_type_attribute_id_RequestMethod,

  // request.headers

  envoy_dynamic_module_type_attribute_id_RequestHeaders,

  // request.referer

  envoy_dynamic_module_type_attribute_id_RequestReferer,

  // request.useragent

  envoy_dynamic_module_type_attribute_id_RequestUserAgent,

  // request.time

  envoy_dynamic_module_type_attribute_id_RequestTime,

  // request.id

  envoy_dynamic_module_type_attribute_id_RequestId,

  // request.protocol

  envoy_dynamic_module_type_attribute_id_RequestProtocol,

  // request.query

  envoy_dynamic_module_type_attribute_id_RequestQuery,

  // request.duration

  envoy_dynamic_module_type_attribute_id_RequestDuration,

  // request.size

  envoy_dynamic_module_type_attribute_id_RequestSize,

  // request.total_size

  envoy_dynamic_module_type_attribute_id_RequestTotalSize,

  // response.code

  envoy_dynamic_module_type_attribute_id_ResponseCode,

  // response.code_details

  envoy_dynamic_module_type_attribute_id_ResponseCodeDetails,

  // response.flags

  envoy_dynamic_module_type_attribute_id_ResponseFlags,

  // response.grpc_status

  envoy_dynamic_module_type_attribute_id_ResponseGrpcStatus,

  // response.headers

  envoy_dynamic_module_type_attribute_id_ResponseHeaders,

  // response.trailers

  envoy_dynamic_module_type_attribute_id_ResponseTrailers,

  // response.size

  envoy_dynamic_module_type_attribute_id_ResponseSize,

  // response.total_size

  envoy_dynamic_module_type_attribute_id_ResponseTotalSize,

  // response.backend_latency

  envoy_dynamic_module_type_attribute_id_ResponseBackendLatency,

  // source.address

  envoy_dynamic_module_type_attribute_id_SourceAddress,

  // source.port

  envoy_dynamic_module_type_attribute_id_SourcePort,

  // destination.address

  envoy_dynamic_module_type_attribute_id_DestinationAddress,

  // destination.port

  envoy_dynamic_module_type_attribute_id_DestinationPort,

  // connection.id

  envoy_dynamic_module_type_attribute_id_ConnectionId,

  // connection.mtls

  envoy_dynamic_module_type_attribute_id_ConnectionMtls,

  // connection.requested_server_name

  envoy_dynamic_module_type_attribute_id_ConnectionRequestedServerName,

  // connection.tls_version

  envoy_dynamic_module_type_attribute_id_ConnectionTlsVersion,

  // connection.subject_local_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionSubjectLocalCertificate,

  // connection.subject_peer_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionSubjectPeerCertificate,

  // connection.dns_san_local_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionDnsSanLocalCertificate,

  // connection.dns_san_peer_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionDnsSanPeerCertificate,

  // connection.uri_san_local_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionUriSanLocalCertificate,

  // connection.uri_san_peer_certificate

  envoy_dynamic_module_type_attribute_id_ConnectionUriSanPeerCertificate,

  // connection.sha256_peer_certificate_digest

  envoy_dynamic_module_type_attribute_id_ConnectionSha256PeerCertificateDigest,

  // connection.transport_failure_reason

  envoy_dynamic_module_type_attribute_id_ConnectionTransportFailureReason,

  // connection.termination_details

  envoy_dynamic_module_type_attribute_id_ConnectionTerminationDetails,

  // upstream.address

  envoy_dynamic_module_type_attribute_id_UpstreamAddress,

  // upstream.port

  envoy_dynamic_module_type_attribute_id_UpstreamPort,

  // upstream.tls_version

  envoy_dynamic_module_type_attribute_id_UpstreamTlsVersion,

  // upstream.subject_local_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamSubjectLocalCertificate,

  // upstream.subject_peer_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamSubjectPeerCertificate,

  // upstream.dns_san_local_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamDnsSanLocalCertificate,

  // upstream.dns_san_peer_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamDnsSanPeerCertificate,

  // upstream.uri_san_local_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamUriSanLocalCertificate,

  // upstream.uri_san_peer_certificate

  envoy_dynamic_module_type_attribute_id_UpstreamUriSanPeerCertificate,

  // upstream.sha256_peer_certificate_digest

  envoy_dynamic_module_type_attribute_id_UpstreamSha256PeerCertificateDigest,

  // upstream.local_address

  envoy_dynamic_module_type_attribute_id_UpstreamLocalAddress,

  // upstream.transport_failure_reason

  envoy_dynamic_module_type_attribute_id_UpstreamTransportFailureReason,

  // upstream.request_attempt_count

  envoy_dynamic_module_type_attribute_id_UpstreamRequestAttemptCount,

  // upstream.cx_pool_ready_duration

  envoy_dynamic_module_type_attribute_id_UpstreamCxPoolReadyDuration,

  // upstream.locality

  envoy_dynamic_module_type_attribute_id_UpstreamLocality,

  // xds.node

  envoy_dynamic_module_type_attribute_id_XdsNode,

  // xds.cluster_name

  envoy_dynamic_module_type_attribute_id_XdsClusterName,

  // xds.cluster_metadata

  envoy_dynamic_module_type_attribute_id_XdsClusterMetadata,

  // xds.listener_direction

  envoy_dynamic_module_type_attribute_id_XdsListenerDirection,

  // xds.listener_metadata

  envoy_dynamic_module_type_attribute_id_XdsListenerMetadata,

  // xds.route_name

  envoy_dynamic_module_type_attribute_id_XdsRouteName,

  // xds.route_metadata

  envoy_dynamic_module_type_attribute_id_XdsRouteMetadata,

  // xds.virtual_host_name

  envoy_dynamic_module_type_attribute_id_XdsVirtualHostName,

  // xds.virtual_host_metadata

  envoy_dynamic_module_type_attribute_id_XdsVirtualHostMetadata,

  // xds.upstream_host_metadata

  envoy_dynamic_module_type_attribute_id_XdsUpstreamHostMetadata,

  // xds.filter_chain_name

  envoy_dynamic_module_type_attribute_id_XdsFilterChainName,

} envoy_dynamic_module_type_attribute_id;

/**

 * envoy_dynamic_module_type_socket_option_state represents the socket state at which an option

 * should be applied.

 */

typedef enum envoy_dynamic_module_type_socket_option_state {

  envoy_dynamic_module_type_socket_option_state_Prebind = 0,

  envoy_dynamic_module_type_socket_option_state_Bound = 1,

  envoy_dynamic_module_type_socket_option_state_Listening = 2,

} envoy_dynamic_module_type_socket_option_state;

/**

 * envoy_dynamic_module_type_socket_option_value_type represents the type of value stored in a

 * socket option.

 */

typedef enum envoy_dynamic_module_type_socket_option_value_type {

  envoy_dynamic_module_type_socket_option_value_type_Int = 0,

  envoy_dynamic_module_type_socket_option_value_type_Bytes = 1,

} envoy_dynamic_module_type_socket_option_value_type;

/**

 * envoy_dynamic_module_type_socket_option represents a socket option with its level, name, state,

 * and value. The value can be either an integer or bytes depending on value_type.

 */

typedef struct envoy_dynamic_module_type_socket_option {

  int64_t level;

  int64_t name;

  envoy_dynamic_module_type_socket_option_state state;

  envoy_dynamic_module_type_socket_option_value_type value_type;

  int64_t int_value;

  envoy_dynamic_module_type_envoy_buffer byte_value;

} envoy_dynamic_module_type_socket_option;

/**

 * envoy_dynamic_module_type_address_type represents the socket address type.

 */

typedef enum envoy_dynamic_module_type_address_type {

  envoy_dynamic_module_type_address_type_Unknown = 0,

  envoy_dynamic_module_type_address_type_Ip = 1,

  envoy_dynamic_module_type_address_type_Pipe = 2,

  envoy_dynamic_module_type_address_type_EnvoyInternal = 3,

} envoy_dynamic_module_type_address_type;

/**

 * envoy_dynamic_module_type_socket_direction represents whether the socket option should be

 * applied to the upstream (outgoing to backend) or downstream (incoming from client) connection.

 */

typedef enum envoy_dynamic_module_type_socket_direction {

  envoy_dynamic_module_type_socket_direction_Upstream = 0,

  envoy_dynamic_module_type_socket_direction_Downstream = 1,

} envoy_dynamic_module_type_socket_direction;

// =============================================================================

// Common 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_module_ptr 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_module_ptr envoy_dynamic_module_on_program_init(void);

// =============================================================================

// Common Callbacks

// =============================================================================

// --------------------------------- Logging -----------------------------------

/**

 * envoy_dynamic_module_callback_log is called by the module to log a message as part

 * of the standard Envoy logging stream under [dynamic_modules] Id.

 *

 * @param level is the log level of the message.

 * @param message is the log message to be logged.

 *

 */

void envoy_dynamic_module_callback_log(envoy_dynamic_module_type_log_level level,

                                       envoy_dynamic_module_type_module_buffer message);

/**

 * envoy_dynamic_module_callback_log_enabled is called by the module to check if the log level is

 * enabled for logging for the dynamic modules Id. This can be used to avoid unnecessary

 * string formatting and allocation if the log level is not enabled since calling this function

 * should be negligible in terms of performance.

 *

 * @param level is the log level to check.

 * @return true if the log level is enabled, false otherwise.

 */

bool envoy_dynamic_module_callback_log_enabled(envoy_dynamic_module_type_log_level level);

// --------------------------------- Threading -----------------------------------

/**

 * envoy_dynamic_module_callback_get_concurrency may be called by the dynamic

 * module in envoy_dynamic_module_on_program_init to get the configured concurrency of the server.

 * NOTE: This function must be called on the main thread.

 *

 * @return number of worker threads (concurrency) that the server is configured to use.

 */

uint32_t envoy_dynamic_module_callback_get_concurrency();

// ----------------------------- Function Registry -----------------------------

/**

 * envoy_dynamic_module_callback_register_function registers an opaque function pointer under the

 * given key in the process-wide function registry. This allows modules loaded in the same process

 * to expose functions that other modules can resolve by name and call directly, enabling zero-copy

 * cross-module interactions.

 *

 * Registration is typically done once during bootstrap (e.g., in on_server_initialized). The

 * function pointer must remain valid for the lifetime of the process.

 *

 * Callers are responsible for agreeing on the function signature out-of-band, since the registry

 * stores opaque void* pointers — analogous to dlsym semantics.

 *

 * This is thread-safe and can be called from any thread.

 *

 * @param key is the name to register the function under.

 * @param function_ptr is the function pointer to register. Must not be nullptr.

 * @return true if registered successfully, false if a function is already registered under key or

 *         function_ptr is nullptr.

 */

bool envoy_dynamic_module_callback_register_function(envoy_dynamic_module_type_module_buffer key,

                                                     void* function_ptr);

/**

 * envoy_dynamic_module_callback_get_function retrieves a previously registered function pointer by

 * key from the process-wide function registry. The returned pointer can be cast to the expected

 * function signature and called directly.

 *

 * Resolution is typically done once during configuration creation (e.g., in

 * on_http_filter_config_new) and the result cached for per-request use.

 *

 * This is thread-safe and can be called from any thread.

 *

 * @param key is the name of the function to retrieve.

 * @param function_ptr_out is a pointer to a variable where the function pointer will be stored.

 *                         This is only written to if the function returns true.

 * @return true if a function was found under the given key, false otherwise.

 */

bool envoy_dynamic_module_callback_get_function(envoy_dynamic_module_type_module_buffer key,

                                                void** function_ptr_out);

// ----------------------------- Shared Data Registry -----------------------------

/**

 * envoy_dynamic_module_callback_register_shared_data registers an opaque data pointer under the

 * given key in the process-wide shared data registry. This allows modules loaded in the same

 * process to share arbitrary state — such as runtime handles, configuration snapshots, or shared

 * caches — without requiring direct access to each other's globals.

 *

 * Unlike the function registry, the shared data registry allows overwriting an existing entry.

 * If the key already exists, the data pointer is updated and the function returns true. This

 * supports patterns where shared state is refreshed (e.g., after a configuration reload).

 * Callers are responsible for managing the lifetime of overwritten data pointers.

 *

 * Registration is typically done once during bootstrap (e.g., in on_server_initialized or

 * on_scheduled). The data pointer must remain valid for the lifetime of the process.

 *

 * This is thread-safe and can be called from any thread.

 *

 * @param key is the name to register the data under.

 * @param data_ptr is the data pointer to register. Must not be nullptr.

 * @return true if registered or updated successfully, false if data_ptr is nullptr.

 */

bool envoy_dynamic_module_callback_register_shared_data(envoy_dynamic_module_type_module_buffer key,

                                                        void* data_ptr);

/**

 * envoy_dynamic_module_callback_get_shared_data retrieves a previously registered data pointer by

 * key from the process-wide shared data registry. The returned pointer can be cast to the expected

 * data type and used directly.

 *

 * Resolution is typically done once during configuration creation (e.g., in

 * on_http_filter_config_new) and the result cached for per-request use.

 *

 * This is thread-safe and can be called from any thread.

 *

 * @param key is the name of the data to retrieve.

 * @param data_ptr_out is a pointer to a variable where the data pointer will be stored.

 *                     This is only written to if the function returns true.

 * @return true if data was found under the given key, false otherwise.

 */

bool envoy_dynamic_module_callback_get_shared_data(envoy_dynamic_module_type_module_buffer key,

                                                   void** data_ptr_out);

// =============================================================================

// ============================== HTTP Filter ==================================

// =============================================================================

// =============================================================================

// HTTP Filter Types

// =============================================================================

/**

 * envoy_dynamic_module_type_http_filter_config_envoy_ptr is a raw pointer to

 * the DynamicModuleHttpFilterConfig class in Envoy. This is passed to the module when

 * creating a new in-module HTTP filter configuration and used to access the HTTP filter-scoped

 * information such as metadata, metrics, etc.

 *

 * This has 1:1 correspondence with envoy_dynamic_module_type_http_filter_config_module_ptr in

 * the module.

 *

 * OWNERSHIP: Envoy owns the pointer.

 */

typedef void* envoy_dynamic_module_type_http_filter_config_envoy_ptr;

/**

 * envoy_dynamic_module_type_http_filter_config_module_ptr is a pointer to an in-module HTTP

 * configuration corresponding to an Envoy HTTP filter configuration. The config is responsible for

 * creating a new HTTP filter that corresponds to each HTTP stream.

 *

 * This has 1:1 correspondence with the DynamicModuleHttpFilterConfig class in Envoy.

 *

 * OWNERSHIP: The module is responsible for managing the lifetime of the pointer. The pointer can be

 * released when envoy_dynamic_module_on_http_filter_config_destroy is called for the same pointer.

 */

typedef const void* envoy_dynamic_module_type_http_filter_config_module_ptr;

/**

 * envoy_dynamic_module_type_http_filter_per_route_config_module_ptr is a pointer to an in-module

 * HTTP configuration corresponding to an Envoy HTTP per route filter configuration. The config is

 * responsible for changing HTTP filter's behavior on specific routes.

 *

 * This has 1:1 correspondence with the DynamicModuleHttpPerRouteFilterConfig class in Envoy.

 *

 * OWNERSHIP: The module is responsible for managing the lifetime of the pointer. The pointer can be

 * released when envoy_dynamic_module_on_http_filter_per_route_config_destroy is called for the same

 * pointer.

 */

typedef const void* envoy_dynamic_module_type_http_filter_per_route_config_module_ptr;

/**

 * envoy_dynamic_module_type_http_filter_envoy_ptr is a raw pointer to the DynamicModuleHttpFilter

 * class in Envoy. This is passed to the module when creating a new HTTP filter for each HTTP stream

 * and used to access the HTTP filter-scoped information such as headers, body, trailers, etc.

 *

 * This has 1:1 correspondence with envoy_dynamic_module_type_http_filter_module_ptr in the module.

 *

 * OWNERSHIP: Envoy owns the pointer, and can be accessed by the module until the filter is

 * destroyed, i.e. envoy_dynamic_module_on_http_filter_destroy is called.

 */

typedef void* envoy_dynamic_module_type_http_filter_envoy_ptr;

/**

 * envoy_dynamic_module_type_http_filter_module_ptr is a pointer to an in-module HTTP filter

 * corresponding to an Envoy HTTP filter. The filter is responsible for processing each HTTP stream.

 *

 * This has 1:1 correspondence with the DynamicModuleHttpFilter class in Envoy.

 *

 * OWNERSHIP: The module is responsible for managing the lifetime of the pointer. The pointer can be

 * released when envoy_dynamic_module_on_http_filter_destroy is called for the same pointer.

 */

typedef const void* envoy_dynamic_module_type_http_filter_module_ptr;

/**

 * envoy_dynamic_module_type_http_filter_scheduler_ptr is a raw pointer to the

 * DynamicModuleHttpFilterScheduler class in Envoy.

 *

 * OWNERSHIP: The allocation is done by Envoy but the module is responsible for managing the

 * lifetime of the pointer. Notably, it must be explicitly destroyed by the module

 * when scheduling the HTTP filter event is done. The creation of this pointer is done by

 * envoy_dynamic_module_callback_http_filter_scheduler_new and the scheduling and destruction is

 * done by envoy_dynamic_module_callback_http_filter_scheduler_delete. Since its lifecycle is

 * owned/managed by the module, this has _module_ptr suffix.

 */

typedef void* envoy_dynamic_module_type_http_filter_scheduler_module_ptr;

/**

 * envoy_dynamic_module_type_http_filter_config_scheduler_module_ptr is a raw pointer to the

 * DynamicModuleHttpFilterConfigScheduler class in Envoy.

 *

 * OWNERSHIP: The allocation is done by Envoy but the module is responsible for managing the

 * lifetime of the pointer. Notably, it must be explicitly destroyed by the module

 * when scheduling the HTTP filter config event is done. The creation of this pointer is done by

 * envoy_dynamic_module_callback_http_filter_config_scheduler_new and the scheduling and destruction

 * is done by envoy_dynamic_module_callback_http_filter_config_scheduler_delete. Since its lifecycle

 * is owned/managed by the module, this has _module_ptr suffix.

 */

typedef void* envoy_dynamic_module_type_http_filter_config_scheduler_module_ptr;

typedef enum envoy_dynamic_module_type_http_body_type {

  envoy_dynamic_module_type_http_body_type_ReceivedRequestBody,

  envoy_dynamic_module_type_http_body_type_BufferedRequestBody,

  envoy_dynamic_module_type_http_body_type_ReceivedResponseBody,

  envoy_dynamic_module_type_http_body_type_BufferedResponseBody,

} envoy_dynamic_module_type_http_body_type;

/**

 * envoy_dynamic_module_type_on_http_filter_request_headers_status represents the status of the

 * filter after processing the HTTP request headers. This corresponds to `FilterHeadersStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_request_headers_status {

  envoy_dynamic_module_type_on_http_filter_request_headers_status_Continue,

  envoy_dynamic_module_type_on_http_filter_request_headers_status_StopIteration,

  envoy_dynamic_module_type_on_http_filter_request_headers_status_ContinueAndDontEndStream,

  envoy_dynamic_module_type_on_http_filter_request_headers_status_StopAllIterationAndBuffer,

  envoy_dynamic_module_type_on_http_filter_request_headers_status_StopAllIterationAndWatermark,

} envoy_dynamic_module_type_on_http_filter_request_headers_status;

/**

 * envoy_dynamic_module_type_on_http_filter_request_body_status represents the status of the filter

 * after processing the HTTP request body. This corresponds to `FilterDataStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_request_body_status {

  envoy_dynamic_module_type_on_http_filter_request_body_status_Continue,

  envoy_dynamic_module_type_on_http_filter_request_body_status_StopIterationAndBuffer,

  envoy_dynamic_module_type_on_http_filter_request_body_status_StopIterationAndWatermark,

  envoy_dynamic_module_type_on_http_filter_request_body_status_StopIterationNoBuffer

} envoy_dynamic_module_type_on_http_filter_request_body_status;

/**

 * envoy_dynamic_module_type_on_http_filter_request_trailers_status represents the status of the

 * filter after processing the HTTP request trailers. This corresponds to `FilterTrailersStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_request_trailers_status {

  envoy_dynamic_module_type_on_http_filter_request_trailers_status_Continue,

  envoy_dynamic_module_type_on_http_filter_request_trailers_status_StopIteration

} envoy_dynamic_module_type_on_http_filter_request_trailers_status;

/**

 * envoy_dynamic_module_type_on_http_filter_response_headers_status represents the status of the

 * filter after processing the HTTP response headers. This corresponds to `FilterHeadersStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_response_headers_status {

  envoy_dynamic_module_type_on_http_filter_response_headers_status_Continue,

  envoy_dynamic_module_type_on_http_filter_response_headers_status_StopIteration,

  envoy_dynamic_module_type_on_http_filter_response_headers_status_ContinueAndDontEndStream,

  envoy_dynamic_module_type_on_http_filter_response_headers_status_StopAllIterationAndBuffer,

  envoy_dynamic_module_type_on_http_filter_response_headers_status_StopAllIterationAndWatermark,

} envoy_dynamic_module_type_on_http_filter_response_headers_status;

/**

 * envoy_dynamic_module_type_on_http_filter_response_body_status represents the status of the filter

 * after processing the HTTP response body. This corresponds to `FilterDataStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_response_body_status {

  envoy_dynamic_module_type_on_http_filter_response_body_status_Continue,

  envoy_dynamic_module_type_on_http_filter_response_body_status_StopIterationAndBuffer,

  envoy_dynamic_module_type_on_http_filter_response_body_status_StopIterationAndWatermark,

  envoy_dynamic_module_type_on_http_filter_response_body_status_StopIterationNoBuffer

} envoy_dynamic_module_type_on_http_filter_response_body_status;

/**

 * envoy_dynamic_module_type_on_http_filter_response_trailers_status represents the status of the

 * filter after processing the HTTP response trailers. This corresponds to `FilterTrailersStatus` in

 * envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_response_trailers_status {

  envoy_dynamic_module_type_on_http_filter_response_trailers_status_Continue,

  envoy_dynamic_module_type_on_http_filter_response_trailers_status_StopIteration

} envoy_dynamic_module_type_on_http_filter_response_trailers_status;

/**

 * envoy_dynamic_module_type_on_http_filter_local_reply_status represents the action to take after

 * the onLocalReply hook completes. This corresponds to `LocalErrorStatus` in envoy/http/filter.h.

 */

typedef enum envoy_dynamic_module_type_on_http_filter_local_reply_status {

  // Continue sending the local reply after onLocalReply has been sent to all filters.

  envoy_dynamic_module_type_on_http_filter_local_reply_status_Continue,

  // Continue sending onLocalReply to all filters, but reset the stream once all filters have been

  // informed rather than sending the local reply.

  envoy_dynamic_module_type_on_http_filter_local_reply_status_ContinueAndResetStream,

} envoy_dynamic_module_type_on_http_filter_local_reply_status;

/**

 * envoy_dynamic_module_type_http_stream_reset_reason represents the reason for resetting the main

 * HTTP stream. This corresponds to `Http::StreamResetReason` in envoy/http/stream_reset_handler.h.

 */

typedef enum envoy_dynamic_module_type_http_filter_stream_reset_reason {

  // If a local codec level reset was sent on the stream.

  envoy_dynamic_module_type_http_filter_stream_reset_reason_LocalReset,

  // If a local codec level refused stream reset was sent on the stream (allowing for retry).

  envoy_dynamic_module_type_http_filter_stream_reset_reason_LocalRefusedStreamReset,

} envoy_dynamic_module_type_http_filter_stream_reset_reason;

// =============================================================================

// HTTP Filter Event Hooks

// =============================================================================

/**

 * envoy_dynamic_module_on_http_filter_config_new is called by the main thread when the http

 * filter config is loaded. The function returns a

 * envoy_dynamic_module_type_http_filter_config_module_ptr for given name and config.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object for the

 * corresponding config.

 * @param name is the name of the filter.

 * @param config is the configuration for the module.

 * @return envoy_dynamic_module_type_http_filter_config_module_ptr is the pointer to the

 * in-module HTTP filter configuration. Returning nullptr indicates a failure to initialize the

 * module. When it fails, the filter configuration will be rejected.

 */

envoy_dynamic_module_type_http_filter_config_module_ptr

envoy_dynamic_module_on_http_filter_config_new(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_envoy_buffer name, envoy_dynamic_module_type_envoy_buffer config);

/**

 * envoy_dynamic_module_on_http_filter_config_destroy is called when the HTTP filter configuration

 * is destroyed in Envoy. The module should release any resources associated with the corresponding

 * in-module HTTP filter configuration.

 * @param filter_config_ptr is a pointer to the in-module HTTP filter configuration whose

 * corresponding Envoy HTTP filter configuration is being destroyed.

 */

void envoy_dynamic_module_on_http_filter_config_destroy(

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr);

/**

 * envoy_dynamic_module_on_http_filter_per_route_config_new is called by the main thread when the

 * http per-route filter config is loaded. The function returns a

 * envoy_dynamic_module_type_http_filter_per_route_config_module_ptr for given name and config.

 *

 * @param name is the name of the filter.

 * @param config is the configuration for the module.

 * @return envoy_dynamic_module_type_http_filter_per_route_config_module_ptr is the pointer to the

 * in-module HTTP filter configuration. Returning nullptr indicates a failure to initialize the

 * module. When it fails, the filter configuration will be rejected.

 */

envoy_dynamic_module_type_http_filter_per_route_config_module_ptr

envoy_dynamic_module_on_http_filter_per_route_config_new(

    envoy_dynamic_module_type_envoy_buffer name, envoy_dynamic_module_type_envoy_buffer config);

/**

 * envoy_dynamic_module_on_http_filter_config_destroy is called when the HTTP per-route filter

 * configuration is destroyed in Envoy. The module should release any resources associated with the

 * corresponding in-module HTTP filter configuration.

 * @param filter_config_ptr is a pointer to the in-module HTTP filter configuration whose

 * corresponding Envoy HTTP filter configuration is being destroyed.

 */

void envoy_dynamic_module_on_http_filter_per_route_config_destroy(

    envoy_dynamic_module_type_http_filter_per_route_config_module_ptr filter_config_ptr);

/**

 * envoy_dynamic_module_on_http_filter_new is called when the HTTP filter is created for each HTTP

 * stream.

 *

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration.

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @return envoy_dynamic_module_type_http_filter_module_ptr is the pointer to the in-module HTTP

 * filter. Returning nullptr indicates a failure to initialize the module. When it fails, the stream

 * will be closed.

 */

envoy_dynamic_module_type_http_filter_module_ptr envoy_dynamic_module_on_http_filter_new(

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr,

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr);

/**

 * envoy_dynamic_module_on_http_filter_request_headers is called when the HTTP request headers are

 * received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param end_of_stream is true if the request headers are the last data.

 * @return envoy_dynamic_module_type_on_http_filter_request_headers_status is the status of the

 * filter.

 */

envoy_dynamic_module_type_on_http_filter_request_headers_status

envoy_dynamic_module_on_http_filter_request_headers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, bool end_of_stream);

/**

 * envoy_dynamic_module_on_http_filter_request_body is called when a new data frame of the HTTP

 * request body is received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param end_of_stream is true if the request body is the last data.

 * @return envoy_dynamic_module_type_on_http_filter_request_body_status is the status of the filter.

 */

envoy_dynamic_module_type_on_http_filter_request_body_status

envoy_dynamic_module_on_http_filter_request_body(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, bool end_of_stream);

/**

 * envoy_dynamic_module_on_http_filter_request_trailers is called when the HTTP request trailers are

 * received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @return envoy_dynamic_module_type_on_http_filter_request_trailers_status is the status of the

 * filter.

 */

envoy_dynamic_module_type_on_http_filter_request_trailers_status

envoy_dynamic_module_on_http_filter_request_trailers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_response_headers is called when the HTTP response headers are

 * received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param end_of_stream is true if the response headers are the last data.

 * @return envoy_dynamic_module_type_on_http_filter_response_headers_status is the status of the

 * filter.

 */

envoy_dynamic_module_type_on_http_filter_response_headers_status

envoy_dynamic_module_on_http_filter_response_headers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, bool end_of_stream);

/**

 * envoy_dynamic_module_on_http_filter_response_body is called when a new data frame of the HTTP

 * response body is received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param end_of_stream is true if the response body is the last data.

 * @return envoy_dynamic_module_type_on_http_filter_response_body_status is the status of the

 * filter.

 */

envoy_dynamic_module_type_on_http_filter_response_body_status

envoy_dynamic_module_on_http_filter_response_body(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, bool end_of_stream);

/**

 * envoy_dynamic_module_on_http_filter_response_trailers is called when the HTTP response trailers

 * are received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @return envoy_dynamic_module_type_on_http_filter_response_trailers_status is the status of the

 * filter.

 */

envoy_dynamic_module_type_on_http_filter_response_trailers_status

envoy_dynamic_module_on_http_filter_response_trailers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_stream_complete is called when the HTTP stream is complete.

 * This is called before envoy_dynamic_module_on_http_filter_destroy and access logs are flushed.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 */

void envoy_dynamic_module_on_http_filter_stream_complete(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_destroy is called when the HTTP filter is destroyed for each

 * HTTP stream.

 *

 * @param filter_module_ptr is the pointer to the in-module HTTP filter.

 */

void envoy_dynamic_module_on_http_filter_destroy(

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_http_callout_done is called when the HTTP callout

 * response is received initiated by a HTTP filter.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param callout_id is the ID of the callout. This is used to differentiate between multiple

 * calls.

 * @param result is the result of the callout.

 * @param headers is the headers of the response.

 * @param headers_size is the size of the headers.

 * @param body_chunks is the body of the response.

 * @param body_chunks_size is the size of the body.

 *

 * headers and body_chunks are owned by Envoy, and they are guaranteed to be valid until the end of

 * this event hook. They may be null if the callout fails or the response is empty.

 */

void envoy_dynamic_module_on_http_filter_http_callout_done(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t callout_id,

    envoy_dynamic_module_type_http_callout_result result,

    envoy_dynamic_module_type_envoy_http_header* headers, size_t headers_size,

    envoy_dynamic_module_type_envoy_buffer* body_chunks, size_t body_chunks_size);

/**

 * envoy_dynamic_module_on_http_filter_http_stream_headers is called when response headers are

 * received for a streamable HTTP callout stream.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param headers is the headers of the response.

 * @param headers_size is the size of the headers.

 * @param end_stream is true if this is the last data in the stream (no body or trailers will

 * follow).

 *

 * headers are owned by Envoy and are guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_http_stream_headers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_envoy_http_header* headers, size_t headers_size, bool end_stream);

/**

 * envoy_dynamic_module_on_http_filter_http_stream_data is called when a chunk of response body is

 * received for a streamable HTTP callout stream. This may be called multiple times for a single

 * stream as body chunks arrive.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param data is the pointer to the array of buffers containing the body chunk.

 * @param data_count is the number of buffers.

 * @param end_stream is true if this is the last data in the stream (no trailers will follow).

 *

 * data is owned by Envoy and is guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_http_stream_data(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t stream_id,

    const envoy_dynamic_module_type_envoy_buffer* data, size_t data_count, bool end_stream);

/**

 * envoy_dynamic_module_on_http_filter_http_stream_trailers is called when response trailers are

 * received for a streamable HTTP callout stream. This is called after headers and any data chunks.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param trailers is the trailers of the response.

 * @param trailers_size is the size of the trailers.

 *

 * trailers are owned by Envoy and are guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_http_stream_trailers(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_envoy_http_header* trailers, size_t trailers_size);

/**

 * envoy_dynamic_module_on_http_filter_http_stream_complete is called when a streamable HTTP

 * callout stream completes successfully. This is called after all headers, data, and trailers have

 * been received.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param stream_id is the handle to the HTTP stream.

 *

 * After this callback, the stream is automatically cleaned up and stream_ptr becomes invalid.

 */

void envoy_dynamic_module_on_http_filter_http_stream_complete(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t stream_id);

/**

 * envoy_dynamic_module_on_http_filter_http_stream_reset is called when a streamable HTTP callout

 * stream is reset or fails. This may be called instead of the complete callback if the stream

 * encounters an error.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param reason is the reason for the stream reset.

 *

 * After this callback, the stream is automatically cleaned up and stream_ptr becomes invalid.

 */

void envoy_dynamic_module_on_http_filter_http_stream_reset(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_http_stream_reset_reason reason);

/**

 * envoy_dynamic_module_on_http_filter_scheduled is called when the HTTP filter is scheduled

 * to be executed on the worker thread where the HTTP filter is running with

 * envoy_dynamic_module_callback_http_filter_scheduler_commit callback.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param event_id is the ID of the event passed to

 * envoy_dynamic_module_callback_http_filter_scheduler_commit.

 */

void envoy_dynamic_module_on_http_filter_scheduled(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint64_t event_id);

/**

 * envoy_dynamic_module_on_http_filter_config_scheduled is called when the HTTP filter

 * configuration is scheduled to be executed on the main thread with

 * envoy_dynamic_module_callback_http_filter_config_scheduler_commit callback.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param event_id is the ID of the event passed to

 * envoy_dynamic_module_callback_http_filter_config_scheduler_commit.

 */

void envoy_dynamic_module_on_http_filter_config_scheduled(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t event_id);

/**

 * envoy_dynamic_module_on_http_filter_config_http_callout_done is called when the HTTP callout

 * response is received for a callout initiated by an HTTP filter configuration.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param callout_id is the ID of the callout. This is used to differentiate between multiple

 * calls.

 * @param result is the result of the callout.

 * @param headers is the headers of the response.

 * @param headers_size is the size of the headers.

 * @param body_chunks is the body of the response.

 * @param body_chunks_size is the size of the body.

 *

 * headers and body_chunks are owned by Envoy, and they are guaranteed to be valid until the end of

 * this event hook. They may be null if the callout fails or the response is empty.

 */

void envoy_dynamic_module_on_http_filter_config_http_callout_done(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t callout_id,

    envoy_dynamic_module_type_http_callout_result result,

    envoy_dynamic_module_type_envoy_http_header* headers, size_t headers_size,

    envoy_dynamic_module_type_envoy_buffer* body_chunks, size_t body_chunks_size);

/**

 * envoy_dynamic_module_on_http_filter_config_http_stream_headers is called when response headers

 * are received for a streamable HTTP callout started from an HTTP filter configuration.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param headers is the headers of the response.

 * @param headers_size is the size of the headers.

 * @param end_stream is true if this is the last data in the stream (no body or trailers will

 * follow).

 *

 * headers are owned by Envoy and are guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_config_http_stream_headers(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_envoy_http_header* headers, size_t headers_size, bool end_stream);

/**

 * envoy_dynamic_module_on_http_filter_config_http_stream_data is called when a chunk of response

 * body is received for a streamable HTTP callout started from an HTTP filter configuration. This

 * may be called multiple times for a single stream as body chunks arrive.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param data is the pointer to the array of buffers containing the body chunk.

 * @param data_count is the number of buffers.

 * @param end_stream is true if this is the last data in the stream (no trailers will follow).

 *

 * data is owned by Envoy and is guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_config_http_stream_data(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t stream_id,

    const envoy_dynamic_module_type_envoy_buffer* data, size_t data_count, bool end_stream);

/**

 * envoy_dynamic_module_on_http_filter_config_http_stream_trailers is called when response trailers

 * are received for a streamable HTTP callout started from an HTTP filter configuration.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param trailers is the trailers of the response.

 * @param trailers_size is the size of the trailers.

 *

 * trailers are owned by Envoy and are guaranteed to be valid until the end of this event hook.

 */

void envoy_dynamic_module_on_http_filter_config_http_stream_trailers(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_envoy_http_header* trailers, size_t trailers_size);

/**

 * envoy_dynamic_module_on_http_filter_config_http_stream_complete is called when a streamable HTTP

 * callout stream started from an HTTP filter configuration completes successfully. This is called

 * after all headers, data, and trailers have been received.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param stream_id is the handle to the HTTP stream.

 *

 * After this callback, the stream is automatically cleaned up and stream_id becomes invalid.

 */

void envoy_dynamic_module_on_http_filter_config_http_stream_complete(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t stream_id);

/**

 * envoy_dynamic_module_on_http_filter_config_http_stream_reset is called when a streamable HTTP

 * callout stream started from an HTTP filter configuration is reset or fails.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig object.

 * @param filter_config_ptr is the pointer to the in-module HTTP filter configuration created by

 * envoy_dynamic_module_on_http_filter_config_new.

 * @param stream_id is the handle to the HTTP stream.

 * @param reason is the reason for the stream reset.

 *

 * After this callback, the stream is automatically cleaned up and stream_id becomes invalid.

 */

void envoy_dynamic_module_on_http_filter_config_http_stream_reset(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_http_filter_config_module_ptr filter_config_ptr, uint64_t stream_id,

    envoy_dynamic_module_type_http_stream_reset_reason reason);

/**

 * envoy_dynamic_module_on_http_filter_downstream_above_write_buffer_high_watermark is called when

 * the buffer for the downstream stream goes over the high watermark for a terminal filter. This may

 * be called multiple times, in which case envoy_dynamic_module_on_above_write_buffer_low_watermark

 * will be called an equal number of times until the write buffer is completely drained below the

 * low watermark.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 */

void envoy_dynamic_module_on_http_filter_downstream_above_write_buffer_high_watermark(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_downstream_below_write_buffer_low_watermark is called when

 * any buffer for the response stream goes from over its high watermark to under its low watermark

 * for a terminal filter.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 */

void envoy_dynamic_module_on_http_filter_downstream_below_write_buffer_low_watermark(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr);

/**

 * envoy_dynamic_module_on_http_filter_local_reply is called when sendLocalReply is invoked on the

 * HTTP stream. This allows filters to be notified when a local reply is being generated, which is

 * useful for logging local errors or modifying local reply behavior.

 *

 * The return value controls what happens after all filters have been informed:

 * - Continue: Send the local reply as normal.

 * - ContinueAndResetStream: Reset the stream instead of sending the local reply.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object of the

 * corresponding HTTP filter.

 * @param filter_module_ptr is the pointer to the in-module HTTP filter created by

 * envoy_dynamic_module_on_http_filter_new.

 * @param response_code is the HTTP response code for the local reply.

 * @param details is the response code details string.

 * @param reset_imminent is true if a reset will occur rather than the local reply.

 * @return envoy_dynamic_module_type_on_http_filter_local_reply_status indicating the action to take

 * after the local reply hook completes.

 */

envoy_dynamic_module_type_on_http_filter_local_reply_status

envoy_dynamic_module_on_http_filter_local_reply(

    envoy_dynamic_module_type_http_filter_envoy_ptr filter_envoy_ptr,

    envoy_dynamic_module_type_http_filter_module_ptr filter_module_ptr, uint32_t response_code,

    envoy_dynamic_module_type_envoy_buffer details, bool reset_imminent);

// =============================================================================

// HTTP Filter Callbacks

// =============================================================================

// ----------------------------- Metrics callbacks -----------------------------

/**

 * envoy_dynamic_module_callback_http_filter_config_define_counter is called by the module

 * during initialization to create a template for generating Stats::Counters with the given name and

 * labels during the lifecycle of the module.

 *

 * @param filter_config_envoy_ptr is the pointer to the DynamicModuleHttpFilterConfig in which the

 * counter will be defined.

 * @param name is the name of the counter to be defined.

 * @param label_names is the labels of the counter to be defined.

 * NOTE: label names could be null if the label_names_length is 0.

 * @param label_names_length is the length of the label_names.

 * NOTE: label_names_length could be 0 if there are no labels.

 * @param counter_id_ptr where the opaque ID that represents a unique metric will be stored. This

 * can be passed to envoy_dynamic_module_callback_http_filter_increment_counter together with

 * filter_envoy_ptr created from filter_config_envoy_ptr.

 * @return the result of the operation.

 */

envoy_dynamic_module_type_metrics_result

envoy_dynamic_module_callback_http_filter_config_define_counter(

    envoy_dynamic_module_type_http_filter_config_envoy_ptr filter_config_envoy_ptr,

    envoy_dynamic_module_type_module_buffer name,

    envoy_dynamic_module_type_module_buffer* label_names, size_t label_names_length,

    size_t* counter_id_ptr);

/**

 * envoy_dynamic_module_callback_http_filter_increment_counter is called by the module to

 * increment a previously defined counter.

 *

 * @param filter_envoy_ptr is the pointer to the DynamicModuleHttpFilter object.

 * @param id is the ID of the counter previously defined using the config that created

 * filter_envoy_ptr

 * @param label_values is the values of the labels to be incremented.

 * NOTE: label_values could be null if the label_values_length is 0.