controlplane

Documentation

Overview

Package controlplane provides policy providers (static and remote) for recourse.

Index

• Variables
• type PolicyCache
  • func NewPolicyCache() *PolicyCache
  • func (c *PolicyCache) Get(key policy.PolicyKey) (pol policy.EffectivePolicy, foundInCache bool, isNegativeCache bool)
  • func (c *PolicyCache) Invalidate(key policy.PolicyKey)
  • func (c *PolicyCache) Set(key policy.PolicyKey, pol policy.EffectivePolicy, ttl time.Duration)
  • func (c *PolicyCache) SetMissing(key policy.PolicyKey, ttl time.Duration)
• type PolicyProvider
• type RemoteProvider
  • func NewRemoteProvider(source Source, opts ...RemoteProviderOption) *RemoteProvider
  • func (p *RemoteProvider) GetEffectivePolicy(ctx context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)
• type RemoteProviderOption
  • func WithCacheTTL(ttl time.Duration) RemoteProviderOption
  • func WithNegativeCacheTTL(ttl time.Duration) RemoteProviderOption
• type Source
• type StaticProvider
  • func (p *StaticProvider) GetEffectivePolicy(_ context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)

Variables

var (
	// ErrProviderUnavailable indicates the provider could not be reached or used.
	ErrProviderUnavailable = errors.New("recourse: policy provider unavailable")
	// ErrPolicyNotFound indicates the provider has no policy for the requested key.
	ErrPolicyNotFound = errors.New("recourse: policy not found")
	// ErrPolicyFetchFailed indicates a provider failure other than unavailability.
	ErrPolicyFetchFailed = errors.New("recourse: policy fetch failed")
)

Types

type PolicyCache

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

PolicyCache is a thread-safe cache for policies with TTL support.

func NewPolicyCache

func NewPolicyCache() *PolicyCache

NewPolicyCache creates a new, empty PolicyCache.

func (*PolicyCache) Get

func (c *PolicyCache) Get(key policy.PolicyKey) (pol policy.EffectivePolicy, foundInCache bool, isNegativeCache bool)

Get retrieves a policy from the cache. Returns (policy, found=true) if a valid entry exists (even if it's a negative cache hit). Returns (policy, found=false) if the entry is missing or expired. If the entry is a negative cache hit, the returned policy will be zero value and found will be true. Check entry.found to distinguish between "cached missing" and "not in cache".

func (*PolicyCache) Invalidate

func (c *PolicyCache) Invalidate(key policy.PolicyKey)

Invalidate removes an entry from the cache.

func (*PolicyCache) Set

func (c *PolicyCache) Set(key policy.PolicyKey, pol policy.EffectivePolicy, ttl time.Duration)

Set adds or updates a policy in the cache.

func (*PolicyCache) SetMissing

func (c *PolicyCache) SetMissing(key policy.PolicyKey, ttl time.Duration)

SetMissing records a negative cache entry (policy not found).

type PolicyProvider

type PolicyProvider interface {
	// GetEffectivePolicy returns the policy for key.
	//
	// Providers may return a non-zero policy alongside a non-nil error to
	// communicate that the policy was obtained via a fallback path (for example,
	// last-known-good).
	GetEffectivePolicy(ctx context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)
}

PolicyProvider supplies an EffectivePolicy for a PolicyKey.

type RemoteProvider

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

RemoteProvider is a PolicyProvider that fetches policies from a Source and caches them.

func NewRemoteProvider

func NewRemoteProvider(source Source, opts ...RemoteProviderOption) *RemoteProvider

NewRemoteProvider creates a new RemoteProvider.

func (*RemoteProvider) GetEffectivePolicy

func (p *RemoteProvider) GetEffectivePolicy(ctx context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)

GetEffectivePolicy returns the policy for key, checking the cache first.

type RemoteProviderOption

type RemoteProviderOption func(*RemoteProvider)

RemoteProviderOption configures a RemoteProvider.

func WithCacheTTL

func WithCacheTTL(ttl time.Duration) RemoteProviderOption

WithCacheTTL sets the TTL for successful policy lookups. Default is 1 minute.

func WithNegativeCacheTTL

func WithNegativeCacheTTL(ttl time.Duration) RemoteProviderOption

WithNegativeCacheTTL sets the TTL for missing policy lookups. Default is 10 seconds.

type Source

type Source interface {
	// GetPolicy returns the policy for the given key.
	// If the policy is not found, it must return ErrPolicyNotFound.
	GetPolicy(ctx context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)
}

Source is the interface for fetching raw policy configuration.

type StaticProvider

type StaticProvider struct {
	Policies map[policy.PolicyKey]policy.EffectivePolicy
	Default  policy.EffectivePolicy
}

StaticProvider is an in-process PolicyProvider backed by a map and an optional default.

func (*StaticProvider) GetEffectivePolicy

func (p *StaticProvider) GetEffectivePolicy(_ context.Context, key policy.PolicyKey) (policy.EffectivePolicy, error)