feat: add Unleash feature flag integration to backend (#654)

Adds feature flag evaluation and workspace override management:
- Unleash client wrapper with workspace context support
- Flag evaluation endpoint with ConfigMap override precedence
- Admin endpoints for listing flags and managing overrides
- Tag-based filtering for workspace-configurable flags

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: maskarb

components/backend/README.md

@@ -179,6 +179,10 @@ make deps-verify       # Verify dependencies
 make check-env         # Verify Go, kubectl, docker installed
 ```
 
+### Feature flags (Unleash)
+
+See [docs/feature-flags](../../docs/feature-flags/README.md) for env vars, handler usage, and examples.
+
 ## Architecture
 
 See `CLAUDE.md` in project root for:
@@ -193,6 +197,8 @@ See `CLAUDE.md` in project root for:
 - `handlers/sessions.go` - AgenticSession lifecycle, user/SA client usage
 - `handlers/middleware.go` - Auth patterns, token extraction, RBAC
 - `handlers/helpers.go` - Utility functions (StringPtr, BoolPtr)
+- `handlers/featureflags.go` - Feature flag helpers (see docs/feature-flags/)
+- `featureflags/featureflags.go` - Unleash client init
 - `types/common.go` - Type definitions
 - `server/server.go` - Server setup, middleware chain, token redaction
 - `routes.go` - HTTP route definitions and registration

components/backend/featureflags/featureflags.go

@@ -0,0 +1,63 @@
+// Package featureflags provides optional Unleash-backed feature flag checks for the backend.
+// When UNLEASH_URL and UNLEASH_CLIENT_KEY are not set, all flags are disabled (IsEnabled returns false).
+package featureflags
+
+import (
+	"log"
+	"net/http"
+	"os"
+	"strings"
+
+	"github.com/Unleash/unleash-go-sdk/v5"
+	unleashContext "github.com/Unleash/unleash-go-sdk/v5/context"
+)
+
+const appName = "ambient-code-backend"
+
+var initialized bool
+
+// Init initializes the Unleash client when UNLEASH_URL and UNLEASH_CLIENT_KEY are set.
+// Safe to call multiple times; only initializes once when config is present.
+// Call from main after loading env and before starting the server.
+func Init() {
+	url := strings.TrimSpace(os.Getenv("UNLEASH_URL"))
+	clientKey := strings.TrimSpace(os.Getenv("UNLEASH_CLIENT_KEY"))
+	if url == "" || clientKey == "" {
+		return
+	}
+	// Ensure URL has a trailing slash for the SDK
+	if !strings.HasSuffix(url, "/") {
+		url += "/"
+	}
+	unleash.Initialize(
+		unleash.WithAppName(appName),
+		unleash.WithUrl(url),
+		unleash.WithCustomHeaders(http.Header{"Authorization": {clientKey}}),
+	)
+	initialized = true
+	log.Printf("Unleash feature flags enabled (url=%s)", strings.TrimSuffix(url, "/"))
+}
+
+// IsEnabled returns true if the named feature flag is enabled.
+// When Unleash is not configured, returns false. Safe to call from any handler.
+func IsEnabled(flagName string) bool {
+	if !initialized {
+		return false
+	}
+	return unleash.IsEnabled(flagName)
+}
+
+// IsEnabledWithContext returns true if the flag is enabled for the given user context.
+// Use for strategies that depend on userId, sessionId, or remoteAddress.
+// When Unleash is not configured, returns false.
+func IsEnabledWithContext(flagName string, userID, sessionID, remoteAddress string) bool {
+	if !initialized {
+		return false
+	}
+	ctx := unleashContext.Context{
+		UserId:        userID,
+		SessionId:     sessionID,
+		RemoteAddress: remoteAddress,
+	}
+	return unleash.IsEnabled(flagName, unleash.WithContext(ctx))
+}

components/backend/go.mod

@@ -5,6 +5,7 @@ go 1.24.0
 toolchain go1.24.7
 
 require (
+	github.com/Unleash/unleash-go-sdk/v5 v5.1.0
 	github.com/anthropics/anthropic-sdk-go v1.2.0
 	github.com/gin-contrib/cors v1.7.6
 	github.com/gin-gonic/gin v1.10.1
@@ -54,6 +55,7 @@ require (
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
+	github.com/launchdarkly/eventsource v1.10.0 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -64,11 +66,13 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/tidwall/gjson v1.18.0 // indirect
 	github.com/tidwall/match v1.1.1 // indirect
 	github.com/tidwall/pretty v1.2.1 // indirect
 	github.com/tidwall/sjson v1.2.5 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
+	github.com/twmb/murmur3 v1.1.8 // indirect
 	github.com/ugorji/go/codec v1.3.0 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
 	go.opencensus.io v0.24.0 // indirect

components/backend/go.sum

@@ -8,6 +8,8 @@ cloud.google.com/go/compute/metadata v0.5.0/go.mod h1:aHnloV2TPI38yx4s9+wAZhHykW
 github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
 github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/Unleash/unleash-go-sdk/v5 v5.1.0 h1:W+HHQklU5/H9kjYTn/T4TKvDHE0BxnZ0+MyTk06RdYw=
+github.com/Unleash/unleash-go-sdk/v5 v5.1.0/go.mod h1:1u8BfdyjlkV5j43la61n9A9ul4E+YQC2kKQotz8z7BE=
 github.com/anthropics/anthropic-sdk-go v1.2.0 h1:RQzJUqaROewrPTl7Rl4hId/TqmjFvfnkmhHJ6pP1yJ8=
 github.com/anthropics/anthropic-sdk-go v1.2.0/go.mod h1:AapDW22irxK2PSumZiQXYUFvsdQgkwIWlpESweWZI/c=
 github.com/bytedance/sonic v1.13.3 h1:MS8gmaH16Gtirygw7jV91pDCN33NyMrPbN7qiYhEsF0=
@@ -116,6 +118,10 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/googleapis/enterprise-certificate-proxy v0.3.2 h1:Vie5ybvEvT75RniqhfFxPRy3Bf7vr3h0cechB90XaQs=
 github.com/googleapis/enterprise-certificate-proxy v0.3.2/go.mod h1:VLSiSSBs/ksPL8kq3OBOQ6WRI2QnaFynd1DCjZ62+V0=
+github.com/h2non/gock v1.2.0 h1:K6ol8rfrRkUOefooBC8elXoaNGYkpp7y2qcxGG6BzUE=
+github.com/h2non/gock v1.2.0/go.mod h1:tNhoxHYW2W42cYkYb1WqzdbYIieALC99kpYr7rH/BQk=
+github.com/h2non/parth v0.0.0-20190131123155-b4df798d6542 h1:2VTzZjLZBgl62/EtslCrtky5vbi9dd7HrQPQIx6wqiw=
+github.com/h2non/parth v0.0.0-20190131123155-b4df798d6542/go.mod h1:Ow0tF8D4Kplbc8s8sSb3V2oUCygFHVp8gC3Dn6U4MNI=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
@@ -137,6 +143,10 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/launchdarkly/eventsource v1.10.0 h1:H9Tp6AfGu/G2qzBJC26iperrvwhzdbiA/gx7qE2nDFI=
+github.com/launchdarkly/eventsource v1.10.0/go.mod h1:J3oa50bPvJesZqNAJtb5btSIo5N6roDWhiAS3IpsKck=
+github.com/launchdarkly/go-test-helpers/v3 v3.1.0 h1:E3bxJMzMoA+cJSF3xxtk2/chr1zshl1ZWa0/oR+8bvg=
+github.com/launchdarkly/go-test-helpers/v3 v3.1.0/go.mod h1:Ake5+hZFS/DmIGKx/cizhn5W9pGA7pplcR7xCxWiLIo=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
@@ -155,6 +165,8 @@ github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFd
 github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
 github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/nbio/st v0.0.0-20140626010706-e9e8d9816f32 h1:W6apQkHrMkS0Muv8G/TipAy/FJl/rCYT0+EuS8+Z0z4=
+github.com/nbio/st v0.0.0-20140626010706-e9e8d9816f32/go.mod h1:9wM+0iRr9ahx58uYLpLIr5fm8diHn0JbqRycJi6w0Ms=
 github.com/onsi/ginkgo/v2 v2.27.3 h1:ICsZJ8JoYafeXFFlFAG75a7CxMsJHwgKwtO+82SE9L8=
 github.com/onsi/ginkgo/v2 v2.27.3/go.mod h1:ArE1D/XhNXBXCBkKOLkbsb2c81dQHCRcF5zwn/ykDRo=
 github.com/onsi/gomega v1.38.3 h1:eTX+W6dobAYfFeGC2PV6RwXRu/MyT+cQguijutvkpSM=
@@ -194,6 +206,8 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
+github.com/twmb/murmur3 v1.1.8 h1:8Yt9taO/WN3l08xErzjeschgZU2QSrwm1kclYq+0aRg=
+github.com/twmb/murmur3 v1.1.8/go.mod h1:Qq/R7NUyOfr65zD+6Q5IHKsJLwP7exErjN6lyyq3OSQ=
 github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=
 github.com/ugorji/go/codec v1.3.0/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=

components/backend/handlers/featureflags.go

@@ -0,0 +1,27 @@
+// Package handlers: feature flag helpers for use inside HTTP handlers.
+// Backed by the optional Unleash integration (see featureflags package).
+// When Unleash is not configured, all flags are disabled.
+
+package handlers
+
+import (
+	"ambient-code-backend/featureflags"
+
+	"github.com/gin-gonic/gin"
+)
+
+// FeatureEnabled returns true if the named feature flag is enabled (global check).
+// When Unleash is not configured, returns false. Safe to call from any handler.
+func FeatureEnabled(flagName string) bool {
+	return featureflags.IsEnabled(flagName)
+}
+
+// FeatureEnabledForRequest returns true if the flag is enabled for the current request.
+// Uses forwarded user ID, client IP, and optional session for Unleash strategies (e.g. userId, remoteAddress).
+// When Unleash is not configured, returns false.
+func FeatureEnabledForRequest(c *gin.Context, flagName string) bool {
+	userID := c.GetString("userID")
+	sessionID := c.GetHeader("X-Session-Id") // optional
+	remoteAddr := c.ClientIP()
+	return featureflags.IsEnabledWithContext(flagName, userID, sessionID, remoteAddr)
+}