Policy Instance Lifecycle in the Policy Engine

[renuka-fernando]

Policy Instance Lifecycle in the Policy Engine

Motivation

The gateway v0.0.1 keeps a single policy instance of a policy globally for all the routes. But there is a requirement where some policies need preprocessing initParameters and parameters (user parameters) and cache them in the policy instance. In such cases, a single global instance is not sufficient. If policy engine supports creating multiple instances of a policy, then each route can have its own instance of the policy with its own cached data.

Solution

Policy implementation should have a func named NewPolicy which returns an instance of the policy. Policy Engine will pass:

• metadata - Contains route-level metadata (currently just routeName)
• initParams - Static policy configuration from policy definition
• params - Dynamic user parameters from API configuration

Policy implementation can use these to create multiple instances if required or return a singleton instance if multiple instances are not required. This enables having a policy instance per route or per initParams/params combination. The instancing strategy is decided by the policy implementation itself.

Signature:

func NewPolicy(
    metadata policy.PolicyMetadata,
    initParams map[string]interface{},
    params map[string]interface{},
) (policy.Policy, error)

All initialization, validation, and preprocessing should be done in NewPolicy. The function returns an error if initialization fails.

Examples

Example 1: Singleton Pattern (Stateless Policy)

Policies with no cacheable state can use a singleton. Basic-auth is a good example - all configuration comes via params on each request.

package basicauth

import (
    "errors"
    policy "github.com/wso2/api-platform/sdk/gateway/policy/v1alpha"
)

type BasicAuthPolicy struct{}

// Single shared instance for all routes
var singletonInstance = &BasicAuthPolicy{}

func NewPolicy(
    metadata policy.PolicyMetadata,
    initParams map[string]interface{},
    params map[string]interface{},
) (policy.Policy, error) {
    // Validate required params
    if _, ok := params["username"]; !ok {
        return nil, errors.New("username parameter required")
    }
    if _, ok := params["password"]; !ok {
        return nil, errors.New("password parameter required")
    }

    return singletonInstance, nil // Same instance for all routes
}

func (p *BasicAuthPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    username := params["username"].(string)
    password := params["password"].(string)
    // ... authentication logic
}

Example 2: Cached Multi-Instance Pattern (Shared Config)

Policies that need to preprocess/cache configuration can reuse instances across routes with identical config. JWT validation is ideal - parsing public keys is expensive.

package jwtauth

import (
    "crypto/rsa"
    "fmt"
    "sync"
    policy "github.com/wso2/api-platform/sdk/gateway/policy/v1alpha"
)

type JWTAuthPolicy struct {
    routeName string
    publicKey *rsa.PublicKey // Cached parsed public key (immutable after creation)
    issuer    string
    audience  string
}

// Global cache: reuse instances for routes with identical config
var (
    instanceCache = make(map[string]*JWTAuthPolicy)
    cacheMu       sync.RWMutex
)

func NewPolicy(
    metadata policy.PolicyMetadata,
    initParams map[string]interface{},
    params map[string]interface{},
) (policy.Policy, error) {
    // Create cache key from initParams (e.g., JWKS URL, issuer)
    cacheKey := fmt.Sprintf("%v", initParams)

    cacheMu.RLock()
    if instance, exists := instanceCache[cacheKey]; exists {
        cacheMu.RUnlock()
        return instance, nil // Reuse existing instance
    }
    cacheMu.RUnlock()

    // Parse and cache public key (expensive operation done once)
    publicKeyPEM, ok := params["publicKey"].(string)
    if !ok {
        return nil, fmt.Errorf("publicKey parameter required")
    }
    publicKey, err := parsePublicKey(publicKeyPEM)
    if err != nil {
        return nil, fmt.Errorf("invalid public key: %w", err)
    }

    // Extract other configuration
    issuer, _ := params["issuer"].(string)
    audience, _ := params["audience"].(string)

    // Create new instance with cached data
    instance := &JWTAuthPolicy{
        routeName: metadata.RouteName,
        publicKey: publicKey,
        issuer:    issuer,
        audience:  audience,
    }

    cacheMu.Lock()
    instanceCache[cacheKey] = instance
    cacheMu.Unlock()

    return instance, nil
}

func (p *JWTAuthPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    token := extractToken(ctx.Headers)
    if err := validateJWT(token, p.publicKey, p.issuer, p.audience); err != nil {
        return policy.ImmediateResponse{
            StatusCode: 401,
            Body:       []byte(`{"error": "Invalid token"}`),
        }
    }

    return policy.UpstreamRequestModifications{}
}

Example 3: Per-Route Instance Pattern (Route-Specific State)

Policies that maintain route-specific state need dedicated instances per route. Rate limiting is a perfect example - each route needs its own counters.

Key insight: Cache by routeName to ensure one instance per route and preserve state across config reloads.

package ratelimit

import (
    "fmt"
    "sync"
    "time"
    policy "github.com/wso2/api-platform/sdk/gateway/policy/v1alpha"
)

type RateLimitPolicy struct {
    routeName string
    limit     int
    window    time.Duration

    // Per-route rate limit state
    counters map[string]*counter // key: client IP or API key
    mu       sync.RWMutex
}

type counter struct {
    count       int
    windowStart time.Time
}

// Global cache: one instance per route
var (
    instanceCache = make(map[string]*RateLimitPolicy)
    cacheMu       sync.RWMutex
)

func NewPolicy(
    metadata policy.PolicyMetadata,
    initParams map[string]interface{},
    params map[string]interface{},
) (policy.Policy, error) {
    // Cache key is routeName - ensures one instance per route
    cacheKey := metadata.RouteName

    cacheMu.RLock()
    if instance, exists := instanceCache[cacheKey]; exists {
        cacheMu.RUnlock()
        return instance, nil  // Reuse existing instance to preserve rate limit counters
    }
    cacheMu.RUnlock()

    // Validate and extract configuration
    requestsPerMin, ok := params["requestsPerMinute"].(float64)
    if !ok {
        return nil, fmt.Errorf("requestsPerMinute parameter required")
    }

    // Create new instance for this route
    instance := &RateLimitPolicy{
        routeName: metadata.RouteName,
        limit:     int(requestsPerMin),
        window:    time.Minute,
        counters:  make(map[string]*counter),
    }

    cacheMu.Lock()
    instanceCache[cacheKey] = instance
    cacheMu.Unlock()

    return instance, nil
}

func (p *RateLimitPolicy) OnRequest(ctx *policy.RequestContext, params map[string]interface{}) policy.RequestAction {
    clientID := extractClientID(ctx)

    p.mu.Lock()
    defer p.mu.Unlock()

    now := time.Now()
    c, exists := p.counters[clientID]

    if !exists || now.Sub(c.windowStart) > p.window {
        p.counters[clientID] = &counter{count: 1, windowStart: now}
        return policy.UpstreamRequestModifications{}
    }

    if c.count >= p.limit {
        return policy.ImmediateResponse{
            StatusCode: 429,
            Headers:    map[string]string{"Retry-After": "60"},
            Body:       []byte(`{"error": "Rate limit exceeded"}`),
        }
    }

    c.count++
    return policy.UpstreamRequestModifications{}
}

Summary

Three caching strategies for policy instances:

Pattern	Cache Key	When to Use	Example
Singleton	None (single global instance)	Stateless policies with no cached data	Basic Auth
Cached by Config	initParams hash	Policies with expensive preprocessing that can be shared across routes	JWT (parsed public keys)
Cached by Route	routeName	Policies with route-specific state that must be isolated	Rate Limiting (per-route counters)