Documentation
¶
Overview ¶
Package featureflag is a thin wrapper around github.com/thomaspoignant/go-feature-flag (GOFF) that gives hex applications feature-flagging with rule-based targeting, percentage rollouts, and typed variations.
See ADR-0013 for the wrap decision. Design summary:
- Type aliases (Client, Context, EvaluationContext) so consumers can call every GOFF method through the alias.
- hex-owned constructors for the two common shapes: a file on disk and a file in an embed.FS. Advanced retrievers (HTTP, S3, K8s) are supplied by importing GOFF's retriever subpackage directly and passing it via Options.Retrievers.
- Package-level convenience (SetDefault + Bool/Int/String/Float64/JSON) mirroring hex/config and hex/i18n.
Example (embed.FS):
//go:embed flags.yaml
var flagsFS embed.FS
client, err := featureflag.NewFromFS(flagsFS, "flags.yaml", featureflag.Options{
PollingInterval: 30 * time.Second,
})
if err != nil { return err }
defer client.Close()
featureflag.SetDefault(client)
ctx := featureflag.NewContext("user-42").AddCustom("beta", "true")
if featureflag.Bool("new-checkout", ctx, false) {
// ...
}
Index ¶
- func Bool(flag string, ctx Context, defaultValue bool) bool
- func Float64(flag string, ctx Context, defaultValue float64) float64
- func Int(flag string, ctx Context, defaultValue int) int
- func JSON(flag string, ctx Context, defaultValue map[string]any) map[string]any
- func JSONArray(flag string, ctx Context, defaultValue []any) []any
- func SetDefault(c *Client)
- func String(flag string, ctx Context, defaultValue string) string
- type Client
- type Context
- type ContextBuilder
- type EvaluationContext
- type Notifier
- type Options
- type Retriever
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bool ¶
Bool evaluates flag as a boolean. Returns defaultValue if the flag is missing, the default client is unset, or evaluation fails.
func SetDefault ¶
func SetDefault(c *Client)
SetDefault installs c as the package-level default client. Subsequent calls to Bool/Int/String/Float64/JSON delegate to c. Safe to call more than once.
Types ¶
type Client ¶
type Client = ffclient.GoFeatureFlag
Client is the type alias for GOFF's evaluation client. Consumers get the full upstream API through this alias (BoolVariation, IntVariation, AllFlagsState, RawVariation, etc.).
func Default ¶
func Default() *Client
Default returns the current default Client, or nil if none is set.
func New ¶
New builds a Client from a full ffclient.Config. Use this when the upstream Config surface has knobs the hex helpers do not expose.
type ContextBuilder ¶
type ContextBuilder struct {
// contains filtered or unexported fields
}
ContextBuilder is a fluent-chain wrapper around EvaluationContext.
func ContextWith ¶
func ContextWith(ec EvaluationContext) *ContextBuilder
ContextWith wraps an EvaluationContext with a fluent builder that makes attribute chains readable at call sites:
ctx := featureflag.ContextWith(featureflag.NewContext("u1")).
Set("beta", "true").
Set("region", "us").
Context()
The underlying upstream API uses void mutators (AddCustomAttribute); this helper preserves the standard EvaluationContext type for hand-off while giving callers a fluent construction path.
func (*ContextBuilder) Context ¶
func (b *ContextBuilder) Context() EvaluationContext
Context returns the underlying EvaluationContext ready to hand to a Variation call.
func (*ContextBuilder) Set ¶
func (b *ContextBuilder) Set(name string, value any) *ContextBuilder
Set attaches a custom attribute for targeting rules and returns the builder for chaining.
type EvaluationContext ¶
type EvaluationContext = ffcontext.EvaluationContext
EvaluationContext is the concrete builder type consumers use to attach user attributes for targeting rules.
func NewAnonymousContext ¶
func NewAnonymousContext(key string) EvaluationContext
NewAnonymousContext returns an anonymous EvaluationContext for unauthenticated / pre-identification traffic.
func NewContext ¶
func NewContext(userKey string) EvaluationContext
NewContext returns an EvaluationContext keyed by userKey. Wrap in ContextWith to attach attributes with a fluent chain.
type Notifier ¶
Notifier is the type alias for GOFF's Notifier interface for flag-change hooks (webhook, log, custom).
type Options ¶
type Options struct {
// PollingInterval is how often retrievers re-fetch the flag file.
// Zero uses GOFF's default (60s). Values below the GOFF minimum are
// clamped upstream.
PollingInterval time.Duration
// StartWithRetrieverError, when true, lets the client start even if
// the initial retrieve fails. Useful when the flag source is
// intermittent and you want to fall back on defaults rather than
// bail out at startup.
StartWithRetrieverError bool
// Retrievers lets consumers supply additional retrievers alongside
// the primary one built by New*/NewFromFile/NewFromFS. Later
// retrievers take precedence over earlier ones in GOFF's merge logic.
Retrievers []Retriever
// Notifiers registers flag-change listeners.
Notifiers []Notifier
// FileFormat overrides retriever content-type detection. Supported:
// "yaml", "json", "toml". Empty means auto-detect from extension.
FileFormat string
}
Options tune a Client. Only the knobs hex applications typically touch are surfaced; consumers who need advanced upstream options can construct ffclient.Config directly and call ffclient.New.
Source Files
Directories