Skip to content

About

This is a Spring Boot starter that integrates OpenFeature, an open standard for feature flag management.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Latest commit

 

History

638 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Spring Boot OpenFeature

Build StatusBuild Status Coveralls

Maven Central Maven Snapshot

This is a Spring Boot starter that integrates OpenFeature, an open standard for feature flag management. Add one starter dependency, set a few spring.openfeature.* properties, and feature flags work in your application — no manual wiring of the OpenFeature SDK.

Features

  • Auto-Configuration — a ready-made dev.openfeature.sdk.Client bean, created as soon as a FeatureProvider bean is on the context.
  • Declarative Flags — the @ToggleOnFlag annotation gates method execution on a flag, with SpEL evaluation context and an orElse fallback method.
  • Health Indicator — a Spring Boot Actuator health check for the configured flag provider.
  • Provider Starters — one starter module per feature-flag backend, each configured under its own spring.openfeature.<provider>.* prefix.
  • Extension Points — ClientCustomizer, OpenFeatureAPICustomizer, and per-provider customizers let you tweak the auto-configured beans.
  • Security Integration — when Spring Security is on the classpath, userId and authorities are automatically added to every flag evaluation context.

Prerequisites

  • Java 17
  • Maven (the repository ships the Maven wrapper ./mvnw)

Getting Started

1. Add the Dependency

Every provider has its own starter. For Unleash:

Maven

<project>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.iromu.openfeature</groupId>
            <artifactId>spring-boot-starter-openfeature-unleash</artifactId>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.iromu.openfeature</groupId>
                <artifactId>spring-boot-openfeature-dependencies</artifactId>
                <version>${spring-boot-openfeature.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

Gradle

dependencyManagement {
    imports {
        mavenBom "org.iromu.openfeature:spring-boot-openfeature-dependencies:${springBootOpenFeatureVersion}"
    }
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.iromu.openfeature:spring-boot-starter-openfeature-unleash'
}

The BOM (spring-boot-openfeature-dependencies) pins the OpenFeature SDK and every provider library version, so you do not need to declare versions yourself.

2. Configure the Provider

Configure the provider under its spring.openfeature.<provider>.* prefix in application.yml (or application.properties). For example, Unleash:

spring:
  application:
    name: UnleashApplication
  openfeature:
    unleash:
      app-name: ${spring.application.name}
      environment: development
      unleash-api: http://unleash-instance:4242/api/
      unleash-token: 'default:development.your-api-key'

Each provider starter also accepts an enabled property (spring.openfeature.<provider>.enabled) to switch its auto-configuration on or off. See the provider table below for the full set of options per provider.

3. Use the Client

Inject the auto-configured Client and evaluate flags:

import dev.openfeature.sdk.Client;
import dev.openfeature.sdk.ImmutableContext;
import dev.openfeature.sdk.Value;

@RestController
@RequestMapping("/feature")
public class FeatureController {

    private final Client client;

    public FeatureController(Client client) {
        this.client = client;
    }

    @GetMapping("{name}")
    public Boolean feature(@PathVariable("name") final String name) {
        return this.client.getBooleanValue(name, false);
    }

    @GetMapping("user/{id}")
    public Boolean featureOnUserId(@PathVariable("id") final String id) {
        return this.client.getBooleanValue("users-flag", false,
                new ImmutableContext(Map.of("userId", new Value(id))));
    }
}

4. Use @ToggleOnFlag

The @ToggleOnFlag annotation (from org.iromu.openfeature.boot.aop) conditionally executes a method based on a flag. attributes accepts a SpEL map that is evaluated into the flag evaluation context, and orElse names a fallback method invoked when the flag evaluates to false.

Given an Unleash flag defined as:

{
  "name": "users-flag",
  "enabled": true,
  "strategies": [
    {
      "name": "userWithId",
      "parameters": {
        "userIds": "111,234"
      }
    }
  ]
}
import org.iromu.openfeature.boot.aop.ToggleOnFlag;

@RestController
@RequestMapping("/feature")
public class UserController {

    @GetMapping("annotated/user/{id}")
    @ToggleOnFlag(key = "users-flag", attributes = "{'userId': #id}", orElse = "featureOnUserIdDisabled")
    public String featureOnUserIdAnnotated(@PathVariable("id") final String id) {
        return "User allowed";
    }

    public String featureOnUserIdDisabled(final String id) {
        return "User not allowed";
    }
}

OpenFeature Providers

Each backend has its own starter module under org.iromu.openfeature:

Provider Version Starter artifact Documentation
Ageris 0.7.0 spring-boot-starter-openfeature-ageris README
ConfigCat 0.2.1 spring-boot-starter-openfeature-configcat README
ConfigDirector 1.4.0 spring-boot-starter-openfeature-configdirector README
Confidence 0.7.0 spring-boot-starter-openfeature-confidence README
Datadog 1.68.1 spring-boot-starter-openfeature-datadog README
DevCycle 2.10.0 spring-boot-starter-openfeature-devcycle README
Env Var 0.0.12 spring-boot-starter-openfeature-envvar README
FeatBit 1.0.0 spring-boot-starter-openfeature-featbit README
flagd 0.15.0 spring-boot-starter-openfeature-flagd README
Flagsmith 0.0.13 spring-boot-starter-openfeature-flagsmith README
Flipt 0.1.4 spring-boot-starter-openfeature-flipt README
Featureflip 0.2.1 spring-boot-starter-openfeature-featureflip README
GCP 0.0.2 spring-boot-starter-openfeature-gcp README
GoFeatureFlag 2.0.2 spring-boot-starter-openfeature-gofeatureflag README
GrowthBook 0.0.2 spring-boot-starter-openfeature-growthbook README
JsonLogic 1.3.0 spring-boot-starter-openfeature-jsonlogic README
Kameleoon 0.0.1 spring-boot-starter-openfeature-kameleoon README
LaunchDarkly 2.0.0 spring-boot-starter-openfeature-launchdarkly README
Mixpanel 0.2.0 spring-boot-starter-openfeature-mixpanel README
Multi-Provider 0.0.3 spring-boot-starter-openfeature-multiprovider README
OFREP 0.0.2 spring-boot-starter-openfeature-ofrep README
Optimizely 1.0.0 spring-boot-starter-openfeature-optimizely README
Octopus Deploy 2.1.0 spring-boot-starter-openfeature-octopusdeploy README
Statsig 0.2.1 spring-boot-starter-openfeature-statsig README
Split 1.2.2 spring-boot-starter-openfeature-split README
Superposition 0.118.2 spring-boot-starter-openfeature-superposition README
Unleash 0.1.3-alpha spring-boot-starter-openfeature-unleash README
VWO 1.0.0 spring-boot-starter-openfeature-vwo README
CloudBees 1.0.1 spring-boot-starter-openfeature-cloudbees README

To switch providers, replace the starter dependency and update the configuration as described in the provider's README.

Example Applications

The examples/ directory contains thirty runnable applications (built with the examples profile or as a separate reactor; they resolve the starters from the local build or the snapshot repository):

  • unleash-simple — port 9998; in-memory fake Unleash provider (default, no external server needed).
  • unleash-advanced — port 9999; mocked Unleash API server with a local features.json backup file.
  • one <provider>-simple per remaining provider (28 apps: ageris-simple, cloudbees-simple, confidence-simple, configcat-simple, configdirector-simple, datadog-simple, devcycle-simple, featbit-simple, featureflip-simple, flipt-simple, flagd-simple, flagsmith-simple, gcp-simple, gofeatureflag-simple, growthbook-simple, jsonlogic-simple, kameleoon-simple, launchdarkly-simple, mixpanel-simple, multiprovider-simple, octopusdeploy-simple, ofrep-simple, optimizely-simple, split-simple, statsig-simple, superposition-simple, vwo-simple) — port 9999; each boots credential-free with an in-memory fake provider (--example.fake-provider=true).
$ cd examples
$ mvn clean package

Then run the packaged application, for example:

$ java -jar unleash-simple/target/unleash-simple-${revision}.jar
$ java -jar gcp-simple/target/gcp-simple-${revision}.jar --example.fake-provider=true

Try the endpoints (unleash-simple on 9998):

$ curl http://localhost:9998/feature/random-boolean-flag
$ curl http://localhost:9998/feature/greet/world

The "simple" examples all expose the same endpoints on their respective ports:

$ curl http://localhost:9999/feature/random-boolean-flag
$ curl http://localhost:9999/feature/toggle/random-boolean-flag
$ curl http://localhost:9999/feature/greet/world

And with unleash-advanced running on 9999:

$ curl http://localhost:9999/feature/annotated/user/111

Building the Project

All commands use the Maven wrapper from the repository root:

# Full build (compile, checkstyle, formatting, tests, coverage)
$ ./mvnw clean verify

# Skip tests
$ ./mvnw clean verify -DskipTests

# Build a single module and its dependencies
$ ./mvnw -pl spring-boot-starter-openfeature-unleash -am clean verify

Code style is enforced by Spring Java Format and Checkstyle, which run automatically during the validate phase.

Documentation

Design and engineering documents live under docs/:

Document Contents
architecture.md Module map, the provider → Client wiring flow, extension points, @ToggleOnFlag aspect, health and security integration
provider-starter-contract.md The shared auto-configuration contract every provider starter honors, per-provider deltas, and the checklist for adding a starter
quality-and-testing.md Test tiers, behavioral contracts, per-module JaCoCo coverage floors, CI posture and known gaps
dependency-management.md Where versions live, the BOM, the OpenFeature SDK ↔ provider lockstep rule, upgrade policy and blocked pins
backlog.md Unimplemented work: the blocked Featurevisor and Hyphen AI starters, the Unleash real-endpoint CI gate
dependency-versions.md Generated audit of every plugin and dependency pin against its latest release

Contributing

Contributions are welcome! See CONTRIBUTING.md for the full guide on reporting bugs, suggesting features, code style, testing, and the pull request process.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Resources

About

This is a Spring Boot starter that integrates OpenFeature, an open standard for feature flag management.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages