shared

type AttributeID uint32

type BodyBuffer interface {
	// GetChunks retrieves the body content as a list of UnsafeEnvoyBuffer chunks.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetChunks() []UnsafeEnvoyBuffer

	// GetSize retrieves the total size of the body buffer.
	GetSize() uint64

	// Drain removes the specified number of bytes from the beginning of the body buffer.
	Drain(numBytes uint64)

	// Append adds the specified bytes to the end of the body buffer.
	Append(data []byte)
}

type BodyStatus int32

type ChildSpan interface {
	Span

	// Finish finishes and releases this span. After calling this method, the span is no longer
	// valid and must not be used. Calling Finish more than once is a no-op.
	Finish()
}

type ClusterHostCounts struct {
	// Total is the total number of hosts in the priority set.
	Total uint64
	// Healthy is the number of hosts in the HEALTHY state.
	Healthy uint64
	// Degraded is the number of hosts in the DEGRADED state.
	Degraded uint64
}

type CounterValue struct {
	Value uint64
	Delta uint64
}

type DownstreamWatermarkCallbacks interface {
	OnAboveWriteBufferHighWatermark()
	OnBelowWriteBufferLowWatermark()
}

type EmptyHttpFilter struct {
}

type EmptyHttpFilterConfigFactory struct {
}

type EmptyHttpFilterFactory struct {
}

type EmptyListenerFilter struct{}

type EmptyListenerFilterConfigFactory struct{}

type EmptyListenerFilterFactory struct{}

type EmptyNetworkFilter struct {
}

type EmptyNetworkFilterConfigFactory struct {
}

type EmptyNetworkFilterFactory struct {
}

type EmptyStatSink struct{}

type EmptyStatSinkConfigFactory struct{}

type HeaderMap interface {
	// Get retrieves the header values for a given key. If the key does not exist,
	// nil will be returned.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	Get(key string) []UnsafeEnvoyBuffer

	// GetOne retrieves a single header value for a given key.
	// If there are multiple values for the key, the first one will be returned.
	// If the key does not exist, an empty UnsafeEnvoyBuffer will be returned.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetOne(key string) UnsafeEnvoyBuffer

	// GetAll retrieves all header values. You should not mutate the returned slice
	// directly.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetAll() [][2]UnsafeEnvoyBuffer

	// Set sets the header value for a given key.
	Set(key string, value string)

	// Add adds a single header value for a given key.
	Add(key string, value string)

	// Remove removes the header values for a given key.
	Remove(key string)
}

type HeadersStatus int32

type HttpCalloutCallback interface {
	OnHttpCalloutDone(calloutID uint64, result HttpCalloutResult,
		headers [][2]UnsafeEnvoyBuffer, body []UnsafeEnvoyBuffer)
}

type HttpCalloutInitResult uint32

type HttpCalloutResult uint32

type HttpFilter interface {
	// OnRequestHeaders will be called when the request headers are received.
	// Returns the status to control the plugin chain processing.
	OnRequestHeaders(headers HeaderMap, endOfStream bool) HeadersStatus

	// OnRequestBody will be called when the request body are received. This may be called multiple times.
	// Returns the status to control the plugin chain processing.
	OnRequestBody(body BodyBuffer, endOfStream bool) BodyStatus

	// OnRequestTrailers will be called when the request trailers are received.
	// Returns the status to control the plugin chain processing.
	OnRequestTrailers(trailers HeaderMap) TrailersStatus

	// OnResponseHeaders will be called when the response headers are received.
	// Returns the status to control the plugin chain processing.
	OnResponseHeaders(headers HeaderMap, endOfStream bool) HeadersStatus

	// OnResponseBody will be called when the response body is received. This may be called multiple
	// times.
	// Returns the status to control the plugin chain processing.
	OnResponseBody(body BodyBuffer, endOfStream bool) BodyStatus

	// OnResponseTrailers will be called when the response trailers are received.
	// Returns the status to control the plugin chain processing.
	OnResponseTrailers(trailers HeaderMap) TrailersStatus

	// OnStreamComplete is called when the stream processing is complete and before access logs
	// are flushed.
	// This is a good place to do any final processing or cleanup before the request is fully
	// completed.
	OnStreamComplete()

	// OnDestroy is called when the HTTP filter instance is being destroyed. This is called
	// after OnStreamComplete and access logs are flushed. This is a good place to release
	// any per-stream resources.
	OnDestroy()

	// OnLocalReply is called when a local reply is being sent. The filter can either let the
	// reply proceed (LocalReplyStatusContinue) or ask Envoy to reset the stream instead
	// (LocalReplyStatusContinueAndResetStream). This is invoked before the reply leaves
	// Envoy and before any stream reset.
	//
	// details is a short description of why the local reply is being sent (e.g.
	// "buffer overflow", "rate limit exceeded"). The buffer aliases Envoy memory; copy
	// before retaining past this call. resetImminent is true if Envoy is going to reset
	// the stream after this call.
	OnLocalReply(responseCode uint32, details UnsafeEnvoyBuffer, resetImminent bool) LocalReplyStatus
}

type HttpFilterConfigFactory interface {
	// Create creates a HttpFilterFactory based on the unparsed configuration.
	Create(handle HttpFilterConfigHandle, unparsedConfig []byte) (HttpFilterFactory, error)

	// CreatePerRoute creates a per-route configuration based on the unparsed configuration.
	CreatePerRoute(unparsedConfig []byte) (any, error)
}

type HttpFilterConfigHandle interface {
	// Log will log the given message via the host environment's logging mechanism.
	Log(level LogLevel, format string, args ...any)

	// DefineHistogram creates a histogram metric with the given name, and tag keys.
	// Returns histogram metric id. This metric can never be used after the plugin
	// config is unloaded.
	DefineHistogram(name string, tagKeys ...string) (MetricID, MetricsResult)

	// DefineGauge creates a gauge metric with the given name, description, and tag keys.
	// Returns gauge metric id. This metric can never be used after the plugin
	// config is unloaded.
	DefineGauge(name string, tagKeys ...string) (MetricID, MetricsResult)

	// DefineCounter creates a counter metric with the given name, description, and tag keys.
	// Returns counter metric id. This metric can never be used after the plugin
	// config is unloaded.
	DefineCounter(name string, tagKeys ...string) (MetricID, MetricsResult)

	// HttpCallout performs an HTTP call to an external service from the config context.
	// The call is asynchronous, and the response will be delivered via the provided callback.
	// This is similar to HttpFilterHandle.HttpCallout but runs on the main thread rather than
	// the worker thread.
	// Returns result of the HTTP callout initialization and the callout ID.
	HttpCallout(cluster string, headers [][2]string, body []byte, timeoutMs uint64,
		cb HttpCalloutCallback) (HttpCalloutInitResult, uint64)

	// StartHttpStream starts a new HTTP stream to an external service from the config context.
	// The stream is asynchronous, and the response will be delivered via the provided callback.
	// This is similar to HttpFilterHandle.StartHttpStream but runs on the main thread.
	// Returns result of the HTTP stream initialization and the stream ID.
	StartHttpStream(cluster string, headers [][2]string, body []byte, endOfStream bool,
		timeoutMs uint64, cb HttpStreamCallback) (HttpCalloutInitResult, uint64)

	// SendHttpStreamData sends data on an existing HTTP stream started via StartHttpStream.
	// Returns true if the data was sent successfully.
	SendHttpStreamData(streamID uint64, body []byte, endOfStream bool) bool

	// SendHttpStreamTrailers sends trailers on an existing HTTP stream started via StartHttpStream.
	// Returns true if the trailers were sent successfully.
	SendHttpStreamTrailers(streamID uint64, trailers [][2]string) bool

	// ResetHttpStream resets an existing HTTP stream started via StartHttpStream.
	ResetHttpStream(streamID uint64)

	// GetScheduler retrieves a scheduler for deferred task execution in the config context.
	// This should be called only during the plugin configuration phase, and the returned
	// Scheduler can be used later even outside of the callbacks and at other threads.
	GetScheduler() Scheduler

	// RecordHistogramValue records the given value to the histogram metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	// Unlike HttpFilterHandle.RecordHistogramValue, this does not require a per-stream filter and
	// can be called outside of the request lifecycle, for example from a scheduled background task.
	RecordHistogramValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// SetGaugeValue sets the given value on the gauge metric. The order and size of
	// tagsValues must match the tag keys defined when the metric was created.
	// Unlike HttpFilterHandle.SetGaugeValue, this does not require a per-stream filter and
	// can be called outside of the request lifecycle, for example from a scheduled background task.
	SetGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// IncrementGaugeValue adds the given value to the gauge metric. The order and size of
	// tagsValues must match the tag keys defined when the metric was created.
	// Unlike HttpFilterHandle.IncrementGaugeValue, this does not require a per-stream filter and
	// can be called outside of the request lifecycle, for example from a scheduled background task.
	IncrementGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// DecrementGaugeValue subtracts the given value from the gauge metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	// Unlike HttpFilterHandle.DecrementGaugeValue, this does not require a per-stream filter and
	// can be called outside of the request lifecycle, for example from a scheduled background task.
	DecrementGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// IncrementCounterValue adds the given value to the counter metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	// Unlike HttpFilterHandle.IncrementCounterValue, this does not require a per-stream filter and
	// can be called outside of the request lifecycle, for example from a scheduled background task.
	IncrementCounterValue(id MetricID, value uint64, tagsValues ...string) MetricsResult
}

type HttpFilterFactory interface {
	// Create creates a HttpFilter instance.
	Create(handle HttpFilterHandle) HttpFilter

	// OnDestroy is called when the factory is being destroyed. This is a good place to clean up any
	// resources. This usually happens when the configuration is updated and all existing streams
	// using this factory are closed.
	OnDestroy()
}

type HttpFilterHandle interface {
	// GetMetadataString retrieves the dynamic metadata string value of the stream.
	// Returns metadata value if found, otherwise an empty UnsafeEnvoyBuffer.
	GetMetadataString(source MetadataSourceType, metadataNamespace, key string) (UnsafeEnvoyBuffer, bool)

	// GetMetadataNumber retrieves the dynamic metadata number value of the stream.
	// Returns metadata value if found, otherwise nil.
	GetMetadataNumber(source MetadataSourceType, metadataNamespace, key string) (float64, bool)

	// GetMetadataBool retrieves the dynamic metadata bool value of the stream.
	// Returns metadata value and true if found, otherwise false.
	GetMetadataBool(source MetadataSourceType, metadataNamespace, key string) (bool, bool)

	// SetMetadata sets the dynamic metadata value of the stream.
	SetMetadata(metadataNamespace, key string, value any)

	// GetMetadataKeys retrieves all keys in the given metadata namespace.
	// Returns list of keys in the namespace, or nil if the namespace does not exist.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetMetadataKeys(source MetadataSourceType, metadataNamespace string) []UnsafeEnvoyBuffer

	// GetMetadataNamespaces retrieves all namespace names in the metadata.
	// Returns list of namespace names, or nil if no namespaces exist.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetMetadataNamespaces(source MetadataSourceType) []UnsafeEnvoyBuffer

	// AddMetadataListNumber appends a number value to the dynamic metadata list stored under the
	// given namespace and key. If the key does not exist, a new list is created. Returns false if
	// the key exists but is not a list, or if the metadata is not accessible.
	AddMetadataListNumber(metadataNamespace, key string, value float64) bool

	// AddMetadataListString appends a string value to the dynamic metadata list stored under the
	// given namespace and key. If the key does not exist, a new list is created. Returns false if
	// the key exists but is not a list, or if the metadata is not accessible.
	AddMetadataListString(metadataNamespace, key string, value string) bool

	// AddMetadataListBool appends a bool value to the dynamic metadata list stored under the
	// given namespace and key. If the key does not exist, a new list is created. Returns false if
	// the key exists but is not a list, or if the metadata is not accessible.
	AddMetadataListBool(metadataNamespace, key string, value bool) bool

	// GetMetadataListSize returns the number of elements in the metadata list stored under the
	// given namespace and key. Returns (0, false) if the metadata is not accessible, the namespace
	// or key does not exist, or the value is not a list.
	GetMetadataListSize(source MetadataSourceType, metadataNamespace, key string) (int, bool)

	// GetMetadataListNumber returns the number element at the given index in the metadata list
	// stored under the given namespace and key. Returns (0, false) if the metadata is not
	// accessible, the namespace or key does not exist, the value is not a list, the index is out
	// of range, or the element is not a number.
	GetMetadataListNumber(source MetadataSourceType, metadataNamespace, key string, index int) (float64, bool)

	// GetMetadataListString returns the string element at the given index in the metadata list
	// stored under the given namespace and key. Returns an empty buffer and false if the metadata is
	// not accessible, the namespace or key does not exist, the value is not a list, the index is
	// out of range, or the element is not a string.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetMetadataListString(source MetadataSourceType, metadataNamespace, key string, index int) (UnsafeEnvoyBuffer, bool)

	// GetMetadataListBool returns the bool element at the given index in the metadata list stored
	// under the given namespace and key. Returns (false, false) if the metadata is not accessible,
	// the namespace or key does not exist, the value is not a list, the index is out of range, or
	// the element is not a bool.
	GetMetadataListBool(source MetadataSourceType, metadataNamespace, key string, index int) (bool, bool)

	// GetFilterState retrieves the serialized filter state value of the stream.
	// Returns filter state value if found, otherwise an empty UnsafeEnvoyBuffer.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetFilterState(key string) (UnsafeEnvoyBuffer, bool)

	// SetFilterState sets the serialized filter state value of the stream.
	SetFilterState(key string, value []byte)

	// SetFilterStateTyped sets the typed filter state value stored under the given key. The key
	// MUST match a registered ObjectFactory; the bytes are passed to createFromBytes on that
	// factory. This is the form required for interop with built-in Envoy filters that read filter
	// state as typed objects (e.g., tcp_proxy reading PerConnectionCluster).
	// Returns true on success, or false if no factory is registered for the key, the factory
	// failed to create the object, or the key is read-only.
	SetFilterStateTyped(key string, value []byte) bool

	// GetAttributeString retrieves the string attribute value of the stream.
	// Returns attribute value if found, otherwise an empty UnsafeEnvoyBuffer.
	// NOTE: The memory of underlying data may not be managed by Go GC. So you should
	// copy the data if you need to keep it and use it later.
	GetAttributeString(attributeID AttributeID) (UnsafeEnvoyBuffer, bool)

	// GetAttributeNumber retrieves the float attribute value of the stream.
	// Returns attribute value if found, otherwise (0, false).
	GetAttributeNumber(attributeID AttributeID) (float64, bool)

	// GetAttributeBool retrieves the bool attribute value of the stream.
	// Returns attribute value and true if found, otherwise false.
	GetAttributeBool(attributeID AttributeID) (bool, bool)

	// GetFilterStateTyped retrieves the serialized bytes of a typed filter state object stored
	// under the given key. Unlike GetFilterState, this calls serializeAsString on the registered
	// typed object, so it works for any filter state object type (not just StringAccessor).
	// Returns serialized value if found, otherwise an empty UnsafeEnvoyBuffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetFilterStateTyped(key string) (UnsafeEnvoyBuffer, bool)

	// GetData retrieves internal data stored for cross-phase communication.
	// This data is not included in DynamicMetadata responses.
	// Returns data value if found, otherwise nil.
	GetData(key string) any

	// SetData sets internal data for cross-phase communication.
	// This data is not included in DynamicMetadata responses.
	SetData(key string, value any)

	// SendLocalResponse sends a local reply to the client and terminates the stream.
	SendLocalResponse(status uint32, headers [][2]string, body []byte, detail string)

	// SendResponseHeaders sends response headers to the client. This is used for
	// streaming local replies.
	SendResponseHeaders(headers [][2]string, endOfStream bool)

	// SendResponseData sends response body data to the client. This is used for
	// streaming local replies.
	SendResponseData(body []byte, endOfStream bool)

	// SendResponseTrailers sends response trailers to the client. This is used for
	// streaming local replies.
	SendResponseTrailers(trailers [][2]string)

	// AddCustomFlag adds a custom flag to the stream. This flag should be very short
	// string to indicate some custom state or information of the stream.
	AddCustomFlag(flag string)

	// ContinueRequest continues the request stream processing.
	// NOTE: This function should only be called when the plugin chains are hung up because
	// of asynchronous operations.
	ContinueRequest()

	// ContinueResponse continues the response stream processing.
	// NOTE: This function should only be called when the plugin chains are hung up because
	// of asynchronous operations.
	ContinueResponse()

	// ClearRouteCache clears the cached route for the stream.
	ClearRouteCache()

	// RefreshRouteCluster clears only the cluster selection for the current route without
	// clearing the entire route cache.
	// This is a subset of ClearRouteCache. Use this when a filter modifies headers that affect
	// cluster selection but not the route itself.
	RefreshRouteCluster()

	// GetWorkerIndex returns the worker thread index assigned to the current HTTP filter.
	// This can be used by the module to manage worker-specific resources.
	GetWorkerIndex() uint32

	// SetSocketOptionInt sets an integer-valued socket option on the upstream or downstream
	// connection associated with the stream. Returns true on success.
	SetSocketOptionInt(level, name int64, state SocketOptionState, direction SocketDirection, value int64) bool

	// SetSocketOptionBytes sets a bytes-valued socket option on the upstream or downstream
	// connection associated with the stream. Returns true on success.
	SetSocketOptionBytes(level, name int64, state SocketOptionState, direction SocketDirection, value []byte) bool

	// GetSocketOptionInt retrieves the integer value of a socket option.
	// Returns value and true if found, otherwise 0 and false.
	GetSocketOptionInt(level, name int64, state SocketOptionState, direction SocketDirection) (int64, bool)

	// GetSocketOptionBytes retrieves the bytes value of a socket option. The buffer is owned by
	// Envoy and remains valid until the filter is destroyed.
	// Returns value and true if found, otherwise an empty UnsafeEnvoyBuffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetSocketOptionBytes(level, name int64, state SocketOptionState, direction SocketDirection) (UnsafeEnvoyBuffer, bool)

	// GetBufferLimit returns the current per-stream body buffer limit in bytes. A limit of 0
	// indicates no limit is applied.
	GetBufferLimit() uint64

	// SetBufferLimit sets the per-stream body buffer limit. It is recommended (but not required)
	// that filters only INCREASE the limit, to avoid conflicting with the buffer requirements of
	// other filters in the chain.
	SetBufferLimit(limit uint64)

	// GetActiveSpan returns the active tracing span for the stream, or nil if tracing is disabled
	// or no span is available. The returned Span is owned by Envoy; do not Finish it. Use
	// Span.SpawnChild to create module-owned child spans.
	GetActiveSpan() Span

	// GetClusterName returns the name of the cluster the current request is routed to.
	// Returns cluster name and true if found, otherwise an empty UnsafeEnvoyBuffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetClusterName() (UnsafeEnvoyBuffer, bool)

	// GetClusterHostCounts returns the host counts for the routed cluster at the given priority.
	// Returns host counts and true if successful, otherwise a zero-valued struct and false.
	GetClusterHostCounts(priority uint32) (ClusterHostCounts, bool)

	// SetUpstreamOverrideHost sets a host that the upstream load balancer should select first
	// if it exists in the routed cluster. Useful for sticky sessions or host affinity. When
	// strict is false, normal load balancing is used as a fallback. Returns false if the host
	// address was invalid.
	SetUpstreamOverrideHost(host string, strict bool) bool

	// ResetStream resets the HTTP stream with the given reason and optional details. After this
	// call, no further filter callbacks will be invoked except OnDestroy.
	ResetStream(reason HttpFilterStreamResetReason, details string)

	// SendGoAwayAndClose sends a GOAWAY frame to the downstream and closes the connection. If
	// graceful is true, a graceful drain is initiated before closing.
	SendGoAwayAndClose(graceful bool)

	// RecreateStream recreates the HTTP stream, optionally with new headers (or with the original
	// headers if headers is nil). Useful for internal redirects or request retries. After a
	// successful call, the current filter chain is destroyed and the filter SHOULD return Stop
	// from the current callback. Returns false if recreation could not be initiated (e.g., the
	// request body has not been fully received yet).
	RecreateStream(headers [][2]string) bool

	// RequestHeaders retrieves the request headers.
	RequestHeaders() HeaderMap

	// BufferedRequestBody retrieves the buffered request body in the chain.
	// NOTE: Because of streaming processing, the request body is not always fully buffered.
	// This function only retrieves the currently buffered body in the chain. The latest newly
	// received body chunk is passed as the parameter to OnRequestBody. Only when endOfStream is
	// true or OnRequestTrailers is called is the full request body received.
	BufferedRequestBody() BodyBuffer

	// ReceivedRequestBody retrieves the latest received request body chunk in the OnRequestBody
	// callback.
	// NOTE: This is only valid in the OnRequestBody callback. For other callbacks or outside of
	// callbacks, use BufferedRequestBody to get the currently buffered body in the chain.
	ReceivedRequestBody() BodyBuffer

	// RequestTrailers retrieves the request trailers.
	RequestTrailers() HeaderMap

	// ResponseHeaders retrieves the response headers.
	ResponseHeaders() HeaderMap

	// BufferedResponseBody retrieves the buffered response body in the chain. See
	// BufferedRequestBody for the buffering caveats.
	BufferedResponseBody() BodyBuffer

	// ReceivedResponseBody retrieves the latest received response body chunk in the OnResponseBody
	// callback.
	// NOTE: This is only valid in the OnResponseBody callback. For other callbacks or outside of
	// callbacks, use BufferedResponseBody to get the currently buffered body in the chain.
	ReceivedResponseBody() BodyBuffer

	// ReceivedBufferedRequestBody returns true if the latest received request body is the
	// previously buffered request body. This is true when a previous filter in the chain stopped
	// and buffered the request body, then resumed, and this filter is now receiving that buffered
	// body.
	// NOTE: This is only meaningful inside the OnRequestBody callback.
	ReceivedBufferedRequestBody() bool

	// ReceivedBufferedResponseBody returns true if the latest received response body is the
	// previously buffered response body. This is true when a previous filter in the chain stopped
	// and buffered the response body, then resumed, and this filter is now receiving that buffered
	// body.
	// NOTE: This is only meaningful inside the OnResponseBody callback.
	ReceivedBufferedResponseBody() bool

	// ResponseTrailers retrieves the response trailers.
	ResponseTrailers() HeaderMap

	// GetMostSpecificConfig retrieves the most specific route configuration for the stream.
	GetMostSpecificConfig() any

	// GetScheduler retrieves the scheduler related to this stream plugin for asynchronous
	// operations.
	//
	// NOTE: This MUST only be called during OnRequest* or OnResponse* callbacks. But then the
	// returned Scheduler can be used later even outside of the callbacks and even at other
	// threads.
	GetScheduler() Scheduler

	// Log will log the given message via the host environment's logging mechanism.
	Log(level LogLevel, format string, args ...any)

	// GetLogLevel returns the current effective log level of the host environment's logging
	// mechanism. The returned level reflects runtime changes, for example those applied via the
	// admin API.
	GetLogLevel() LogLevel

	// IsLogLevelEnabled reports whether the given log level is enabled by the host environment's
	// logging mechanism. It can be used to skip expensive work that is only needed when a message
	// at the given level would actually be logged.
	IsLogLevelEnabled(level LogLevel) bool

	// HttpCallout performs an HTTP call to an external service. The call is asynchronous; the
	// response, or an error, is delivered to the provided callback.
	//
	// Returns the initialization result and the callout ID. A non-success result indicates the
	// callout failed to start.
	//
	// NOTE: This method should only be called during OnRequest* or OnResponse* callbacks or
	// from a scheduled function, so that it runs on the thread where the stream is being
	// processed.
	HttpCallout(cluster string, headers [][2]string, body []byte, timeoutMs uint64,
		cb HttpCalloutCallback) (HttpCalloutInitResult, uint64)

	// StartHttpStream starts a new HTTP stream to an external service. The stream is asynchronous;
	// responses are delivered to the provided callback.
	//
	// Returns the initialization result and the stream ID. A non-success result indicates the
	// stream failed to start.
	//
	// NOTE: This method should only be called during OnRequest* or OnResponse* callbacks or
	// from a scheduled function, so that it runs on the thread where the stream is being
	// processed.
	StartHttpStream(cluster string, headers [][2]string, body []byte, endOfStream bool, timeoutMs uint64,
		cb HttpStreamCallback) (HttpCalloutInitResult, uint64)

	// SendHttpStreamData sends data on an existing HTTP stream. Returns true if the data was
	// sent successfully.
	//
	// NOTE: This method should only be called during OnRequest* or OnResponse* callbacks or
	// from a scheduled function, so that it runs on the thread where the stream is being
	// processed.
	SendHttpStreamData(streamID uint64, body []byte, endOfStream bool) bool

	// SendHttpStreamTrailers sends trailers on an existing HTTP stream. Returns true if the
	// trailers were sent successfully.
	//
	// NOTE: This method should only be called during OnRequest* or OnResponse* callbacks or
	// from a scheduled function, so that it runs on the thread where the stream is being
	// processed.
	SendHttpStreamTrailers(streamID uint64, trailers [][2]string) bool

	// ResetHttpStream resets an existing HTTP stream.
	//
	// NOTE: This method should only be called during OnRequest* or OnResponse* callbacks or
	// from a scheduled function, so that it runs on the thread where the stream is being
	// processed.
	ResetHttpStream(streamID uint64)

	// SetDownstreamWatermarkCallbacks sets the downstream watermark callbacks for the stream.
	SetDownstreamWatermarkCallbacks(callbacks DownstreamWatermarkCallbacks)

	// ClearDownstreamWatermarkCallbacks unsets the downstream watermark callbacks for the stream.
	ClearDownstreamWatermarkCallbacks()

	// RecordHistogramValue records the given value to the histogram metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	RecordHistogramValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// SetGaugeValue sets the given value on the gauge metric. The order and size of
	// tagsValues must match the tag keys defined when the metric was created.
	SetGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// IncrementGaugeValue adds the given value to the gauge metric. The order and size of
	// tagsValues must match the tag keys defined when the metric was created.
	IncrementGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// DecrementGaugeValue subtracts the given value from the gauge metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	DecrementGaugeValue(id MetricID, value uint64, tagsValues ...string) MetricsResult

	// IncrementCounterValue adds the given value to the counter metric. The order and
	// size of tagsValues must match the tag keys defined when the metric was created.
	IncrementCounterValue(id MetricID, value uint64, tagsValues ...string) MetricsResult
}

type HttpFilterStreamResetReason uint32

type HttpHeaderType uint32

type HttpStreamCallback interface {
	OnHttpStreamHeaders(streamID uint64, headers [][2]UnsafeEnvoyBuffer, endStream bool)
	OnHttpStreamData(streamID uint64, body []UnsafeEnvoyBuffer, endStream bool)
	OnHttpStreamTrailers(streamID uint64, trailers [][2]UnsafeEnvoyBuffer)
	OnHttpStreamComplete(streamID uint64)
	OnHttpStreamReset(streamID uint64, reason HttpStreamResetReason)
}

type HttpStreamResetReason uint32

type ListenerAddressType uint32

type ListenerFilter interface {
	// OnAccept is called when Envoy accepts a new downstream socket.
	OnAccept() ListenerFilterStatus

	// OnData is called when bytes are available in the listener filter peek buffer.
	OnData(dataLength uint64) ListenerFilterStatus

	// OnClose is called when the socket closes while this filter owns iteration.
	OnClose()

	// OnDestroy is called when Envoy destroys the listener filter instance.
	OnDestroy()

	// MaxReadBytes reports how many bytes Envoy should peek for this filter.
	MaxReadBytes() uint64
}

type ListenerFilterConfigFactory interface {
	// Create parses unparsedConfig and returns the ListenerFilterFactory for new downstream sockets.
	Create(handle ListenerFilterConfigHandle, unparsedConfig []byte) (ListenerFilterFactory, error)
}

type ListenerFilterConfigHandle interface {
	// DefineHistogram defines a histogram metric during config creation.
	DefineHistogram(name string) (MetricID, MetricsResult)
	// DefineGauge defines a gauge metric during config creation.
	DefineGauge(name string) (MetricID, MetricsResult)
	// DefineCounter defines a counter metric during config creation.
	DefineCounter(name string) (MetricID, MetricsResult)

	// IncrementCounterValue increases a counter metric by value from the config context.
	//
	// Unlike ListenerFilterHandle.IncrementCounterValue, this does not require a per-connection
	// filter and can be called outside of the connection lifecycle, e.g. from a scheduled task.
	IncrementCounterValue(id MetricID, value uint64) MetricsResult
	// SetGaugeValue sets a gauge metric to value from the config context.
	SetGaugeValue(id MetricID, value uint64) MetricsResult
	// IncrementGaugeValue increases a gauge metric by value from the config context.
	IncrementGaugeValue(id MetricID, value uint64) MetricsResult
	// DecrementGaugeValue decreases a gauge metric by value from the config context.
	DecrementGaugeValue(id MetricID, value uint64) MetricsResult
	// RecordHistogramValue records value into a histogram metric from the config context.
	RecordHistogramValue(id MetricID, value uint64) MetricsResult

	// GetScheduler returns a scheduler bound to the config context.
	GetScheduler() Scheduler
	// Log writes a formatted message through Envoy's logging subsystem.
	Log(level LogLevel, format string, args ...any)
}

type ListenerFilterFactory interface {
	// Create constructs the per-connection ListenerFilter for a newly accepted socket.
	Create(handle ListenerFilterHandle) ListenerFilter

	// OnDestroy is called when Envoy destroys this factory after draining existing users.
	OnDestroy()
}

type ListenerFilterHandle interface {
	// GetBufferChunk returns the current peek buffer chunk for this listener filter.
	GetBufferChunk() (UnsafeEnvoyBuffer, bool)
	// DrainBuffer drains length bytes from the listener filter peek buffer.
	DrainBuffer(length uint64) bool

	// SetDetectedTransportProtocol overrides the detected downstream transport protocol.
	SetDetectedTransportProtocol(protocol string)
	// SetRequestedServerName overrides the downstream requested server name.
	SetRequestedServerName(name string)
	// SetRequestedApplicationProtocols overrides the downstream requested ALPN protocols.
	SetRequestedApplicationProtocols(protocols []string)
	// SetJA3Hash overrides the JA3 TLS fingerprint.
	SetJA3Hash(hash string)
	// SetJA4Hash overrides the JA4 TLS fingerprint.
	SetJA4Hash(hash string)

	// GetRequestedServerName returns the requested server name (SNI), if present.
	GetRequestedServerName() (UnsafeEnvoyBuffer, bool)
	// GetDetectedTransportProtocol returns the detected downstream transport protocol, if present.
	GetDetectedTransportProtocol() (UnsafeEnvoyBuffer, bool)
	// GetRequestedApplicationProtocols returns the requested ALPN protocol list.
	GetRequestedApplicationProtocols() []UnsafeEnvoyBuffer
	// GetJA3Hash returns the JA3 TLS fingerprint, if present.
	GetJA3Hash() (UnsafeEnvoyBuffer, bool)
	// GetJA4Hash returns the JA4 TLS fingerprint, if present.
	GetJA4Hash() (UnsafeEnvoyBuffer, bool)
	// IsSSL reports whether the downstream connection is using TLS.
	IsSSL() bool
	// GetSSLURISANs returns the peer certificate URI SAN entries.
	GetSSLURISANs() []UnsafeEnvoyBuffer
	// GetSSLDNSSANs returns the peer certificate DNS SAN entries.
	GetSSLDNSSANs() []UnsafeEnvoyBuffer
	// GetSSLSubject returns the peer certificate subject, if present.
	GetSSLSubject() (UnsafeEnvoyBuffer, bool)

	// GetRemoteAddress returns the effective remote address and port.
	GetRemoteAddress() (UnsafeEnvoyBuffer, uint32, bool)
	// GetDirectRemoteAddress returns the direct remote address and port before proxy handling.
	GetDirectRemoteAddress() (UnsafeEnvoyBuffer, uint32, bool)
	// GetLocalAddress returns the effective local address and port.
	GetLocalAddress() (UnsafeEnvoyBuffer, uint32, bool)
	// GetDirectLocalAddress returns the original local address and port before restoration.
	GetDirectLocalAddress() (UnsafeEnvoyBuffer, uint32, bool)
	// GetOriginalDst returns the original destination address and port, if present.
	GetOriginalDst() (UnsafeEnvoyBuffer, uint32, bool)
	// GetAddressType returns the current local address type.
	GetAddressType() ListenerAddressType
	// IsLocalAddressRestored reports whether Envoy restored the local address.
	IsLocalAddressRestored() bool
	// SetRemoteAddress overrides the effective downstream remote address.
	SetRemoteAddress(address string, port uint32, isIPv6 bool) bool
	// RestoreLocalAddress restores the downstream local address.
	RestoreLocalAddress(address string, port uint32, isIPv6 bool) bool

	// ContinueFilterChain resumes listener filter iteration after a stop result.
	ContinueFilterChain(success bool)
	// UseOriginalDst configures whether Envoy should honor the original destination.
	UseOriginalDst(useOriginalDst bool)
	// CloseSocket closes the downstream socket and records optional details.
	CloseSocket(details string)
	// WriteToSocket writes bytes directly to the downstream socket.
	WriteToSocket(data []byte) int64

	// GetSocketFD returns the socket file descriptor when Envoy exposes one.
	GetSocketFD() int64
	// SetSocketOptionInt sets an integer socket option on the downstream socket.
	SetSocketOptionInt(level, name, value int64) bool
	// SetSocketOptionBytes sets a bytes socket option on the downstream socket.
	SetSocketOptionBytes(level, name int64, value []byte) bool
	// GetSocketOptionInt returns an integer socket option value, if present.
	GetSocketOptionInt(level, name int64) (int64, bool)
	// GetSocketOptionBytes returns a bytes socket option value, if present.
	GetSocketOptionBytes(level, name int64, maxSize uint64) ([]byte, bool)

	// SetDynamicMetadataString sets a string dynamic metadata value.
	SetDynamicMetadataString(metadataNamespace, key, value string)
	// GetDynamicMetadataString returns a string dynamic metadata value, if present.
	GetDynamicMetadataString(metadataNamespace, key string) (UnsafeEnvoyBuffer, bool)
	// SetDynamicMetadataNumber sets a numeric dynamic metadata value.
	SetDynamicMetadataNumber(metadataNamespace, key string, value float64)
	// GetDynamicMetadataNumber returns a numeric dynamic metadata value, if present.
	GetDynamicMetadataNumber(metadataNamespace, key string) (float64, bool)

	// SetFilterState stores a raw bytes filter state value under key.
	SetFilterState(key string, value []byte) bool
	// GetFilterState returns the raw bytes filter state value stored under key, if present.
	GetFilterState(key string) (UnsafeEnvoyBuffer, bool)

	// SetDownstreamTransportFailureReason records the downstream transport failure reason.
	SetDownstreamTransportFailureReason(reason string)
	// GetConnectionStartTimeMs returns the downstream connection start time in milliseconds.
	GetConnectionStartTimeMs() uint64
	// GetCurrentMaxReadBytes returns Envoy's current max listener-filter peek size.
	GetCurrentMaxReadBytes() uint64

	// HttpCallout starts an asynchronous HTTP callout from the listener filter worker thread.
	HttpCallout(cluster string, headers [][2]string, body []byte, timeoutMs uint64,
		cb HttpCalloutCallback) (HttpCalloutInitResult, uint64)

	// RecordHistogramValue records value in a histogram metric defined from the config handle.
	RecordHistogramValue(id MetricID, value uint64) MetricsResult
	// SetGaugeValue sets a gauge metric to value.
	SetGaugeValue(id MetricID, value uint64) MetricsResult
	// IncrementGaugeValue increases a gauge metric by value.
	IncrementGaugeValue(id MetricID, value uint64) MetricsResult
	// DecrementGaugeValue decreases a gauge metric by value.
	DecrementGaugeValue(id MetricID, value uint64) MetricsResult
	// IncrementCounterValue increases a counter metric by value.
	IncrementCounterValue(id MetricID, value uint64) MetricsResult

	// GetScheduler returns a scheduler bound to this listener filter's worker thread.
	GetScheduler() Scheduler
	// GetWorkerIndex returns the Envoy worker index for this listener filter instance.
	GetWorkerIndex() uint32

	// Log writes a formatted message through Envoy's logging subsystem.
	Log(level LogLevel, format string, args ...any)
}

type ListenerFilterStatus int32

type LocalReplyStatus int32

type LogLevel uint32

type MetadataSourceType uint32

type MetricID uint64

type MetricSnapshot interface {
	// CounterCount returns the number of counters in the snapshot.
	CounterCount() uint64
	// GetCounter writes the counter name at index into name and returns the
	// (possibly reallocated) name slice, the counter values, and whether the
	// index was valid. When false, name is returned unchanged.
	GetCounter(index uint64, name []byte) ([]byte, CounterValue, bool)

	// GaugeCount returns the number of gauges in the snapshot.
	GaugeCount() uint64
	// GetGauge writes the gauge name at index into name and returns the
	// (possibly reallocated) name slice, the gauge value, and whether the index
	// was valid. When false, name is returned unchanged.
	GetGauge(index uint64, name []byte) ([]byte, uint64, bool)

	// TextReadoutCount returns the number of text readouts in the snapshot.
	TextReadoutCount() uint64
	// GetTextReadout writes the text readout name and value at index into name
	// and value, returning the (possibly reallocated) slices and whether the
	// index was valid. When false, name and value are returned unchanged. The
	// name and value slices must not share a backing array, as both are written
	// by the same call.
	GetTextReadout(index uint64, name, value []byte) ([]byte, []byte, bool)
}

type MetricsResult uint32

type NetworkBuffer interface {
	// GetChunks returns the current buffer as Envoy-owned chunks.
	//
	// For a read buffer, the chunks are valid after the first OnRead callback for the lifetime of
	// the connection. For a write buffer, they are valid after the first OnWrite callback for the
	// lifetime of the connection. Copy the data if you need to retain it after the current callback.
	GetChunks() []UnsafeEnvoyBuffer

	// GetSize returns the total size of the current buffer in bytes.
	GetSize() uint64

	// Drain removes numBytes from the front of the buffer.
	//
	// It returns false when the underlying Envoy buffer is unavailable or the operation fails.
	Drain(numBytes uint64) bool

	// Prepend adds data to the front of the buffer.
	//
	// The provided bytes are owned by the caller for the duration of the call. It returns false if
	// Envoy rejects the operation.
	Prepend(data []byte) bool

	// Append adds data to the end of the buffer.
	//
	// The provided bytes are owned by the caller for the duration of the call. It returns false if
	// Envoy rejects the operation.
	Append(data []byte) bool
}

type NetworkConnectionCloseType uint32

type NetworkConnectionEvent uint32

type NetworkConnectionState uint32

type NetworkFilter interface {
	// OnNewConnection is called once a TCP connection has been accepted and the filter instance has
	// been created for it.
	//
	// Returning NetworkFilterStatusContinue lets iteration proceed to later filters immediately.
	// Returning NetworkFilterStatusStop pauses iteration until the filter later calls
	// NetworkFilterHandle.ContinueReading.
	OnNewConnection() NetworkFilterStatus

	// OnRead is called when data has been read from the downstream side and is about to continue
	// through the read filter chain toward the upstream.
	//
	// data exposes the current read buffer owned by Envoy. endOfStream is true when the downstream
	// side has half-closed and this callback is processing the final read data. Returning
	// NetworkFilterStatusStop pauses iteration until ContinueReading is called.
	OnRead(data NetworkBuffer, endOfStream bool) NetworkFilterStatus

	// OnWrite is called when data is about to be written in the upstream -> downstream direction.
	//
	// data exposes the current write buffer owned by Envoy. endOfStream is true when this callback
	// is processing the final write-side data. Returning NetworkFilterStatusStop pauses iteration
	// until ContinueReading is called.
	OnWrite(data NetworkBuffer, endOfStream bool) NetworkFilterStatus

	// OnEvent is called for connection lifecycle events such as connect, remote close, and local
	// close.
	OnEvent(event NetworkConnectionEvent)

	// OnDestroy is called when the filter instance is being destroyed and should release any
	// resources tied to the connection.
	OnDestroy()

	// OnAboveWriteBufferHighWatermark is called when the connection write buffer crosses above its
	// configured high watermark.
	OnAboveWriteBufferHighWatermark()

	// OnBelowWriteBufferLowWatermark is called when the connection write buffer drops from above
	// the high watermark to below the low watermark again.
	OnBelowWriteBufferLowWatermark()
}

type NetworkFilterConfigFactory interface {
	// Create parses the supplied configuration bytes and returns a thread-safe
	// NetworkFilterFactory for subsequent connections.
	//
	// Returning an error rejects the filter configuration.
	Create(handle NetworkFilterConfigHandle, unparsedConfig []byte) (NetworkFilterFactory, error)
}

type NetworkFilterConfigHandle interface {
	// Log writes a formatted message through Envoy's logging subsystem.
	Log(level LogLevel, format string, args ...any)

	// DefineHistogram creates a histogram metric during configuration initialization and returns its
	// opaque ID.
	DefineHistogram(name string) (MetricID, MetricsResult)

	// DefineGauge creates a gauge metric during configuration initialization and returns its opaque
	// ID.
	DefineGauge(name string) (MetricID, MetricsResult)

	// DefineCounter creates a counter metric during configuration initialization and returns its
	// opaque ID.
	DefineCounter(name string) (MetricID, MetricsResult)

	// IncrementCounterValue increases a counter metric by value from the config context.
	//
	// Unlike NetworkFilterHandle.IncrementCounterValue, this does not require a per-connection
	// filter and can be called outside of the connection lifecycle, e.g. from a scheduled task.
	IncrementCounterValue(id MetricID, value uint64) MetricsResult

	// SetGaugeValue sets a gauge metric to value from the config context.
	SetGaugeValue(id MetricID, value uint64) MetricsResult

	// IncrementGaugeValue increases a gauge metric by value from the config context.
	IncrementGaugeValue(id MetricID, value uint64) MetricsResult

	// DecrementGaugeValue decreases a gauge metric by value from the config context.
	DecrementGaugeValue(id MetricID, value uint64) MetricsResult

	// RecordHistogramValue records value into a histogram metric from the config context.
	RecordHistogramValue(id MetricID, value uint64) MetricsResult

	// GetScheduler retrieves a scheduler for deferred task execution in the config context.
	// This should be called only during the plugin configuration phase, and the returned
	// Scheduler can be used later even outside of the callbacks and at other threads.
	GetScheduler() Scheduler
}

type NetworkFilterFactory interface {
	// Create constructs the per-connection NetworkFilter instance for a newly accepted TCP
	// connection.
	//
	// Returning nil causes filter creation to fail and the connection to be closed.
	Create(handle NetworkFilterHandle) NetworkFilter

	// OnDestroy is called when Envoy is destroying this factory, usually after configuration has
	// been replaced and all connections using it have drained.
	OnDestroy()
}

type NetworkFilterHandle interface {
	// ReadBuffer returns the current downstream -> upstream buffer for this connection.
	ReadBuffer() NetworkBuffer

	// WriteBuffer returns the current upstream -> downstream buffer for this connection.
	WriteBuffer() NetworkBuffer

	// Write writes data directly to the downstream connection.
	//
	// When endStream is true, Envoy half-closes the connection after writing.
	Write(data []byte, endStream bool)

	// InjectReadData injects data into the read filter chain after this filter.
	//
	// The injected bytes continue through later read filters as if they had just been received.
	InjectReadData(data []byte, endStream bool)

	// InjectWriteData injects data into the write filter chain after this filter.
	//
	// The injected bytes continue through later write filters as if they had just been produced.
	InjectWriteData(data []byte, endStream bool)

	// ContinueReading resumes filter iteration after OnNewConnection, OnRead, or OnWrite previously
	// returned NetworkFilterStatusStop.
	ContinueReading()

	// Close closes the connection using the supplied close behavior.
	Close(closeType NetworkConnectionCloseType)

	// GetConnectionID returns the unique Envoy connection ID.
	GetConnectionID() uint64

	// GetRemoteAddress returns the remote peer address and port as seen by Envoy.
	GetRemoteAddress() (UnsafeEnvoyBuffer, uint32, bool)

	// GetLocalAddress returns the local address and port for the connection.
	GetLocalAddress() (UnsafeEnvoyBuffer, uint32, bool)

	// IsSSL reports whether the connection is using SSL/TLS.
	IsSSL() bool

	// DisableClose disables or re-enables close handling for this filter instance.
	DisableClose(disabled bool)

	// CloseWithDetails closes the connection and records termination details that Envoy can surface
	// in logs and diagnostics.
	CloseWithDetails(closeType NetworkConnectionCloseType, details string)

	// GetRequestedServerName returns the requested server name (SNI) from the TLS handshake.
	GetRequestedServerName() (UnsafeEnvoyBuffer, bool)

	// GetDirectRemoteAddress returns the direct remote address and port without proxy/XFF handling.
	GetDirectRemoteAddress() (UnsafeEnvoyBuffer, uint32, bool)

	// GetSSLURISANs returns the peer certificate URI SAN entries.
	GetSSLURISANs() []UnsafeEnvoyBuffer

	// GetSSLDNSSANs returns the peer certificate DNS SAN entries.
	GetSSLDNSSANs() []UnsafeEnvoyBuffer

	// GetSSLSubject returns the peer certificate subject.
	GetSSLSubject() (UnsafeEnvoyBuffer, bool)

	// SetFilterState stores a raw bytes filter state value under key.
	//
	// Other filters can read the value, and built-in filters may use it for routing decisions.
	SetFilterState(key string, value []byte) bool

	// GetFilterState returns a raw bytes filter state value previously stored under key.
	GetFilterState(key string) (UnsafeEnvoyBuffer, bool)

	// SetFilterStateTyped stores a typed filter state value using Envoy's registered ObjectFactory
	// for key.
	SetFilterStateTyped(key string, value []byte) bool

	// GetFilterStateTyped returns the serialized bytes of the typed filter state object stored under
	// key.
	GetFilterStateTyped(key string) (UnsafeEnvoyBuffer, bool)

	// GetMetadataString returns a dynamic metadata string value for metadataNamespace/key.
	GetMetadataString(metadataNamespace, key string) (UnsafeEnvoyBuffer, bool)

	// GetMetadataNumber returns a dynamic metadata number value for metadataNamespace/key.
	GetMetadataNumber(metadataNamespace, key string) (float64, bool)

	// GetMetadataBool returns a dynamic metadata bool value for metadataNamespace/key.
	GetMetadataBool(metadataNamespace, key string) (bool, bool)

	// SetMetadata stores a string, number, or bool dynamic metadata value at
	// metadataNamespace/key, replacing any existing value.
	SetMetadata(metadataNamespace, key string, value any)

	// SetSocketOptionInt stores an integer socket option to be applied at the specified socket
	// state.
	SetSocketOptionInt(level, name int64, state SocketOptionState, value int64)

	// SetSocketOptionBytes stores a bytes socket option to be applied at the specified socket state.
	SetSocketOptionBytes(level, name int64, state SocketOptionState, value []byte)

	// GetSocketOptionInt returns an integer socket option value if one is present for the supplied
	// level/name/state tuple.
	GetSocketOptionInt(level, name int64, state SocketOptionState) (int64, bool)

	// GetSocketOptionBytes returns a bytes socket option value if one is present for the supplied
	// level/name/state tuple.
	GetSocketOptionBytes(level, name int64, state SocketOptionState) (UnsafeEnvoyBuffer, bool)

	// GetSocketOptions returns all socket options currently stored on the connection.
	GetSocketOptions() []SocketOption

	// Log writes a formatted message through Envoy's logging subsystem.
	Log(level LogLevel, format string, args ...any)

	// HttpCallout performs an HTTP call to an external service. The call is asynchronous, and the
	// response will be delivered via the provided callback.
	//
	// NOTE: This method should only be called during network filter callbacks or scheduled functions
	// via the Scheduler so that it runs on the filter's worker thread.
	HttpCallout(cluster string, headers [][2]string, body []byte, timeoutMs uint64,
		cb HttpCalloutCallback) (HttpCalloutInitResult, uint64)

	// RecordHistogramValue records value in a histogram metric previously defined from the config
	// handle.
	RecordHistogramValue(id MetricID, value uint64) MetricsResult

	// SetGaugeValue sets a gauge metric to value.
	SetGaugeValue(id MetricID, value uint64) MetricsResult

	// IncrementGaugeValue increases a gauge metric by value.
	IncrementGaugeValue(id MetricID, value uint64) MetricsResult

	// DecrementGaugeValue decreases a gauge metric by value.
	DecrementGaugeValue(id MetricID, value uint64) MetricsResult

	// IncrementCounterValue increases a counter metric by value.
	IncrementCounterValue(id MetricID, value uint64) MetricsResult

	// GetClusterHostCounts returns the total, healthy, and degraded host counts for the named
	// cluster and priority.
	GetClusterHostCounts(cluster string, priority uint32) (ClusterHostCounts, bool)

	// GetUpstreamHostAddress returns the currently selected upstream host address and port.
	GetUpstreamHostAddress() (UnsafeEnvoyBuffer, uint32, bool)

	// GetUpstreamHostHostname returns the currently selected upstream host hostname.
	GetUpstreamHostHostname() (UnsafeEnvoyBuffer, bool)

	// GetUpstreamHostCluster returns the cluster name of the currently selected upstream host.
	GetUpstreamHostCluster() (UnsafeEnvoyBuffer, bool)

	// HasUpstreamHost reports whether Envoy has already selected an upstream host for this
	// connection.
	HasUpstreamHost() bool

	// StartUpstreamSecureTransport upgrades the upstream connection into secure mode when the
	// transport socket supports StartTLS-style promotion.
	StartUpstreamSecureTransport() bool

	// GetConnectionState returns the current connection state.
	GetConnectionState() NetworkConnectionState

	// ReadDisable disables or re-enables reading on the connection.
	//
	// Envoy reference-counts these calls; callers must balance disables with enables.
	ReadDisable(disable bool) NetworkReadDisableStatus

	// ReadEnabled reports whether reading is currently enabled.
	ReadEnabled() bool

	// IsHalfCloseEnabled reports whether remote half-close leaves the connection writable.
	IsHalfCloseEnabled() bool

	// EnableHalfClose enables or disables half-close semantics on the connection.
	EnableHalfClose(enabled bool)

	// GetBufferLimit returns the current soft buffer limit in bytes.
	GetBufferLimit() uint32

	// SetBufferLimits updates the soft buffer limit in bytes.
	//
	// On the write side, this controls high/low watermark transitions surfaced through the
	// watermark callbacks.
	SetBufferLimits(limit uint32)

	// AboveHighWatermark reports whether the write buffer is currently above the high watermark.
	AboveHighWatermark() bool

	// GetScheduler retrieves the scheduler related to this network filter for asynchronous
	// operations.
	//
	// NOTE: This MUST only be called during network filter callbacks. But then the returned
	// Scheduler can be used later even outside of the callbacks and at other threads.
	GetScheduler() Scheduler

	// GetWorkerIndex returns the worker index assigned to the current filter instance.
	GetWorkerIndex() uint32
}

type NetworkFilterStatus int32

type NetworkReadDisableStatus uint32

type Scheduler interface {
	// Schedule schedules a function to be executed asynchronously in the thread where the stream
	// plugin is being processed.
	//
	// NOTE: The function may be ignored if the related plugin processing is completed.
	Schedule(func())
}

type SocketDirection uint32

type SocketOption struct {
	Level      int64
	Name       int64
	State      SocketOptionState
	ValueType  SocketOptionValueType
	IntValue   int64
	BytesValue UnsafeEnvoyBuffer
}

type SocketOptionState uint32

type SocketOptionValueType uint32

type Span interface {
	// SetTag sets a key/value tag on the span.
	SetTag(key, value string)

	// SetOperation sets the operation name on the span.
	SetOperation(operation string)

	// Log records an event on the span with the current timestamp.
	Log(event string)

	// SetSampled overrides the sampling decision for the span. If sampled is false, this span and
	// any subsequent child spans will not be reported to the tracing system.
	SetSampled(sampled bool)

	// GetBaggage retrieves a baggage value from the span. Returns the value and true if the key
	// was found, otherwise an empty buffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetBaggage(key string) (UnsafeEnvoyBuffer, bool)

	// SetBaggage sets a baggage value on the span. All subsequent child spans will have access to
	// this baggage.
	SetBaggage(key, value string)

	// GetTraceID retrieves the trace ID from the span. Returns the value and true if available,
	// otherwise an empty buffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetTraceID() (UnsafeEnvoyBuffer, bool)

	// GetSpanID retrieves the span ID from the span. Returns the value and true if available,
	// otherwise an empty buffer and false.
	// NOTE: The memory of the underlying data may not be managed by Go GC. Copy the data if you
	// need to keep it past the current callback.
	GetSpanID() (UnsafeEnvoyBuffer, bool)

	// SpawnChild creates a child span with the given operation name. The returned ChildSpan must
	// be finished by calling its Finish method when the module is done with it. Returns nil if
	// the child span could not be created.
	SpawnChild(operationName string) ChildSpan
}

type StatSink interface {
	// OnFlush is called periodically with a full snapshot of the metrics that
	// passed the configured sink predicates.
	OnFlush(snapshot MetricSnapshot)

	// OnHistogramComplete is called synchronously for every histogram
	// observation. The name buffer is only valid for the duration of this call.
	OnHistogramComplete(name UnsafeEnvoyBuffer, value uint64)

	// OnDestroy is called when the stats sink config is being torn down. Close
	// sockets and flush any buffered state here.
	OnDestroy()
}

type StatSinkConfigFactory interface {
	// Create parses the sink configuration and returns a StatSink instance, or
	// an error if the configuration is invalid. Returning a nil StatSink with
	// no error is also treated as a failure.
	//
	// handle provides runtime services such as logging. config contains the
	// bytes passed via the sink_config field of the DynamicModuleStatsSink
	// proto. The encoding depends on the Any type used in the config, for
	// example raw bytes for BytesValue and JSON for Struct.
	Create(handle StatSinkHandle, config []byte) (StatSink, error)
}

type StatSinkHandle interface {
	// Log writes a message to Envoy's logger at the given level.
	Log(level LogLevel, format string, args ...any)

	// DefineGauge creates a gauge with the given name and returns its ID. It must
	// be called while the sink is being created, from StatSinkConfigFactory.Create.
	// Defining a gauge afterwards returns MetricsFrozen.
	DefineGauge(name string) (MetricID, MetricsResult)

	// SetGauge sets a gauge previously defined with DefineGauge to value. It must
	// be called on the main thread, typically from a function scheduled with the
	// scheduler returned by GetScheduler.
	SetGauge(id MetricID, value uint64) MetricsResult

	// GetScheduler returns a scheduler whose scheduled functions run on the main
	// thread. A sink that aggregates metrics off the main thread, for example on a
	// goroutine started from OnFlush, uses it to publish results with SetGauge. It
	// must be called while the sink is being created, from
	// StatSinkConfigFactory.Create.
	GetScheduler() Scheduler
}

type TrailersStatus int32

type UnsafeEnvoyBuffer struct {
	// Pointer to the start of the buffer data.
	Ptr *byte
	// Length of the buffer data in bytes.
	Len uint64
}