nimbool

README

nimbool

Fast feature flag lookups for Go.

nimbool has a really small API, and expects callers to own flag IDs:

• define IDs with const + int
• load a JSON object keyed by those IDs
• choose the lookup mode that matches the flag semantics
• replace flags at runtime if needed

The payload is a JSON object with percentage values.

• 100 is always enabled
• 0 is always disabled
• values between 1 and 99 can be evaluated with two different lookup AB test modes

{
  "0": 100,
  "1": 0,
  "2": 25
}

Lookup modes

Enabled(id) is the fastest mode. Percentage flags are decided once per Replace, so reads are stable until the next payload is published. Good for operational rollouts when there is no user, account, device, session, or request key.

EnabledFor(id, key) is deterministic. It hashes the flag ID and caller-owned key into a bucket from 0 to 99, then compares that bucket with the stored percentage. Right mode for sticky AB tests, user, account, device, session, or request rollout.

EnabledRandom(id) evaluates percentages independently on every lookup. Right mode for non-sticky random distribution is explicitly wanted.

package main

import "github.com/berkayuckac/nimbool"

const (
	Checkout nimbool.ID = 1
	Search nimbool.ID = 2
	NewFlow nimbool.ID = 3
)

func main() {
	flags, err := nimbool.New([]byte(`{"1":100,"2":0,"3":25}`))
	// ... or load it from file, env variable, secret, or your app config flow.
	if err != nil {
		panic(err)
	}

	if flags.Enabled(Checkout) {
		// fast path
	}

	if flags.EnabledFor(NewFlow, "user-123") {
		// sticky keyed rollout
	}

	// ... or once again, replace it with a flow of your choice
	_ = flags.Replace([]byte(`{"1":0,"2":100,"3":25}`))
}

Benchmark

cpu: Apple M3 Pro (12C)
BenchmarkEnabled-12                      1000000000               0.4480 ns/op          0 B/op          0 allocs/op
BenchmarkEnabledMiss-12                  1000000000               0.5207 ns/op          0 B/op          0 allocs/op
BenchmarkEnabledNegativeID-12            1000000000               0.2521 ns/op          0 B/op          0 allocs/op
BenchmarkEnabledParallel-12              1000000000               0.3216 ns/op          0 B/op          0 allocs/op
BenchmarkEnabledProcessPercentage-12     1000000000               0.4173 ns/op          0 B/op          0 allocs/op
BenchmarkEnabledForPercentage-12          100000000              10.31 ns/op           0 B/op          0 allocs/op
BenchmarkEnabledRandomPercentage-12       234839155               5.115 ns/op          0 B/op          0 allocs/op
BenchmarkReplaceSmall-12                   907946              1308 ns/op            488 B/op         17 allocs/op
BenchmarkReplaceLarge-12                     6355            191631 ns/op          84912 B/op       1053 allocs/op
BenchmarkReplaceSparse-12                  86076             15051 ns/op          21760 B/op         82 allocs/op

License

MIT

Documentation

Overview

Package nimbool provides fast feature flag lookup from JSON payloads

Index

• type Flags
  • func New(payload []byte) (*Flags, error)
  • func (f *Flags) Enabled(id ID) bool
  • func (f *Flags) EnabledFor(id ID, key string) bool
  • func (f *Flags) EnabledRandom(id ID) bool
  • func (f *Flags) Replace(payload []byte) error
• type ID

Types

type Flags

type Flags struct {
	// contains filtered or unexported fields
}

Flags is the feature flag cache Hot-path reads use one atomic pointer load and an array lookup

func New

func New(payload []byte) (*Flags, error)

New creates a Flags cache from a JSON object

func (*Flags) Enabled

func (f *Flags) Enabled(id ID) bool

Enabled reports whether a given id is enabled in the active flag payload. Percentages between 1 and 99 are decided once per Replace, so this is the fastest lookup mode.

func (*Flags) EnabledFor

func (f *Flags) EnabledFor(id ID, key string) bool

EnabledFor reports whether a given id is enabled for key. Percentages between 1 and 99 use a stable hash of id and key, which is the right mode for sticky user, account, device, session, or request rollout.

func (*Flags) EnabledRandom

func (f *Flags) EnabledRandom(id ID) bool

EnabledRandom reports whether a given id is enabled in the active flag payload. Percentages between 1 and 99 are evaluated independently per lookup.

func (*Flags) Replace

func (f *Flags) Replace(payload []byte) error

Replace publishes a new flag payload.

type ID

type ID int

ID is the integer handle for a flag Callers own ID assignment, usually with const + int:

const (
	Checkout nimbool.ID = 1
	Search nimbool.ID = 2
)