InstaNode-dev
diff --git a/‎featureflag/contract_test.go‎
Lines changed: 151 additions & 0 deletions b/‎featureflag/contract_test.go‎
Lines changed: 151 additions & 0 deletions
diff --git a/‎featureflag/errors.go‎
Lines changed: 14 additions & 0 deletions b/‎featureflag/errors.go‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎featureflag/factory.go‎
Lines changed: 152 additions & 0 deletions b/‎featureflag/factory.go‎
Lines changed: 152 additions & 0 deletions
@@ -0,0 +1,151 @@
+package featureflag_test
+
+// contract_test.go — registry-iterating contract test for the feature-flag
+// abstraction (CLAUDE.md rule 18).
+//
+// Every backend registers itself with the global registry at package-init via
+// featureflag.Register(name, builder). This test iterates the LIVE registry
+// rather than a hand-typed slice, so a third backend added later is
+// automatically held to the same fail-closed contract.
+//
+// THE central invariant (the inverse of the repo's "fail open on Redis" rule):
+// every backend MUST return the caller-supplied DEFAULT on every failure mode —
+//   - the flag is missing
+//   - the underlying provider errors
+//   - the eval context is nil/empty (no targeting info)
+//   - the context is cancelled / nil
+// Failing closed means an unbuilt feature is OFF for everyone unless explicitly
+// targeted on. This file is the load-bearing proof of that guarantee.
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"instant.dev/common/featureflag"
+
+	// side-effect imports register each backend with the registry.
+	// NOTE: the flagd backend is deferred to a follow-up PR (it ships with the
+	// flagd deployment and pulls the OpenFeature+flagd dep tree, which carries
+	// GO-2026-4279 until flagd/core >= v0.13.1). Config "flagd" currently
+	// degrades to the static backend (fail-closed) via the factory. Until then
+	// the registry holds only `static`, and the contract below still iterates it.
+	_ "instant.dev/common/featureflag/static"
+)
+
+// configForBackend returns the minimum Config to construct each backend such
+// that it has NO usable flag source — so every evaluation MUST fall back to the
+// caller default (static: supply no flags). Must fail closed.
+func configForBackend(name string) featureflag.Config {
+	return featureflag.Config{Backend: name}
+}
+
+// TestRegistry_AllBackendsFailClosed is the rule-18 contract test. It iterates
+// every registered backend and asserts the fail-closed guarantee across all the
+// failure surfaces, for all three typed accessors.
+func TestRegistry_AllBackendsFailClosed(t *testing.T) {
+	registered := featureflag.ListRegistered()
+	require.GreaterOrEqual(t, len(registered), 1,
+		"expected at least 1 backend registered (static; flagd deferred to a follow-up PR); got %v", registered)
+
+	for _, name := range registered {
+		name := name
+		t.Run(name, func(t *testing.T) {
+			p, err := featureflag.Factory(configForBackend(name))
+			// Factory NEVER hard-errors (it degrades to static); err is advisory.
+			require.NotNil(t, p, "Factory(%q) returned nil provider", name)
+			t.Cleanup(func() { _ = p.Close() })
+			_ = err
+
+			ctx := context.Background()
+
+			// --- missing flag: every accessor returns its caller default ---
+			t.Run("missing_flag", func(t *testing.T) {
+				gotBool, _ := p.BoolVariant(ctx, "no_such_flag", true, featureflag.EvalContext{})
+				assert.True(t, gotBool, "%s: missing bool flag must return caller default (true)", name)
+				gotBool2, _ := p.BoolVariant(ctx, "no_such_flag", false, featureflag.EvalContext{})
+				assert.False(t, gotBool2, "%s: missing bool flag must return caller default (false)", name)
+
+				gotStr, _ := p.StringVariant(ctx, "no_such_flag", "DEFAULT", featureflag.EvalContext{})
+				assert.Equal(t, "DEFAULT", gotStr, "%s: missing string flag must return caller default", name)
+
+				gotInt, _ := p.IntVariant(ctx, "no_such_flag", 42, featureflag.EvalContext{})
+				assert.Equal(t, int64(42), gotInt, "%s: missing int flag must return caller default", name)
+			})
+
+			// --- nil / empty eval context: still returns default ---
+			t.Run("empty_eval_context", func(t *testing.T) {
+				got, _ := p.BoolVariant(ctx, "feature_team_billing", false, featureflag.EvalContext{})
+				assert.False(t, got, "%s: empty eval context must not enable a gated feature", name)
+
+				gotNilAttrs, _ := p.BoolVariant(ctx, "feature_team_billing", false, featureflag.EvalContext{
+					Attributes: nil,
+				})
+				assert.False(t, gotNilAttrs, "%s: nil attributes must not enable a gated feature", name)
+			})
+
+			// --- nil context: must fail closed, never panic ---
+			t.Run("nil_context", func(t *testing.T) {
+				//nolint:staticcheck // SA1012: deliberately passing nil ctx to prove fail-closed
+				got, err := p.BoolVariant(nil, "anything", false, featureflag.EvalContext{})
+				assert.False(t, got, "%s: nil context must return caller default", name)
+				assert.Error(t, err, "%s: nil context should surface an advisory error", name)
+			})
+
+			// --- cancelled context: must fail closed ---
+			t.Run("cancelled_context", func(t *testing.T) {
+				cctx, cancel := context.WithCancel(context.Background())
+				cancel()
+				got, err := p.BoolVariant(cctx, "anything", false, featureflag.EvalContext{})
+				assert.False(t, got, "%s: cancelled context must return caller default", name)
+				assert.Error(t, err, "%s: cancelled context should surface an advisory error", name)
+			})
+
+			// --- Name + Close contract ---
+			t.Run("name_and_close", func(t *testing.T) {
+				assert.NotEmpty(t, p.Name(), "%s: Name() must be non-empty", name)
+				assert.NoError(t, p.Close(), "%s: Close() must be a clean no-op", name)
+				assert.NoError(t, p.Close(), "%s: Close() must be idempotent", name)
+			})
+		})
+	}
+}
+
+// TestFactory_UnknownBackendDegradesToStatic verifies the DELIBERATE difference
+// from storageprovider/queueprovider: an unknown backend does NOT hard-fail the
+// service. It degrades to the static (fail-closed) backend and returns an
+// advisory error — because a flag system that refuses to boot is strictly worse
+// than one serving OFF defaults.
+func TestFactory_UnknownBackendDegradesToStatic(t *testing.T) {
+	p, err := featureflag.Factory(featureflag.Config{Backend: "made-up-backend"})
+	require.NotNil(t, p, "unknown backend must still yield a usable provider")
+	assert.ErrorIs(t, err, featureflag.ErrUnknownBackend, "should surface advisory ErrUnknownBackend")
+	// The degraded provider must serve fail-closed defaults.
+	got, _ := p.BoolVariant(context.Background(), "anything", false, featureflag.EvalContext{})
+	assert.False(t, got, "degraded provider must fail closed")
+	_ = p.Close()
+}
+
+// TestNormalizeBackend covers the alias table — the SUT is the table itself, so
+// this is hand-typed (rule 18's carve-out: the table IS the registry here).
+func TestNormalizeBackend(t *testing.T) {
+	cases := map[string]string{
+		"":            featureflag.BackendStatic, // empty defaults to static
+		"static":      featureflag.BackendStatic,
+		"STATIC":      featureflag.BackendStatic,
+		"memory":      featureflag.BackendStatic,
+		"in-memory":   featureflag.BackendStatic,
+		"inmem":       featureflag.BackendStatic,
+		"file":        featureflag.BackendStatic,
+		"flagd":       featureflag.BackendFlagd,
+		"openfeature": featureflag.BackendFlagd,
+		"open-feature": featureflag.BackendFlagd,
+		"grpc":        featureflag.BackendFlagd,
+		"nonsense":    "",
+	}
+	for in, want := range cases {
+		assert.Equal(t, want, featureflag.NormalizeBackend(in), "NormalizeBackend(%q)", in)
+	}
+}
@@ -0,0 +1,14 @@
+package featureflag
+
+import "fmt"
+
+// errPanic wraps a recovered panic value as an error so the fail-closed
+// wrapper can return it alongside the caller default. The value is never
+// re-panicked — a misbehaving provider must NEVER crash a request path; the
+// feature simply reads as its default (OFF).
+func errPanic(r any) error {
+	if err, ok := r.(error); ok {
+		return fmt.Errorf("featureflag: provider panicked: %w", err)
+	}
+	return fmt.Errorf("featureflag: provider panicked: %v", r)
+}
@@ -0,0 +1,152 @@
+package featureflag
+
+import (
+	"fmt"
+	"strings"
+)
+
+// Canonical backend identifiers. These are the strings every layer (api,
+// worker, provisioner, k8s ConfigMaps) compares against.
+const (
+	// BackendStatic is the pure in-memory backend (default). Reads a flag
+	// definition map / file; NO network; tests + CI need no running flagd.
+	BackendStatic = "static"
+
+	// BackendFlagd is the OpenFeature SDK + flagd backend (gRPC streaming).
+	// IMPL DEFERRED to a follow-up PR (ships with the flagd deployment; its
+	// OpenFeature+flagd dep tree carries GO-2026-4279 until flagd/core >=
+	// v0.13.1). Until registered, config "flagd" degrades to BackendStatic
+	// (fail-closed) via the factory — same safety, no vulnerable deps in-tree.
+	BackendFlagd = "flagd"
+)
+
+// Config is the operator-facing configuration for the feature-flag backend.
+// The api / worker / provisioner wire this from env vars
+// (FEATURE_FLAG_BACKEND + per-backend knobs) and pass it to Factory() at boot.
+type Config struct {
+	// Backend selects the implementation. One of "static", "flagd". Aliases
+	// ("memory"/"inmem"/"file" -> "static"; "openfeature"/"grpc" -> "flagd").
+	// Empty defaults to "static" — the safest, dependency-free backend.
+	Backend string
+
+	// StaticFlags is the in-memory flag definition consumed by the static
+	// backend. Keyed by flag key. When both StaticFlags and StaticFilePath are
+	// empty the static backend serves an empty flag set (every flag => default,
+	// i.e. fully fail-closed). Ignored by the flagd backend.
+	StaticFlags map[string]StaticFlag
+
+	// StaticFilePath, when set, loads the static flag definition from a
+	// flagd-format JSON file at boot (the in-cluster ConfigMap mount path).
+	// StaticFlags wins over StaticFilePath on key collision. Ignored by flagd.
+	StaticFilePath string
+
+	// Flagd-specific. Host + Port of the flagd gRPC endpoint. Defaults:
+	// host "localhost", port 8013 (flagd rpc resolver default).
+	FlagdHost string
+	FlagdPort uint16
+
+	// FlagdInProcess selects the in-process resolver (flagd syncs the flag set
+	// over gRPC and evaluates locally — lowest latency) instead of the default
+	// rpc resolver (each eval is a gRPC round-trip). Both are sub-second.
+	FlagdInProcess bool
+}
+
+// NormalizeBackend maps the operator-facing value (with historical aliases)
+// onto one of the canonical backend strings. An unrecognised non-empty value
+// returns "" so Factory can decide how to degrade.
+func NormalizeBackend(raw string) string {
+	switch strings.ToLower(strings.TrimSpace(raw)) {
+	case "", "static", "memory", "in-memory", "inmem", "file":
+		return BackendStatic
+	case "flagd", "openfeature", "open-feature", "grpc":
+		return BackendFlagd
+	default:
+		return ""
+	}
+}
+
+// Factory selects and constructs the right [Provider] for cfg, ALREADY WRAPPED
+// by [Wrap] so the returned provider is guaranteed fail-closed.
+//
+// Unlike storageprovider/queueprovider — where an unknown backend hard-fails so
+// a service never silently degrades to a less-secure store — featureflag
+// degrades DELIBERATELY: an unbuilt feature defaulting OFF is the SAFE state, so
+// if the requested backend is unknown or its construction fails, Factory falls
+// back to the static backend (fail-closed defaults) and returns a nil error.
+// A flag system that refuses to boot would take the whole service down; that is
+// strictly worse than serving defaults. The returned error is non-nil only as
+// an ADVISORY (so the caller can log/alert that it degraded) — the provider is
+// always usable.
+func Factory(cfg Config) (Provider, error) {
+	name := NormalizeBackend(cfg.Backend)
+	if name == "" {
+		// Unknown backend: degrade to static, surface advisory error.
+		p, _ := newStatic(cfg)
+		return Wrap(p), fmt.Errorf("%w: %q (degraded to static, fail-closed defaults)", ErrUnknownBackend, cfg.Backend)
+	}
+
+	ctor, ok := lookupBuilder(name)
+	if !ok {
+		// Backend recognised but its impl package wasn't imported (e.g. flagd
+		// excluded from a slim build). Degrade to static.
+		p, _ := newStatic(cfg)
+		return Wrap(p), fmt.Errorf("featureflag: backend %q not registered — did you import the impl package? (degraded to static)", name)
+	}
+
+	p, err := ctor(cfg)
+	if err != nil || p == nil {
+		// Construction failed (flagd unreachable at boot, bad config, ...).
+		// Degrade to static rather than failing the service.
+		sp, _ := newStatic(cfg)
+		return Wrap(sp), fmt.Errorf("featureflag: backend %q failed to construct (%v) — degraded to static", name, err)
+	}
+	return Wrap(p), nil
+}
+
+// Builder is the constructor signature each backend registers via Register from
+// its package init(). Keeping flagd's OpenFeature + gRPC transitive deps in a
+// subpackage means `common` consumers that only use the static backend don't
+// pull the flagd SDK into their import graph (same pattern as queueprovider).
+type Builder func(cfg Config) (Provider, error)
+
+var builders = map[string]Builder{}
+
+// Register adds a Builder under name. Called from each backend package's
+// init(). Idempotent — a second registration with the same name overwrites the
+// first (used in tests to inject a fake).
+func Register(name string, b Builder) {
+	builders[NormalizeBackend(name)] = b
+}
+
+func lookupBuilder(name string) (Builder, bool) {
+	b, ok := builders[name]
+	return b, ok
+}
+
+// ListRegistered returns the names of every backend currently registered. Used
+// by the registry-iterating contract test (CLAUDE.md rule 18).
+func ListRegistered() []string {
+	out := make([]string, 0, len(builders))
+	for k := range builders {
+		out = append(out, k)
+	}
+	return out
+}
+
+// newStatic is the in-package fallback constructor used by Factory's degrade
+// paths. It does NOT depend on the static subpackage being imported, so the
+// fail-closed fallback works even in a build that never imported any backend.
+// It builds the same concrete provider the static subpackage registers.
+func newStatic(cfg Config) (Provider, error) {
+	return buildStatic(cfg)
+}
+
+// NewStaticBuilder returns the [Builder] for the in-memory static backend. The
+// featureflag/static subpackage calls this from its init() to register the
+// backend under [BackendStatic]. Exported (rather than registering from the
+// root package directly) so a slim build that never imports the static
+// subpackage keeps an empty registry, while Factory's degrade path still has a
+// hard fallback via buildStatic.
+func NewStaticBuilder() Builder {
+	return buildStatic
+}