flagnetic

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 22, 2026 License: Apache-2.0

README

Flagnetic

Self-hosted, open-source feature flags and experiments. One Go binary with an embedded web console; PostgreSQL is the only thing it needs.

Status: developer preview. Version 0.6 is the sixth release: try it, build against its SDKs, and tell us what breaks, but do not run it where an outage would hurt. The SDK API and the ruleset format only grow from 0.1 on, and upgrades only migrate forward, without data loss; the management API and the console may still change in 0.x, each change marked in the release notes. See what 0.x promises.

Why

The open-source flag products keep a paid tier, and the features a real team needs sit behind it: roles, SSO, audit log, approvals, environments, streaming, experiment analysis. Flagnetic ships all of it under Apache-2.0, with no cloud edition, no enterprise license and no feature gates. Ever.

What it contains

  • Flags of four types (boolean, string, number, JSON) in every environment, with targeting rules, segments (private ones included), percentage rollouts, prerequisites, overrides and a kill switch; revert, copy and compare between environments, history, and a tester that shows what a context is served, and why. Stale flags are listed with their reasons and sent as a weekly digest.
  • Experiments: a lifecycle of draft, running, stopped and archived, with a hypothesis, an owner, weights, a traffic allocation that only grows and a decision when it stops. A rule serves an experiment, SDKs record exposures explicitly, and an alias links an anonymous visitor to the user they sign up as. Exposures are rolled up into first exposures, daily counts and conflicts; the sample-ratio check raises alerts members acknowledge, silent failures and overdue experiments are flagged, and an assignment lookup and a hash uniformity check let you verify assignment in your own warehouse.
  • Governance: protected environments, where a change reaches SDKs only through a reviewed change request (flag configurations and definitions, segments, experiment transitions), with approval, rejection, scheduled application and revert; webhooks with signed deliveries, retries, test pings, redelivery and a delivery log; a stream of a project's changes that keeps the console current; and an audit log you can download as JSON Lines or CSV.
  • Access: roles and permissions per project, personal access tokens and project tokens with scopes, which cannot mint credentials or widen access (only a signed-in session does), an audit log of every change, local sign-in with lockout and throttling, members and invitations; a project can be deleted with everything in it.
  • Identity: an SMTP server for mailed invitations, password resets and notices of a disabled webhook subscription, in English and Russian; invitations into a project with a grant; OIDC and SAML auth providers, each vouching for its own email domains, with identity linking, group mappings that turn directory groups into roles, and SSO enforcement per email domain; SCIM provisioning and deprovisioning of members and groups from Entra ID, Okta or any SCIM 2.0 client; and a command-line break-glass that restores password sign-in.
  • Delivery to SDKs: server and client SDK keys per environment, with rotation and an overlap, revocation and allowed origins; the ruleset with conditional requests; the ruleset stream, which brings a change, a kill switch included, to a server SDK within 2 seconds; remote evaluation for client keys, which learn served values only; the events SDKs post, kept and rolled up under a retention you set, with the event volume and any gap retention left; the attributes SDKs send that the project has not declared; and the SDKs seen using each environment.
  • SDKs for Go, JavaScript and TypeScript, Dart and Flutter, Ruby and Python, with OpenFeature providers for Go, JavaScript, Ruby and Python, listed below. Evaluation happens in a server SDK, so a flag check costs no network call and the SDK keeps serving its last good ruleset if the server goes away.
  • Sinks: a project's durable, at-least-once copy of its raw events (exposures, aliases and evaluation summaries) in ClickHouse, S3-compatible object storage as JSON Lines or Parquet, or a signed webhook, in a documented export schema that only grows. A sink is tested before it is enabled and can send sample rows; its health, failure classes, dead letters and replay are in the console and the API, and a sink is flagged at risk before retention drops rows it has not delivered, with a gap recorded when it does.
  • Export and import: a project's configuration as one document, YAML or JSON, to keep in git, copy to another instance or show an auditor. An import creates a project, merges into one or replaces its configuration, whole or not at all, after a dry run that shows what it would change; it works from the console, the API and the command line. A Firebase Remote Config template is translated into flags and rules of one environment, and a demo project is included.
  • Operations: any number of identical replicas on one PostgreSQL, with no sticky sessions; Prometheus metrics on a listener of their own, loopback by default; secrets sealed to the row that holds them; a deprecated API operation announced with Deprecation and Sunset headers; a console in English and Russian covering all of the above; a Docker image for linux/amd64 and linux/arm64 with provenance and an SBOM; a Helm chart for Kubernetes, published to GHCR with a build attestation (see Running on Kubernetes).

Not there yet

Each arrives in a later release:

  • Analysis of an experiment's results: Flagnetic assigns units, records exposures and checks the sample ratio, and for now the metrics are read in your own warehouse, from the events a sink delivers there.

SDKs

Each SDK is published under the name flagnetic on its own registry, and the OpenFeature providers beside it. All speak the same protocol and work with every server from 0.1.0 on; see SDKs for modes, runtimes and how soon a change reaches each.

Language Install
Go go get github.com/azverinus/flagnetic/sdks/go, and go get github.com/azverinus/flagnetic/sdks/go-openfeature for OpenFeature
JavaScript and TypeScript: Node, browsers, React npm install flagnetic
Dart dart pub add flagnetic
Flutter flutter pub add flagnetic_flutter
Ruby bundle add flagnetic, and bundle add flagnetic-openfeature for OpenFeature
Python pip install flagnetic, and pip install 'flagnetic[openfeature]' for OpenFeature

Quick start

With Docker:

git clone https://github.com/azverinus/flagnetic.git && cd flagnetic/deploy
echo "FLAGNETIC_SECRET_KEY=$(openssl rand -base64 32)" > .env   # once; keep this file
docker compose up -d

This runs PostgreSQL, applies the migrations and starts the server on http://localhost:8080. Create the first instance admin, then sign in with the email and the password it prints:

docker compose exec flagnetic flagnetic admin bootstrap --email you@example.com

A first flag in ten minutes goes on from here to a flag evaluated by the Go or JavaScript SDK, and changed while it runs. Or import the demo project to look around, add an SDK key to one of its environments, and follow the SDK for your language.

Documentation

Read it as a site with search and the API reference at https://azverinus.github.io/flagnetic/; the pages below are the same Markdown.

Principles

  • PostgreSQL is the only required dependency; everything else is an optional integration.
  • Flag checks are free; the platform going down is not an incident.
  • Assignment is deterministic; exposure is an explicit call, separate from evaluation.
  • Contracts are versioned from the first release, because a mobile app in a store is served for years.
  • Everything in the console is available through the API.

Contributing

Read CONTRIBUTING.md and ARCHITECTURE.md. Security issues: see SECURITY.md.

License

Apache-2.0.

Directories

Path Synopsis
cmd
flagnetic command
Command flagnetic is the Flagnetic server.
Command flagnetic is the Flagnetic server.
eval module
internal
app
Package app is the root of the application layer: one subpackage per bounded context, holding its command and query handlers.
Package app is the root of the application layer: one subpackage per bounded context, holding its command and query handlers.
app/access
Package access holds the use cases of the access context: members, the instance admin, API tokens and the authentication of their callers.
Package access holds the use cases of the access context: members, the instance admin, API tokens and the authentication of their callers.
app/delivery
Package delivery holds the use cases of the delivery context: moving an environment's ruleset version on when a write changes what its SDKs receive, evaluating its ruleset for a context to explain what the context is served, and serving the SDKs themselves: their keys and the authentication of a request by one, remote evaluation, the ruleset and its stream, the attributes discovered in the contexts evaluated, and the inventory of the SDKs seen.
Package delivery holds the use cases of the delivery context: moving an environment's ruleset version on when a write changes what its SDKs receive, evaluating its ruleset for a context to explain what the context is served, and serving the SDKs themselves: their keys and the authentication of a request by one, remote evaluation, the ruleset and its stream, the attributes discovered in the contexts evaluated, and the inventory of the SDKs seen.
app/events
Package events holds the use cases of the events context: ingest of the events SDKs post.
Package events holds the use cases of the events context: ingest of the events SDKs post.
app/experiments
Package experiments holds the use cases of the experiments context.
Package experiments holds the use cases of the experiments context.
app/flags
Package flags holds the use cases of the flags context: flags, their configuration in each environment, and segments.
Package flags holds the use cases of the flags context: flags, their configuration in each environment, and segments.
app/governance
Package governance holds the use cases of the governance context: recording the audit entries of every context and reading the audit log.
Package governance holds the use cases of the governance context: recording the audit entries of every context and reading the audit log.
app/identity
Package identity holds the use cases of the identity context: the auth providers an instance admin configures and, as they arrive, the sign-ins, identities and directory provisioning built on them.
Package identity holds the use cases of the identity context: the auth providers an instance admin configures and, as they arrive, the sign-ins, identities and directory provisioning built on them.
app/sinks
Package sinks holds the use cases of a project's sinks: the resource a maintainer creates, reads, edits and deletes, whose credentials are sealed and never read back.
Package sinks holds the use cases of a project's sinks: the resource a maintainer creates, reads, edits and deletes, whose credentials are sealed and never read back.
app/transfer
Package transfer holds the use cases of the transfer context: a project's configuration leaving the platform as a project document.
Package transfer holds the use cases of the transfer context: a project's configuration leaving the platform as a project document.
app/workspace
Package workspace holds the use cases of the workspace context: projects, their environments, unit types and attributes.
Package workspace holds the use cases of the workspace context: projects, their environments, unit types and attributes.
domain
Package domain is the root of the domain layer: one subpackage per bounded context, holding its entities, value objects and invariants.
Package domain is the root of the domain layer: one subpackage per bounded context, holding its entities, value objects and invariants.
domain/access
Package access is the domain of who may do what: members and the instance admin, API tokens and their scopes, the permission catalog, the built-in roles and how a caller is judged against what an operation requires.
Package access is the domain of who may do what: members and the instance admin, API tokens and their scopes, the permission catalog, the built-in roles and how a caller is judged against what an operation requires.
domain/delivery
Package delivery is the domain of what an environment's SDKs receive: the ruleset materialized from its flags, segments and declarations, and the evaluation of it that explains what a context is served.
Package delivery is the domain of what an environment's SDKs receive: the ruleset materialized from its flags, segments and declarations, and the evaluation of it that explains what a context is served.
domain/events
Package events is the domain of the events context: the events SDKs post, how each is judged on its own, and how an exposure is judged against the experiment it names.
Package events is the domain of the events context: the events SDKs post, how each is judged on its own, and how an exposure is judged against the experiment it names.
domain/experiments
Package experiments is the domain of experiments: a time-boxed comparison of variations of one flag on a declared unit type, with a hypothesis, an owner, weights, a traffic allocation and two public salts.
Package experiments is the domain of experiments: a time-boxed comparison of variations of one flag on a declared unit type, with a hypothesis, an owner, weights, a traffic allocation and two public salts.
domain/flags
Package flags is the domain of what a project serves: flags with their definition and variations, their configuration in each environment, and the segments their rules target.
Package flags is the domain of what a project serves: flags with their definition and variations, their configuration in each environment, and the segments their rules target.
domain/governance
Package governance is the domain of how changes are governed: the audit entry (who changed what, when, from which value to which), change requests, the events that changes cause, webhook subscriptions and their deliveries, and the notices of the change stream.
Package governance is the domain of how changes are governed: the audit entry (who changed what, when, from which value to which), change requests, the events that changes cause, webhook subscriptions and their deliveries, and the notices of the change stream.
domain/identity
Package identity holds the rules of the integrations that reach outside the instance to know who a person is: the auth providers an instance admin configures, and, as they arrive, the identities, sign-in attempts and directory provisioning built on them.
Package identity holds the rules of the integrations that reach outside the instance to know who a person is: the auth providers an instance admin configures, and, as they arrive, the identities, sign-in attempts and directory provisioning built on them.
domain/sinks
Package sinks holds a project's sinks: the standing request to copy its raw events to a ClickHouse database, an S3-compatible bucket or a signed webhook.
Package sinks holds a project's sinks: the standing request to copy its raw events to a ClickHouse database, an S3-compatible bucket or a signed webhook.
domain/transfer
Package transfer is the domain of moving a project's configuration in and out of the platform as one project document: the document's types, its byte-stable encodings in JSON and YAML, and its strict decoding.
Package transfer is the domain of moving a project's configuration in and out of the platform as one project document: the document's types, its byte-stable encodings in JSON and YAML, and its strict decoding.
domain/transfer/firebase
Package firebase translates a Firebase Remote Config template into the flags, rules and attributes to merge into one environment: parameters become flags, conditional values become rules, and everything the translation cannot reproduce becomes a coded warning pointing into the template.
Package firebase translates a Firebase Remote Config template into the flags, rules and attributes to merge into one environment: parameters become flags, conditional values become rules, and everything the translation cannot reproduce becomes a coded warning pointing into the template.
domain/workspace
Package workspace is the domain of where flags live: projects, their environments, and the unit types and attributes their targeting refers to.
Package workspace is the domain of where flags live: projects, their environments, and the unit types and attributes their targeting refers to.
infra
Package infra is the root of the infrastructure layer.
Package infra is the root of the infrastructure layer.
infra/compose
Package compose assembles a replica: it builds the application's handlers on their PostgreSQL and other outbound adapters and mounts the APIs on the edge.
Package compose assembles a replica: it builds the application's handlers on their PostgreSQL and other outbound adapters and mounts the APIs on the edge.
infra/config
Package config is the server's configuration: one table declares every setting, and the loader, the keys of the configuration file and the public reference (docs/configuration.md) are all derived from it, so the reference cannot fall behind what the server reads.
Package config is the server's configuration: one table declares every setting, and the loader, the keys of the configuration file and the public reference (docs/configuration.md) are all derived from it, so the reference cannot fall behind what the server reads.
infra/in/cli
Package cli is the flagnetic command line.
Package cli is the flagnetic command line.
infra/in/http
Package http is the server's HTTP edge: the public handler with its health and readiness probes, onto which the APIs and the console are mounted.
Package http is the server's HTTP edge: the public handler with its health and readiness probes, onto which the APIs and the console are mounted.
infra/in/http/console
Package console serves the web console the binary embeds: the build of web/apps/console, or a placeholder page when the binary was built without it, so `go build` never needs Node.
Package console serves the web console the binary embeds: the build of web/apps/console, or a placeholder page when the binary was built without it, so `go build` never needs Node.
infra/in/http/deprecation
Package deprecation announces deprecated operations on the wire.
Package deprecation announces deprecated operations on the wire.
infra/in/http/management
Package management provides primitives to interact with the openapi HTTP API.
Package management provides primitives to interact with the openapi HTTP API.
infra/in/http/management/operations
Package operations reads what each operation of the management API requires from its OpenAPI document, and holds the table generated from it that the permission seam reads.
Package operations reads what each operation of the management API requires from its OpenAPI document, and holds the table generated from it that the permission seam reads.
infra/in/http/scim
Package scim provides primitives to interact with the openapi HTTP API.
Package scim provides primitives to interact with the openapi HTTP API.
infra/in/http/sdk
Package sdk provides primitives to interact with the openapi HTTP API.
Package sdk provides primitives to interact with the openapi HTTP API.
infra/in/http/sso
Package sso is the browser edge of single sign-on: the addresses a browser is sent through to sign in at an auth provider, outside the management API because every step is a navigation, not a call.
Package sso is the browser edge of single sign-on: the addresses a browser is sent through to sign in at an auth provider, outside the management API because every step is a navigation, not a call.
infra/in/worker
Package worker runs a replica's background work in rounds.
Package worker runs a replica's background work in rounds.
infra/metrics
Package metrics is the replica's Prometheus registry and the listener that serves it.
Package metrics is the replica's Prometheus registry and the listener that serves it.
infra/out/idphttp
Package idphttp is the HTTP client every request to an identity provider is made with, whatever the protocol it speaks.
Package idphttp is the HTTP client every request to an identity provider is made with, whatever the protocol it speaks.
infra/out/mail
Package mail is the outbound mail adapter: the templates every kind of mail is written from, in every language, and the SMTP sender.
Package mail is the outbound mail adapter: the templates every kind of mail is written from, in every language, and the SMTP sender.
infra/out/oidc
Package oidc is the outbound adapter to OpenID Connect providers, built on go-oidc.
Package oidc is the outbound adapter to OpenID Connect providers, built on go-oidc.
infra/out/password
Package password hashes members' passwords with argon2id.
Package password hashes members' passwords with argon2id.
infra/out/postgres
Package postgres is the server's PostgreSQL: the connection pool, the check that the server is a supported version, and the schema migrations embedded in the binary.
Package postgres is the server's PostgreSQL: the connection pool, the check that the server is a supported version, and the schema migrations embedded in the binary.
infra/out/postgres/access
Package access is the PostgreSQL repository of the access context: members, API tokens and sessions.
Package access is the PostgreSQL repository of the access context: members, API tokens and sessions.
infra/out/postgres/delivery
Package delivery is the PostgreSQL repository of the delivery context: for now, the ruleset version of each environment.
Package delivery is the PostgreSQL repository of the delivery context: for now, the ruleset version of each environment.
infra/out/postgres/events
Package events is the PostgreSQL repository of the events context: the raw events SDKs post and the tables that keep them apart from retries.
Package events is the PostgreSQL repository of the events context: the raw events SDKs post and the tables that keep them apart from retries.
infra/out/postgres/experiments
Package experiments is the PostgreSQL repository of the experiments context.
Package experiments is the PostgreSQL repository of the experiments context.
infra/out/postgres/flags
Package flags is the PostgreSQL repository of the flags context: flags, their configuration in each environment, and segments.
Package flags is the PostgreSQL repository of the flags context: flags, their configuration in each environment, and segments.
infra/out/postgres/governance
Package governance is the PostgreSQL repository of the governance context: the audit log, change requests, webhook subscriptions with their outbox and deliveries, the change stream and stale-flag digests.
Package governance is the PostgreSQL repository of the governance context: the audit log, change requests, webhook subscriptions with their outbox and deliveries, the change stream and stale-flag digests.
infra/out/postgres/identity
Package identity is the PostgreSQL repository of the identity context: auth providers.
Package identity is the PostgreSQL repository of the identity context: auth providers.
infra/out/postgres/projectrow
Package projectrow records, for the life of a transaction, the projects whose row it locked FOR NO KEY UPDATE, the lock every write of a project takes so that the project's writes run one at a time.
Package projectrow records, for the life of a transaction, the projects whose row it locked FOR NO KEY UPDATE, the lock every write of a project takes so that the project's writes run one at a time.
infra/out/postgres/sinks
Package sinks is the PostgreSQL repository of a project's sinks.
Package sinks is the PostgreSQL repository of a project's sinks.
infra/out/postgres/workspace
Package workspace is the PostgreSQL repository of the workspace context: projects, their environments, unit types and attributes.
Package workspace is the PostgreSQL repository of the workspace context: projects, their environments, unit types and attributes.
infra/out/saml
Package saml is the outbound adapter to SAML identity providers: the instance as a service provider, built on gosaml2 and goxmldsig.
Package saml is the outbound adapter to SAML identity providers: the instance as a service provider, built on gosaml2 and goxmldsig.
infra/out/sinks
Package sinks makes the HTTP calls of sinks: the clients each kind of target is called with, guarded by kind, and the reduction of whatever a target answers to a failure class.
Package sinks makes the HTTP calls of sinks: the clients each kind of target is called with, guarded by kind, and the reduction of whatever a target answers to a failure class.
infra/out/testclock
Package testclock is the test-only clock of FLAGNETIC_TEST_CLOCK_FILE: the wall clock moved ahead by the duration a file holds, such as "25h".
Package testclock is the test-only clock of FLAGNETIC_TEST_CLOCK_FILE: the wall clock moved ahead by the duration a file holds, such as "25h".
infra/out/webhook
Package webhook makes the HTTP calls of webhook deliveries.
Package webhook makes the HTTP calls of webhook deliveries.
pkg/buildinfo
Package buildinfo reports the version the running binary was built from.
Package buildinfo reports the version the running binary was built from.
pkg/pglisten
Package pglisten keeps a process listening on a PostgreSQL notification channel, and tells it when it is not.
Package pglisten keeps a process listening on a PostgreSQL notification channel, and tells it when it is not.
pkg/pgtest
Package pgtest gives a test package a real PostgreSQL, so that no test fakes the database.
Package pgtest gives a test package a real PostgreSQL, so that no test fakes the database.
pkg/pgxtx
Package pgxtx carries a PostgreSQL transaction in a context, so the code that owns a unit of work begins it and the code that runs statements finds it, without the transaction appearing in any signature in between.
Package pgxtx carries a PostgreSQL transaction in a context, so the code that owns a unit of work begins it and the code that runs statements finds it, without the transaction appearing in any signature in between.
pkg/safego
Package safego runs functions so that a panic in one is recovered, logged with its stack and counted, rather than crashing the process: one poison input must not take every process that reads it down with it.
Package safego runs functions so that a panic in one is recovered, logged with its stack and counted, rather than crashing the process: one poison input must not take every process that reads it down with it.
shared
Package shared is the root of the kernel every layer may import: error kinds, identifiers, the clock and secret values.
Package shared is the root of the kernel every layer may import: error kinds, identifiers, the clock and secret values.
shared/clock
Package clock is the one time source of the server.
Package clock is the one time source of the server.
shared/errors
Package errors is the one way domain and application code says what went wrong: an error of a fixed kind with a stable code.
Package errors is the one way domain and application code says what went wrong: an error of a fixed kind with a stable code.
shared/id
Package id is the identifiers of every entity: UUIDv7 values minted by the application before the domain sees them, typed per entity.
Package id is the identifiers of every entity: UUIDv7 values minted by the application before the domain sees them, typed per entity.
shared/precondition
Package precondition is how a write names the version of the entity it was based on, and how that version is judged against the stored one.
Package precondition is how a write names the version of the entity it was based on, and how that version is judged against the stored one.
shared/protection
Package protection carries, in a context, which protected environments a write may change without a change request, as the context carries the write's transaction.
Package protection carries, in a context, which protected environments a write may change without a change request, as the context carries the write's transaction.
shared/secret
Package secret holds values that must never reach a log: passwords, keys, tokens.
Package secret holds values that must never reach a log: passwords, keys, tokens.
shared/subnet
Package subnet groups client addresses the way limits count them.
Package subnet groups client addresses the way limits count them.
shared/text
Package text is the one rule for the text a client sends: it holds no control character other than a tab or a line break.
Package text is the one rule for the text a client sends: it holds no control character other than a tab or a line break.
testkit
Package testkit is the Flagnetic test kit: a real, migrated PostgreSQL for every test package, and the fake clock, deterministic identifiers and log sink a test hands to the code under test.
Package testkit is the Flagnetic test kit: a real, migrated PostgreSQL for every test package, and the fake clock, deterministic identifiers and log sink a test hands to the code under test.
sdks
python/scripts/_unicode_tables command
Command _unicode_tables writes src/flagnetic/_eval/_re2/unicode_tables.py from the Go standard library's unicode package, which the reference evaluator's regexp package uses: the simple case folding that (?i) applies, and the categories and scripts \p accepts with the characters that fold into each.
Command _unicode_tables writes src/flagnetic/_eval/_re2/unicode_tables.py from the Go standard library's unicode package, which the reference evaluator's regexp package uses: the simple case folding that (?i) applies, and the categories and scripts \p accepts with the characters that fold into each.
ruby/script/_unicode_tables command
Command _unicode_tables writes lib/flagnetic/eval/unicode_tables.rb from the Go standard library's unicode package, which the reference evaluator's regexp package uses: the simple case folding orbits (?i) folds with, and the category and script names \p accepts.
Command _unicode_tables writes lib/flagnetic/eval/unicode_tables.rb from the Go standard library's unicode package, which the reference evaluator's regexp package uses: the simple case folding orbits (?i) folds with, and the category and script names \p accepts.
go module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL