wasm

package
v1.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 16, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

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

View Source
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 ActionSetNameForPath(pathID string, httpRouteMatchIndex int, hostname string) string

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 ExtensionName(gatewayName string) string

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

func (a *Action) EqualTo(other Action) bool

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

func (a *Action) HasAuthAccess() bool

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

func (s *ActionSet) EqualTo(other ActionSet) bool

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 (s ActionSet) MarshalJSON() ([]byte, error)

func (*ActionSet) UnmarshalJSON added in v1.5.0

func (s *ActionSet) UnmarshalJSON(data []byte) error

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 ConfigFromStruct

func ConfigFromStruct(structure *structpb.Struct) (*Config, error)

func (*Config) EqualTo

func (c *Config) EqualTo(other *Config) bool

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.

func (*Config) ToJSON

func (c *Config) ToJSON() (*apiextensionsv1.JSON, error)

func (*Config) ToStruct

func (c *Config) ToStruct() (*_struct.Struct, error)

type DataType

type DataType struct {
	Value any
}

func (*DataType) EqualTo

func (d *DataType) EqualTo(other DataType) bool

func (*DataType) MarshalJSON

func (d *DataType) MarshalJSON() ([]byte, error)

func (*DataType) UnmarshalJSON

func (d *DataType) UnmarshalJSON(data []byte) error

type Expression

type Expression struct {
	// Data to be sent to the service
	ExpressionItem ExpressionItem `json:"expression"`
}

type ExpressionItem

type ExpressionItem struct {
	// Key holds the expression key
	Key string `json:"key"`

	// Value holds the CEL expression
	Value string `json:"value"`
}

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 LogLevel added in v1.4.0

type LogLevel int
const (
	LogLevelError LogLevel = iota
	LogLevelWarn
	LogLevelInfo
	LogLevelDebug
)

func (LogLevel) String added in v1.4.0

func (ll LogLevel) String() string

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"`
}

func (Service) EqualTo

func (s Service) EqualTo(other Service) bool

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 StaticSpec struct {
	Value string `json:"value"`
	Key   string `json:"key"`
}

type Tracing added in v1.4.0

type Tracing struct {
	Service string `json:"service,omitempty"`
}

func (*Tracing) EqualTo added in v1.4.0

func (t *Tracing) EqualTo(other *Tracing) bool

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL