pbflags

pbflags

Protocol Buffer-based feature flags with type-safe code generation, multi-tier caching, and a never-throw guarantee.

Note: This project is a learning exercise and research exploration into protobuf-driven feature flag design. It was extracted from a production system to study the patterns independently. If you're building a real product and need feature flags, you probably want Flipt, OpenFeature, or Unleash instead. Those are battle-tested, well-supported, and have ecosystems around them. pbflags exists because we found the proto-as-source-of-truth pattern interesting and wanted to share it.

Overview

pbflags lets you define feature flags as protobuf messages and generates type-safe client code for Go and Java. Flags are the proto source of truth, the database is the runtime source of truth, and generated clients give you compile-time type safety at every call site.

For AI agents

If you are an AI agent integrating pbflags into a consumer project, start with docs/agent-setup.md. It is the shortest end-to-end setup path and avoids maintainer-only details from the rest of the docs.

Prerequisites

• Go 1.26+
• PostgreSQL (or Docker for docker compose up)
• Buf CLI

Quick Start

1. Define flags in proto

syntax = "proto3";
import "pbflags/options.proto";

enum Layer {
  option (pbflags.layers) = true;
  LAYER_UNSPECIFIED = 0;
  LAYER_GLOBAL = 1;
  LAYER_USER = 2;
}

message Notifications {
  option (pbflags.feature) = {
    id: "notifications"
    description: "Notification delivery controls"
    owner: "platform-team"
  };

  bool email_enabled = 1 [(pbflags.flag) = {
    description: "Enable email notifications"
    default: { bool_value: { value: true } }
    layer: "user"
  }];

  string digest_frequency = 2 [(pbflags.flag) = {
    description: "Digest email frequency"
    default: { string_value: { value: "daily" } }
  }];
}

2. Generate client code

Add pbflags to your buf.yaml and generate:

# buf.yaml
# deps:
#   - buf.build/spotlightgov/pbflags

go install github.com/SpotlightGOV/pbflags/cmd/protoc-gen-pbflags@latest
buf dep update
buf generate --template buf.gen.flags.yaml
buf build proto -o descriptors.pb

Example buf.gen.flags.yaml for Go:

version: v2
plugins:
  - local: protoc-gen-pbflags
    out: gen/flags
    strategy: all
    opt:
      - lang=go
      - package_prefix=github.com/yourorg/yourrepo/gen/flags
inputs:
  - directory: proto

3. Run the server

pbflags-admin --standalone \
  --descriptors=descriptors.pb \
  --database=postgres://user:pass@localhost:5432/mydb?sslmode=disable

This starts the admin UI on :9200 and the evaluator on :9201. Migrations, definition sync, and evaluation all happen in one process.

Or use Docker Compose:

docker compose -f docker/docker-compose.yml up

4. Use in your application

import (
  "net/http"

  "github.com/yourorg/yourrepo/gen/flags/layers"
  "github.com/yourorg/yourrepo/gen/flags/notificationsflags"
  "github.com/yourorg/yourrepo/gen/flags/v1/pbflagsv1connect"
)

evaluator := pbflagsv1connect.NewFlagEvaluatorServiceClient(
  http.DefaultClient,
  "http://localhost:9201",
)
notifications := notificationsflags.NewNotificationsFlagsClient(evaluator)

emailEnabled := notifications.EmailEnabled(ctx, layers.User("user-123"))  // bool
frequency := notifications.DigestFrequency(ctx)                            // string

Language Support

Documentation

As-built documentation lives in docs/. Design research and explorations live in research/.

License

MIT