Tutorial

Installation

twrs requires Go 1.24+. Add it to your project:

go get gitlab.com/twrshq/twrs@latest

Quick start

Create a flags once, at startup, and share it across your application.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"gitlab.com/twrshq/twrs"
)

func main() {
	ctx := context.Background()

	f, err := twrs.New(twrs.Options{
		Path:           "flags.yaml",
		ReloadInterval: 10 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer f.Close()

	ok, err := f.Enabled(ctx, "new-checkout", "u_1842")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(ok)

	v, err := f.Variant(ctx, "search-ranking", "u_1842")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(v)
}

The flag file

Flags are declared in a YAML or JSON file. Each flag has a default value and an ordered list of rules; the first matching rule decides the value.

Keep the file in your repository and deploy it with your code, or point twrs at a path that another process updates.

Evaluating flags

Pass the flag name, an evaluation context and a default. The context carries the attributes your rules match on, such as the user id.

Evaluation never fails. Unknown flags and type mismatches return the default and are reported through the error hook.

Rollouts

A percentage rule hashes the flag name and a stable attribute, usually the user id, into a bucket from 0 to 99. Raising the percentage only adds users; nobody flips back and forth.