featureflag

Documentation

Index

• type EvaluationContext
• type FlagCache
  • func NewFlagCache(ttl time.Duration) *FlagCache
  • func (c *FlagCache) Flush()
  • func (c *FlagCache) Get(flagKey, userKey string) (FlagValue, bool)
  • func (c *FlagCache) Invalidate(flagKey, userKey string)
  • func (c *FlagCache) InvalidateFlag(flagKey string)
  • func (c *FlagCache) Len() int
  • func (c *FlagCache) Set(flagKey, userKey string, val FlagValue)
• type FlagChangeEvent
• type FlagMeta
• type FlagType
• type FlagValue
• type Provider
• type Service
  • func NewService(provider Provider, cache *FlagCache, logger *slog.Logger) *Service
  • func (s *Service) AllFlags(ctx context.Context, evalCtx EvaluationContext) ([]FlagValue, error)
  • func (s *Service) Evaluate(ctx context.Context, key string, evalCtx EvaluationContext) (FlagValue, error)
  • func (s *Service) SSEHandler() http.HandlerFunc
  • func (s *Service) SubscriberCount() int

Types

type EvaluationContext

type EvaluationContext struct {
	UserKey    string            `json:"user_key"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

EvaluationContext holds the contextual data used to evaluate a feature flag. The UserKey uniquely identifies the subject (user, service, etc.). Attributes carry additional targeting information such as email, groups, plan, etc.

type FlagCache

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

FlagCache is a thread-safe in-memory TTL cache for evaluated flag values. A TTL of zero disables caching (every Get returns a miss).

func NewFlagCache

func NewFlagCache(ttl time.Duration) *FlagCache

NewFlagCache creates a cache with the given TTL. Pass 0 to disable caching.

func (*FlagCache) Flush

func (c *FlagCache) Flush()

Flush removes all entries.

func (*FlagCache) Get

func (c *FlagCache) Get(flagKey, userKey string) (FlagValue, bool)

Get returns the cached value and true if a non-expired entry exists.

func (*FlagCache) Invalidate

func (c *FlagCache) Invalidate(flagKey, userKey string)

Invalidate removes a single entry from the cache.

func (*FlagCache) InvalidateFlag

func (c *FlagCache) InvalidateFlag(flagKey string)

InvalidateFlag removes all entries for the given flag key.

func (*FlagCache) Len

func (c *FlagCache) Len() int

Len returns the number of entries (including expired ones not yet evicted).

func (*FlagCache) Set

func (c *FlagCache) Set(flagKey, userKey string, val FlagValue)

Set stores a flag value in the cache. No-op when TTL is zero.

type FlagChangeEvent

type FlagChangeEvent struct {
	Key    string   `json:"key"`
	Value  any      `json:"value"`
	Type   FlagType `json:"type"`
	Source string   `json:"source"`
}

FlagChangeEvent is emitted when a flag value changes within a provider.

type FlagMeta

type FlagMeta struct {
	Key         string    `json:"key"`
	Type        FlagType  `json:"type"`
	Description string    `json:"description,omitempty"`
	Enabled     bool      `json:"enabled"`
	Tags        []string  `json:"tags,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

FlagMeta describes a flag definition without evaluating it.

type FlagType

type FlagType string

FlagType enumerates the supported feature flag value types.

const (
	FlagTypeBoolean FlagType = "boolean"
	FlagTypeString  FlagType = "string"
	FlagTypeInteger FlagType = "integer"
	FlagTypeFloat   FlagType = "float"
	FlagTypeJSON    FlagType = "json"
)

type FlagValue

type FlagValue struct {
	Key      string          `json:"key"`
	Value    any             `json:"value"`
	Type     FlagType        `json:"type"`
	Source   string          `json:"source"`             // provider name that produced the value
	Reason   string          `json:"reason,omitempty"`   // why this value was selected
	Metadata json.RawMessage `json:"metadata,omitempty"` // provider-specific extra data
}

FlagValue represents the evaluated result of a single feature flag.

type Provider

type Provider interface {
	// Name returns a unique identifier for this provider (e.g. "generic", "launchdarkly").
	Name() string

	// Evaluate returns the resolved flag value for the given key and context.
	// Returns an error if the flag does not exist or evaluation fails.
	Evaluate(ctx context.Context, key string, evalCtx EvaluationContext) (FlagValue, error)

	// AllFlags returns the evaluated values for every flag visible to the given context.
	AllFlags(ctx context.Context, evalCtx EvaluationContext) ([]FlagValue, error)

	// Subscribe registers a callback that is invoked whenever a flag changes.
	// The returned function cancels the subscription.
	Subscribe(fn func(FlagChangeEvent)) (cancel func())
}

Provider is the interface that all feature-flag backends must implement.

type Service

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

Service is a caching proxy that sits between consumers and a Provider. It adds an in-memory cache, SSE broadcasting, and audit logging.

func NewService

func NewService(provider Provider, cache *FlagCache, logger *slog.Logger) *Service

NewService creates a Service wrapping the given provider and cache.

func (*Service) AllFlags

func (s *Service) AllFlags(ctx context.Context, evalCtx EvaluationContext) ([]FlagValue, error)

AllFlags delegates to the provider (cache is per-key, so we don't cache AllFlags).

func (*Service) Evaluate

func (s *Service) Evaluate(ctx context.Context, key string, evalCtx EvaluationContext) (FlagValue, error)

Evaluate returns the flag value for the given key. Cache is checked first; on a miss the provider is queried and the result is cached.

func (*Service) SSEHandler

func (s *Service) SSEHandler() http.HandlerFunc

SSEHandler returns an HTTP handler that streams flag change events to clients. Events are formatted as:

event: flag.updated
data: {"key":"my-flag","value":true,"type":"boolean","source":"generic"}

func (*Service) SubscriberCount

func (s *Service) SubscriberCount() int

SubscriberCount returns the number of active SSE subscribers.