features

Forge Features: feature flags for Go services

Forge Features is the feature flag extension for Forge, the Go backend framework. You define boolean, string, number and JSON flags in Go, target them at users by ID, email, country, group or any custom attribute, and roll a feature out to a fixed percentage of users with stable hashing, so the same user gets the same answer on every request. Flags are evaluated in process by the local provider. Settings for LaunchDarkly, Unleash, Flagsmith and PostHog exist in the config, but those providers aren't wired up yet: see Providers.

Documentation · Quick start · Features · Evaluating flags · Targeting and rollouts · Providers · Configuration · FAQ

Quick start

You need Go 1.26 or later. Add Forge and the extension:

go get github.com/xraph/forge@latest
go get github.com/xraph/forge/extensions/features@latest

Save this as main.go. It defines two flags: a checkout switch that beta users always get and a quarter of everyone else gets, and a theme string that changes for one country.

package main

import (
	"log"
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/extensions/features"
)

func main() {
	app := forge.NewApp(forge.AppConfig{
		Name:        "flags-demo",
		HTTPAddress: ":8080",
		Extensions: []forge.Extension{
			features.NewExtension(
				features.WithLocalFlags(map[string]features.FlagConfig{
					"new-checkout": {
						Key:     "new-checkout",
						Type:    "boolean",
						Enabled: true,
						Targeting: []features.TargetingRule{
							{Attribute: "group", Operator: "in", Values: []string{"beta"}, Value: true},
						},
						Rollout: &features.RolloutConfig{Percentage: 25},
					},
					"checkout-theme": {
						Key:   "checkout-theme",
						Type:  "string",
						Value: "classic",
						Targeting: []features.TargetingRule{
							{Attribute: "country", Operator: "equals", Values: []string{"DE"}, Value: "compact"},
						},
					},
				}),
			),
		},
	})

	err := app.Router().GET("/checkout", func(ctx forge.Context) error {
		flags, err := features.Get(app.Container())
		if err != nil {
			return err
		}

		user := features.NewUserContext(ctx.QueryDefault("user", "anonymous")).
			WithCountry(ctx.Query("country"))
		if ctx.Query("beta") == "true" {
			user = user.WithGroups([]string{"beta"})
		}

		return ctx.JSON(http.StatusOK, map[string]any{
			"user":         user.UserID,
			"new_checkout": flags.IsEnabled(ctx.Context(), "new-checkout", user),
			"theme":        flags.GetString(ctx.Context(), "checkout-theme", user, "classic"),
		})
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

Run it and ask as a few different users:

go mod tidy
go run .

curl "http://localhost:8080/checkout?user=alice"
# {"new_checkout":false,"theme":"classic","user":"alice"}
curl "http://localhost:8080/checkout?user=bob&beta=true&country=DE"
# {"new_checkout":true,"theme":"compact","user":"bob"}

Bob is in the beta group, so the targeting rule turns the checkout on for him, and his country picks the compact theme. Alice falls through to the 25% rollout, and her user ID hashes outside it. Try a dozen user IDs and roughly a quarter of them come back true. Ask again as Alice and you'll get the same answer every time.

Features

Evaluating flags

Get the service from the container with features.Get(container), features.GetFromApp(app) or their Must versions, or take it as a constructor parameter:

type Checkout struct {
	flags *features.Service
}

func NewCheckout(flags *features.Service) *Checkout {
	return &Checkout{flags: flags}
}

// After forge.NewApp:
err := forge.Provide(app.Container(), NewCheckout)

Every evaluation takes a *features.UserContext. Build one with NewUserContext and chain whatever you know about the caller:

user := features.NewUserContext("user-42").
	WithEmail("ada@example.com").
	WithGroups([]string{"beta", "staff"}).
	WithAttribute("plan", "pro")

limit := flags.GetInt(ctx, "upload-limit-mb", user, 10)
ratio := flags.GetFloat(ctx, "sample-rate", user, 0.1)
layout := flags.GetJSON(ctx, "dashboard-layout", user, map[string]any{"columns": 2})

all, err := flags.GetAllFlags(ctx, user)

WithName, WithIP and WithCountry fill the other built-in fields. You can pass nil as the user context too, and then targeting and rollouts are skipped and you get the flag's base value.

Types are matched exactly. GetInt only returns a value you stored as a Go int and GetFloat only one you stored as a float64, so if you store 50 in a flag and then read it with GetFloat, the type assertion fails quietly and you get your default back with no warning in the logs.

Targeting and rollouts

For a defined flag, the local provider goes through these steps in order and stops at the first one that gives an answer:

1. Each targeting rule, in the order you listed them. If a rule matches the user and its Value has the type you asked for, that value wins.
2. For boolean flags with a Rollout, the user's bucket. A user inside the percentage gets Enabled, a user outside it gets the opposite.
3. The flag's own value: Enabled for booleans, Value for everything else.

A flag you never defined falls back to WithDefaultFlags, then to the default you passed to the getter.

Rollouts hash the attribute named in RolloutConfig.Attribute (user_id when empty, or email, or a custom string attribute) with MD5 into one of 100 buckets. A user with an empty value for that attribute is always outside the rollout. Percentage of 0 or less puts nobody in, and 100 or more puts everybody in.

So a boolean flag with Enabled: true and Percentage: 25 is on for about a quarter of your users. Flip it to Enabled: false and the same quarter now gets false while everyone else gets true, which is rarely what you meant.

Providers

The providers package has client code for the four remote services, but the extension doesn't call it yet. Pick one today and registration fails, so your app won't start.

Configuration

Configure the extension with options on features.NewExtension, or under extensions.features (falling back to features) in your config file. Your options win over the file and the file wins over the defaults. Flags can live in YAML under local.flags, value included. Write a number the way your getter expects it: 50 decodes as int and 50.0 as float64. WithRequireConfig(true) turns a missing section into a startup error.

DefaultConfig() gives you Enabled: true, Provider: "local", a 30-second refresh interval, and empty flag and default maps.

A FlagConfig has Key, Name, Description, Type (boolean, string, number or json), Enabled, Value, Targeting and Rollout. Type matters for GetAllFlags: it decides which getter is used for each flag, and anything other than the first three returns the raw Value.

Documentation

Where the docs pages and this README disagree about providers or YAML config, this README follows the code.

FAQ

How do I add feature flags to a Go API?

Add features.NewExtension(features.WithLocalFlags(...)) to your Forge app's Extensions, then call IsEnabled or one of the typed getters with a UserContext. The quick start is a complete program.

How do percentage rollouts stay consistent per user in Go?

The provider hashes the user's ID (or the attribute you name) with MD5 and takes the result modulo 100. The same ID always lands in the same bucket, so a user doesn't flicker between on and off as you call the flag again, and raising the percentage only adds users.

Can I use LaunchDarkly, Unleash, Flagsmith or PostHog with Forge?

Not through this extension yet. The options exist, but choosing any of those providers makes startup fail until they're wired in. Use the local provider for now.

Can I change flags without restarting?

Not through the public API. Local flags are fixed when you build the extension, and the service doesn't expose a way to edit them, so you restart with new definitions or keep values you need to change at runtime somewhere else.

What happens if a flag is missing?

You get a default, never an error. A missing flag falls back to WithDefaultFlags, and then to the default you pass to the getter. IsEnabled uses false.

Contributing

Features is its own Go module in the Forge repository. Test it from its directory the way CI does:

cd extensions/features
GOWORK=off go build ./...
GOWORK=off go vet ./...
GOWORK=off go test -short -count=1 ./...
golangci-lint run ./...

AGENTS.md has the pinned lint version and the repository conventions. Commits follow Conventional Commits, for example feat(features): ....

License

Forge Features is part of Forge and is available under the Apache License 2.0.