Documentation
¶
Overview ¶
Package wasm provides types and utilities for building WebAssembly plugin configurations for Envoy-based data plane integration.
This package translates Kuadrant policies (AuthPolicy, RateLimitPolicy, etc.) into WASM plugin configurations deployed to Envoy proxies via Istio or Envoy Gateway.
Core Types ¶
- Config: Top-level WASM configuration with services, action sets, and observability
- Service: External services the plugin calls (Authorino, Limitador, tracing)
- ActionSet: Actions triggered when route conditions match
- Action: Individual enforcement steps (auth checks, rate limiting)
Gateway API Integration ¶
Route matches from HTTPRoute and GRPCRoute are converted to CEL predicates for runtime evaluation. gRPC routes are represented as HTTP/2 paths since gRPC methods map to paths like "/{service}/{method}".
Semantic Equality ¶
EqualTo methods implement semantic equality - configs are equal if functionally equivalent, ignoring collection order where it doesn't affect behavior. This prevents unnecessary data plane updates.
Serialization ¶
Configs serialize to JSON (ToJSON) for Kubernetes resources and Protobuf Struct (ToStruct) for Istio/Envoy Gateway integration.
Index ¶
- Constants
- func ActionSetNameForPath(pathID string, httpRouteMatchIndex int, hostname string) string
- func AuthServiceTimeout() string
- func BuildActionSetsForPath(ctx context.Context, pathID string, path []machinery.Targetable, ...) ([]kuadrantgatewayapi.HTTPRouteMatchConfig, error)
- func ConvertGRPCRouteMatchToHTTP(grpcRouteMatch gatewayapiv1.GRPCRouteMatch) gatewayapiv1.HTTPRouteMatch
- func ExtensionName(gatewayName string) string
- func PredicatesFromGRPCRouteMatch(match gatewayapiv1.GRPCRouteMatch) []string
- func PredicatesFromHTTPRouteMatch(match gatewayapiv1.HTTPRouteMatch) []string
- func RatelimitCheckServiceTimeout() string
- func RatelimitReportServiceTimeout() string
- func RatelimitServiceTimeout() string
- func TracingServiceTimeout() string
- type Action
- type ActionSet
- type ConditionalData
- type Config
- type DataType
- type Expression
- type ExpressionItem
- type FailureModeType
- func AuthServiceFailureMode(logger *logr.Logger) FailureModeType
- func RatelimitCheckServiceFailureMode(logger *logr.Logger) FailureModeType
- func RatelimitReportServiceFailureMode(logger *logr.Logger) FailureModeType
- func RatelimitServiceFailureMode(logger *logr.Logger) FailureModeType
- func TracingServiceFailureMode(logger *logr.Logger) FailureModeType
- type LogLevel
- type Observability
- type RouteRuleConditions
- type Service
- type ServiceBuilder
- type ServiceType
- type Static
- type StaticSpec
- type Tracing
- type TypedAction
Constants ¶
const ( RateLimitServiceName = "ratelimit-service" RateLimitCheckServiceName = "ratelimit-check-service" RateLimitReportServiceName = "ratelimit-report-service" AuthServiceName = "auth-service" TracingServiceName = "tracing-service" )
Variables ¶
This section is empty.
Functions ¶
func ActionSetNameForPath ¶
func AuthServiceTimeout ¶
func AuthServiceTimeout() string
func BuildActionSetsForPath ¶
func BuildActionSetsForPath(ctx context.Context, pathID string, path []machinery.Targetable, actions []Action) ([]kuadrantgatewayapi.HTTPRouteMatchConfig, error)
BuildActionSetsForPath builds action sets for both HTTP and gRPC routes.
Note: Returns HTTPRouteMatchConfig for both HTTP and gRPC routes. For gRPC routes, GRPCRouteMatch is converted to HTTPRouteMatch format because gRPC runs on HTTP/2 and gRPC methods map to HTTP/2 paths (/{service}/{method}). This conversion enables sorting with HTTP routes and reflects the wire-level protocol. The actual predicates sent to the WASM plugin are generated from the original GRPCRouteMatch.
func ConvertGRPCRouteMatchToHTTP ¶ added in v1.5.0
func ConvertGRPCRouteMatchToHTTP(grpcRouteMatch gatewayapiv1.GRPCRouteMatch) gatewayapiv1.HTTPRouteMatch
ConvertGRPCRouteMatchToHTTP converts a GRPCRouteMatch to an HTTPRouteMatch for sorting purposes.
This conversion is necessary because gRPC is built on HTTP/2 and gRPC methods map directly to HTTP/2 paths (/{service}/{method}). By converting to HTTPRouteMatch, we can: 1. Reuse the existing HTTPRouteMatch sorting logic 2. Correctly represent gRPC method specificity using HTTP path match types 3. Sort HTTP and gRPC routes together by hostname and specificity
The conversion encodes gRPC method specificity into HTTP path matches: - Service+Method → Exact match (most specific) - Service only → PathPrefix (medium specific) - Method only → PathPrefix (less specific, shorter path)
func ExtensionName ¶
func PredicatesFromGRPCRouteMatch ¶ added in v1.5.0
func PredicatesFromGRPCRouteMatch(match gatewayapiv1.GRPCRouteMatch) []string
PredicatesFromGRPCRouteMatch generates CEL predicates from a GRPCRouteMatch. GRPCRouteMatch fields map to CEL as follows:
- method.service and method.method combine to form request.url_path patterns
- headers use the same predicate generation as HTTPRoute (predicateFromHeader)
func PredicatesFromHTTPRouteMatch ¶
func PredicatesFromHTTPRouteMatch(match gatewayapiv1.HTTPRouteMatch) []string
PredicatesFromHTTPRouteMatch builds a list of conditions from a rule match
func RatelimitCheckServiceTimeout ¶ added in v1.3.0
func RatelimitCheckServiceTimeout() string
func RatelimitReportServiceTimeout ¶ added in v1.3.0
func RatelimitReportServiceTimeout() string
func RatelimitServiceTimeout ¶
func RatelimitServiceTimeout() string
func TracingServiceTimeout ¶ added in v1.4.0
func TracingServiceTimeout() string
Types ¶
type Action ¶
type Action struct {
ServiceName string `json:"service"`
Scope string `json:"scope"`
Predicates []string `json:"predicates,omitempty"`
// ConditionalData data contains the predicates and data that will be sent to the service
// +optional
ConditionalData []ConditionalData `json:"conditionalData,omitempty"`
// SourcePolicyLocators tracks all policies that contributed to this action.
// This is important for policies that can be merged (e.g., Gateway-level + HTTPRoute-level).
// For atomic merge strategies or individual rules, this may contain a single entry.
// Serialized to wasm config as "sources" for observability and debugging.
// Format: "kind/namespace/name"
SourcePolicyLocators []string `json:"sources,omitempty"`
}
func (*Action) EqualTo ¶
EqualTo performs semantic equality comparison between two Action instances. Note: This has mixed ordering semantics for different fields.
Order-insensitive fields:
- ConditionalData: Checks that the same conditional data exists, regardless of order
Order-sensitive fields (strict equality):
- Scope: String comparison
- ServiceName: String comparison
- Predicates: Strict slice equality - order matters
- SourcePolicyLocators: Strict slice equality - order matters
func (*Action) HasAuthAccess ¶
type ActionSet ¶
type ActionSet struct {
Name string `json:"name"`
// Conditions that activate the action set
RouteRuleConditions RouteRuleConditions `json:"routeRuleConditions,omitempty"`
// Actions that will be invoked when the conditions are met (legacy format)
// +optional
Actions []Action `json:"-"`
// TypedActions are extension pipeline actions in the new TypedAction format.
// +optional
TypedActions []TypedAction `json:"-"`
// SourceRoute records which route (Kind/Namespace/Name) this action set was
// created from. Not serialized — used only to match pipeline actions to the
// correct action sets at reconcile time.
SourceRoute string `json:"-"`
}
func BuildSkeletonActionSetsForRoute ¶ added in v1.5.0
func BuildSkeletonActionSetsForRoute(listener *machinery.Listener, route machinery.Targetable) []ActionSet
BuildSkeletonActionSetsForRoute creates ActionSets with proper RouteRuleConditions (hostnames and predicates) but no actions, for all hostname/match combinations of a route. Supports both HTTPRoute and GRPCRoute. Returns nil for unsupported route types.
func (*ActionSet) EqualTo ¶
EqualTo performs semantic equality comparison between two ActionSet instances.
Order-sensitive fields:
- Name: String comparison
- RouteRuleConditions: Uses RouteRuleConditions.EqualTo (which has its own ordering rules)
- Actions: Order matters - compared by index position
Note: Actions order is significant because it affects the evaluation order in the data plane.
func (ActionSet) MarshalJSON ¶ added in v1.5.0
func (*ActionSet) UnmarshalJSON ¶ added in v1.5.0
type ConditionalData ¶ added in v1.3.0
type ConditionalData struct {
// Predicates holds a list of CEL predicates
// +optional
Predicates []string `json:"predicates,omitempty"`
// Data to be sent to the service
// +optional
Data []DataType `json:"data,omitempty"`
}
func (*ConditionalData) EqualTo ¶ added in v1.3.0
func (c *ConditionalData) EqualTo(other ConditionalData) bool
EqualTo performs semantic equality comparison between two ConditionalData instances. Note: This has mixed ordering semantics for different fields.
Order-sensitive fields:
- Predicates: Order matters - strict slice equality
- Data: Order matters - compared by index position
Note: Both predicates and data order are significant as they may affect evaluation order in the data plane.
type Config ¶
type Config struct {
RequestData map[string]string `json:"requestData,omitempty"`
Services map[string]Service `json:"services"`
ActionSets []ActionSet `json:"actionSets"`
Observability *Observability `json:"observability,omitempty"`
DescriptorService string `json:"descriptorService,omitempty"`
}
func BuildConfigForActionSet ¶
func BuildConfigForActionSet(actionSets []ActionSet, logger *logr.Logger, observability *Observability, serviceBuilder *ServiceBuilder) Config
func ConfigFromJSON ¶
func ConfigFromJSON(configJSON *apiextensionsv1.JSON) (*Config, error)
func (*Config) EqualTo ¶
EqualTo performs semantic equality comparison between two Config instances. This is not a strict equality check - it considers two configs equal if they are functionally equivalent, even if some collection orderings differ.
Order-sensitive fields:
- ActionSets: Order matters - compared by index position
- RequestData: Map comparison (order doesn't apply)
- Services: Map comparison (order doesn't apply)
- DescriptorService: String comparison
- Observability: Strict equality via nested EqualTo
Note: ActionSets order is significant because it affects the evaluation order in the data plane.
type DataType ¶
type DataType struct {
Value any
}
func (*DataType) MarshalJSON ¶
func (*DataType) UnmarshalJSON ¶
type Expression ¶
type Expression struct {
// Data to be sent to the service
ExpressionItem ExpressionItem `json:"expression"`
}
type ExpressionItem ¶
type FailureModeType ¶
type FailureModeType string
+kubebuilder:validation:Enum:=deny;allow
const ( FailureModeDeny FailureModeType = "deny" FailureModeAllow FailureModeType = "allow" )
func AuthServiceFailureMode ¶
func AuthServiceFailureMode(logger *logr.Logger) FailureModeType
func RatelimitCheckServiceFailureMode ¶ added in v1.3.0
func RatelimitCheckServiceFailureMode(logger *logr.Logger) FailureModeType
func RatelimitReportServiceFailureMode ¶ added in v1.3.0
func RatelimitReportServiceFailureMode(logger *logr.Logger) FailureModeType
func RatelimitServiceFailureMode ¶
func RatelimitServiceFailureMode(logger *logr.Logger) FailureModeType
func TracingServiceFailureMode ¶ added in v1.4.0
func TracingServiceFailureMode(logger *logr.Logger) FailureModeType
type Observability ¶ added in v1.4.0
type Observability struct {
HTTPHeaderIdentifier *string `json:"httpHeaderIdentifier,omitempty"`
DefaultLevel *string `json:"defaultLevel,omitempty"`
Tracing *Tracing `json:"tracing,omitempty"`
}
func BuildObservabilityConfig ¶ added in v1.4.0
func BuildObservabilityConfig(serviceBuilder *ServiceBuilder, observabilitySpec *v1beta1.Observability) *Observability
BuildObservabilityConfig builds the wasm-shim observability config from the Observability spec For MVP: finds the highest priority level that is set to "true" Priority: DEBUG(4) > INFO(3) > WARN(2) > ERROR(1) Future: will support dynamic CEL predicates for request-time evaluation
func (*Observability) EqualTo ¶ added in v1.4.0
func (o *Observability) EqualTo(other *Observability) bool
type RouteRuleConditions ¶
type RouteRuleConditions struct {
Hostnames []string `json:"hostnames"`
// +optional
Predicates []string `json:"predicates,omitempty"`
}
func (*RouteRuleConditions) EqualTo ¶
func (r *RouteRuleConditions) EqualTo(other RouteRuleConditions) bool
EqualTo performs semantic equality comparison between two RouteRuleConditions instances.
Order-sensitive fields:
- Hostnames: Order matters - compared by index position
- Predicates: Order matters - compared by index position
Note: Hostname order is preserved as it may reflect priority or specificity, while predicates are order-insensitive as they are evaluated independently.
type Service ¶
type Service struct {
Endpoint string `json:"endpoint"`
Type ServiceType `json:"type"`
FailureMode FailureModeType `json:"failureMode"`
Timeout *string `json:"timeout,omitempty"`
GrpcService *string `json:"grpcService,omitempty"`
GrpcMethod *string `json:"grpcMethod,omitempty"`
}
type ServiceBuilder ¶ added in v1.4.0
type ServiceBuilder struct {
// contains filtered or unexported fields
}
ServiceBuilder helps build wasm services with optional configurations using the builder pattern
func NewServiceBuilder ¶ added in v1.4.0
func NewServiceBuilder(logger *logr.Logger) *ServiceBuilder
NewServiceBuilder creates a new ServiceBuilder with default services
func (*ServiceBuilder) Build ¶ added in v1.4.0
func (sb *ServiceBuilder) Build() map[string]Service
Build returns the built services map
func (*ServiceBuilder) WithService ¶ added in v1.4.0
func (sb *ServiceBuilder) WithService(name string, service Service) *ServiceBuilder
WithService adds a custom service
func (*ServiceBuilder) WithTracing ¶ added in v1.4.0
func (sb *ServiceBuilder) WithTracing() *ServiceBuilder
WithTracing adds a tracing service with the specified endpoint
type ServiceType ¶
type ServiceType string
+kubebuilder:validation:Enum:=ratelimit;auth;ratelimit-check;ratelimit-report;tracing;dynamic
const ( RateLimitServiceType ServiceType = "ratelimit" RateLimitCheckServiceType ServiceType = "ratelimit-check" RateLimitReportServiceType ServiceType = "ratelimit-report" AuthServiceType ServiceType = "auth" TracingServiceType ServiceType = "tracing" DynamicServiceType ServiceType = "dynamic" )
type Static ¶
type Static struct {
Static StaticSpec `json:"static"`
}
type StaticSpec ¶
type TypedAction ¶ added in v1.5.0
type TypedAction struct {
Type string `json:"type"`
Predicate string `json:"predicate"`
Terminal bool `json:"terminal"`
Var string `json:"var,omitempty"`
Service string `json:"service,omitempty"`
MessageBuilder string `json:"messageBuilder,omitempty"`
OnReply []TypedAction `json:"onReply,omitempty"`
DenyWith string `json:"denyWith,omitempty"`
Target string `json:"target,omitempty"`
Headers string `json:"headers,omitempty"`
LogMessage string `json:"logMessage,omitempty"`
// SourcePolicyLocators tracks all policies that contributed to this action.
// Format: "kind/namespace/name"
SourcePolicyLocators []string `json:"sources,omitempty"`
}
TypedAction represents an extension pipeline action in the new wasm-shim format. The "type" field discriminates the action kind (grpc, deny, headers).
func (TypedAction) EqualTo ¶ added in v1.5.0
func (t TypedAction) EqualTo(other TypedAction) bool