policyv1alpha

type APIKey struct {
	// ID of the API Key
	ID string `json:"id" yaml:"id"`
	// Name of the API key (URL-safe identifier, auto-generated, immutable)
	Name string `json:"name" yaml:"name"`
	// DisplayName is the human-readable name (user-provided, mutable)
	DisplayName string `json:"displayName" yaml:"displayName"`
	// ApiKey API key with apip_ prefix
	APIKey string `json:"apiKey" yaml:"apiKey"`
	// APIId Unique identifier of the API that the key is associated with
	APIId string `json:"apiId" yaml:"apiId"`
	// Operations List of API operations the key will have access to
	Operations string `json:"operations" yaml:"operations"`
	// Status of the API key
	Status APIKeyStatus `json:"status" yaml:"status"`
	// CreatedAt Timestamp when the API key was generated
	CreatedAt time.Time `json:"createdAt" yaml:"createdAt"`
	// CreatedBy User who created the API key
	CreatedBy string `json:"createdBy" yaml:"createdBy"`
	// UpdatedAt Timestamp when the API key was last updated
	UpdatedAt time.Time `json:"updatedAt" yaml:"updatedAt"`
	// ExpiresAt Expiration timestamp (null if no expiration)
	ExpiresAt *time.Time `json:"expiresAt" yaml:"expiresAt"`
	// Source tracking for external key support ("local" | "external")
	Source string `json:"source" yaml:"source"`
	// IndexKey Pre-computed hash for O(1) lookup (external plain text keys only)
	IndexKey string `json:"indexKey" yaml:"indexKey"`
}

type APIKeyStatus string

type APIkeyStore struct {
	// contains filtered or unexported fields
}

type Body struct {
	// Content is the body payload (may be nil)
	Content []byte

	// EndOfStream indicates if this is the final chunk of body data
	// true = complete body received, false = more chunks may follow
	EndOfStream bool

	// Present indicates if body data is available
	// false = body was not sent or not buffered (e.g., streaming)
	// true = body is available (Content may still be nil for empty bodies)
	Present bool
}

type BodyProcessingMode string

type DropHeaderAction struct {
	Action  string   // Type of the action -> "allow" or "deny"
	Headers []string // Headers list to drop or allow
}

type HeaderProcessingMode string

type Headers struct {
	// contains filtered or unexported fields
}

type ImmediateResponse struct {
	StatusCode               int
	Headers                  map[string]string
	Body                     []byte
	AnalyticsMetadata        map[string]any            // Custom analytics metadata (key-value pairs)
	DynamicMetadata          map[string]map[string]any // Dynamic metadata by namespace
	DropHeadersFromAnalytics DropHeaderAction          // Headers to be excluded from analytics event
}

type LazyResource struct {
	// ID uniquely identifies this resource within its type
	ID string `json:"id" yaml:"id"`

	// ResourceType identifies the type of resource (e.g., "LlmProviderTemplate")
	ResourceType string `json:"resource_type" yaml:"resource_type"`

	// Resource contains the actual resource data as a map
	Resource map[string]interface{} `json:"resource" yaml:"resource"`
}

type LazyResourceStore struct {
	// contains filtered or unexported fields
}

type Level string

type ParameterType string

type ParsedAPIKey struct {
	APIKey string
	ID     string
}

type Policy interface {

	// Mode returns the policy's processing mode for each phase
	// Used by the kernel to optimize execution (e.g., skip body buffering if not needed)
	Mode() ProcessingMode

	// OnRequest executes the policy during request phase
	// Called with request context including headers and body (if body mode is BUFFER)
	// Returns RequestAction with modifications or immediate response
	// Returns nil if policy has no action (pass-through)
	OnRequest(ctx *RequestContext, params map[string]interface{}) RequestAction

	// OnResponse executes the policy during response phase
	// Called with response context including headers and body (if body mode is BUFFER)
	// Returns ResponseAction with modifications
	// Returns nil if policy has no action (pass-through)
	OnResponse(ctx *ResponseContext, params map[string]interface{}) ResponseAction
}

type PolicyDefinition struct {
	// Policy name (e.g., "jwtValidation", "rateLimiting")
	Name string `yaml:"name" json:"name"`

	// Semantic version of THIS definition (e.g., "v1.0.0", "v2.0.0")
	// Each version gets its own PolicyDefinition
	Version string `yaml:"version" json:"version"`

	// Human-readable description of what this policy version does
	Description string `yaml:"description" json:"description"`

	// Parameters for THIS version
	// Each schema defines name, type, validation rules
	Parameters map[string]interface{} `yaml:"parameters" json:"parameters"`

	// SystemParameters for THIS version
	SystemParameters map[string]interface{} `yaml:"systemParameters" json:"systemParameters"`
}

type PolicyFactory func(metadata PolicyMetadata, params map[string]interface{}) (Policy, error)

type PolicyMetadata struct {
	// RouteName is the unique identifier for the route this policy is attached to
	RouteName string

	// APIId is the unique identifier of the API this policy belongs to
	APIId string

	// APIName is the name of the API this policy belongs to
	APIName string

	// APIVersion is the version of the API this policy belongs to
	APIVersion string

	// AttachedTo indicates where the policy is attached (e.g., LevelAPI, LevelRoute)
	AttachedTo Level
}

type PolicyParameters struct {
	// Raw parameter values as received from xDS config (JSON/YAML)
	Raw map[string]interface{}

	// Validated parameters matching the policy's schema
	// Validated at configuration time, not execution time
	// Key: parameter name, Value: typed validated value
	Validated map[string]TypedValue
}

type PolicySpec struct {
	// Policy identifier (e.g., "jwtValidation", "rateLimiting")
	// Must match a registered policy name in PolicyRegistry
	Name string `yaml:"name" json:"name"`

	// Semantic version of policy implementation (e.g., "v1.0.0", "v2.1.0")
	// Must match a registered policy version in PolicyRegistry
	Version string `yaml:"version" json:"version"`

	// Static enable/disable toggle
	// If false, policy never executes regardless of ExecutionCondition
	Enabled bool `yaml:"enabled" json:"enabled"`

	// Typed and validated configuration parameters
	// Validated against PolicyDefinition.ParameterSchemas at config time
	Parameters PolicyParameters `yaml:"parameters" json:"parameters"`

	// Optional CEL expression for dynamic conditional execution
	// nil = always execute (when Enabled=true)
	// non-nil = only execute when expression evaluates to true
	// Expression context: RequestContext (request phase) or ResponseContext (response phase)
	ExecutionCondition *string `yaml:"executionCondition,omitempty" json:"executionCondition,omitempty"`
}

type ProcessingMode struct {
	// RequestHeaderMode specifies if/how the policy processes request headers
	RequestHeaderMode HeaderProcessingMode

	// RequestBodyMode specifies if/how the policy processes request body
	RequestBodyMode BodyProcessingMode

	// ResponseHeaderMode specifies if/how the policy processes response headers
	ResponseHeaderMode HeaderProcessingMode

	// ResponseBodyMode specifies if/how the policy processes response body
	ResponseBodyMode BodyProcessingMode
}

type RequestAction interface {
	StopExecution() bool // returns true if execution should stop
	// contains filtered or unexported methods
}

type RequestContext struct {
	// Shared data across request/response lifecycle
	*SharedContext

	// Current request headers (read-only for policies)
	// Policies use Get(), Has(), Iterate() methods for read-only access
	// Kernel updates via UnsafeInternalValues()
	Headers   *Headers
	Body      *Body
	Path      string
	Method    string
	Authority string
	Scheme    string
	Vhost     string
}

type ResponseAction interface {
	StopExecution() bool // returns true if execution should stop
	// contains filtered or unexported methods
}

type ResponseContext struct {
	// Shared data across request/response lifecycle
	*SharedContext

	// Original request data (immutable, from request phase)
	RequestHeaders *Headers
	RequestBody    *Body
	RequestPath    string
	RequestMethod  string

	// Current response headers (read-only for policies)
	// Policies use Get(), Has(), Iterate() methods for read-only access
	// Kernel updates via UnsafeInternalValues()
	ResponseHeaders *Headers

	// Current response body (mutable)
	// nil if no body or body not required
	ResponseBody *Body

	// Current response status code (mutable)
	ResponseStatus int
}

type SharedContext struct {
	// ProjectID is the project ID which the API is associated with
	ProjectID string

	// Unique request identifier for correlation
	// Generated by Kernel, immutable
	RequestID string

	// Shared metadata for inter-policy communication
	// Persists from request phase through response phase
	// Policies read/write this map to coordinate behavior
	Metadata map[string]interface{}

	// APIId is the unique identifier of the API (e.g., UUID)
	APIId string

	// APIName is the name of the API (e.g., "PetStore")
	APIName string

	// APIVersion is the version of the API (e.g., "v1.0.0")
	APIVersion string

	// APIKind is the type of the API
	APIKind string

	// APIContext is the base context path of the API (e.g., "/petstore")
	// This is the base path without the version
	APIContext string

	// OperationPath is the operation path pattern from the API definition
	// (e.g., "/pets/{id}" for a parameterized path)
	// This differs from RequestContext.Path which contains the actual request path
	// with resolved parameters (e.g., "/petstore/v1.0.0/pets/123")
	OperationPath string

	// AuthContext stores authentication-related information
	// Policies can read/write this map to share auth data (e.g., user ID)
	AuthContext map[string]string
}

type TypedValue struct {
	// Parameter type (string, int, float, bool, duration, array, map, uri, email, etc.)
	Type ParameterType

	// Actual value after validation and type conversion
	// Go native type matching ParameterType:
	//   string → string
	//   int → int64
	//   float → float64
	//   bool → bool
	//   duration → time.Duration
	//   string_array → []string
	//   int_array → []int64
	//   uri → string (validated as URI)
	//   email → string (validated as email)
	//   hostname → string (validated as hostname)
	//   ipv4 → string (validated as IPv4)
	//   ipv6 → string (validated as IPv6)
	//   uuid → string (validated as UUID)
	//   map → map[string]interface{}
	Value interface{}
}

type UpstreamRequestModifications struct {
	SetHeaders               map[string]string         // Set or replace headers
	RemoveHeaders            []string                  // Headers to remove
	AppendHeaders            map[string][]string       // Headers to append
	AddQueryParameters       map[string][]string       // Query parameters to add
	RemoveQueryParameters    []string                  // Query parameters to remove
	Body                     []byte                    // nil = no change, []byte{} = clear
	Path                     *string                   // nil = no change
	Method                   *string                   // nil = no change
	AnalyticsMetadata        map[string]any            // Custom analytics metadata (key-value pairs)
	DynamicMetadata          map[string]map[string]any // Dynamic metadata by namespace
	DropHeadersFromAnalytics DropHeaderAction          // Request headers to exclude from analytics event
}

type UpstreamResponseModifications struct {
	SetHeaders               map[string]string         // Set or replace headers
	RemoveHeaders            []string                  // Headers to remove
	AppendHeaders            map[string][]string       // Headers to append
	Body                     []byte                    // nil = no change, []byte{} = clear
	StatusCode               *int                      // nil = no change
	AnalyticsMetadata        map[string]any            // Custom analytics metadata (key-value pairs)
	DynamicMetadata          map[string]map[string]any // Dynamic metadata by namespace
	DropHeadersFromAnalytics DropHeaderAction          // Response headers to exclude from analytics event
}

type ValidationRules struct {
	// String validation
	MinLength *int
	MaxLength *int
	Pattern   string // regex pattern
	Format    string // email, uri, hostname, ipv4, ipv6, uuid
	Enum      []string

	// Numeric validation (int, float)
	Min        *float64
	Max        *float64
	MultipleOf *float64

	// Array validation
	MinItems    *int
	MaxItems    *int
	UniqueItems bool

	// Duration validation
	MinDuration *time.Duration
	MaxDuration *time.Duration

	// Custom CEL validation expression
	// Expression context: value
	// Must return bool
	CustomValidation *string
}