Quarkus - Unleash

Unleash is a feature toggle system, that gives you a great overview of all feature toggles across all your applications and services. Quarkus Unleash extension is client for Unleash.

Installation

If you want to use this extension, you need to add the quarkiverse-unleash extension first. In your pom.xml file, add:

<dependency>
    <groupId>io.quarkiverse.unleash</groupId>
    <artifactId>quarkus-unleash</artifactId>
    <version>1.0.0</version>
</dependency>

Usage

Unleash client

Assuming you have Unleash running on localhost:4242 you should add the following properties to your application.properties and fill in the values for url.

quarkus.unleash.url=http://localhost:4242/api

Once you have configured the properties, you can start using an Unleash-client.

@ApplicationScoped
public class TestService {

    @Inject
    Unleash unleash;

    public boolean isTest() {
        return unleash.isEnabled("quarkus.unleash.test");
    }
}

@FeatureToggle

By using the @FeatureToggle annotation there is a shortcut to inject feature toggle.

@ApplicationScoped
public class TestService {

    @FeatureToggle(name = "my-toggle")
    Instance<Boolean> myToggle;

    @FeatureToggle(name = "my-toggle", defaultValue = true)
    Instance<Boolean> myToggleDefault;

}

@FeatureVariant

By using the @FeatureVariant annotation there is a shortcut to inject feature toggle variant or the payload of the variant.

@ApplicationScoped
public class TestService {

    @FeatureVariant(name = "toggle-variant")
    Instance<Variant> variant;

    @FeatureVariant(name = "toggle-payload")
    Instance<String> variant;

    @FeatureVariant(name = "toggle-variant-json")
    Instance<MyCustomJsonModel> variant;

}

Testing

To use the test extension, add this dependency to the project:

<dependency>
    <groupId>io.quarkiverse.unleash</groupId>
    <artifactId>quarkus-unleash-test</artifactId>
    <version>1.0.0</version>
    <scope>test</scope>
</dependency>

UnleashTestResource creates an instance of admin and standard Unleash clients just for testing. These instances are separate from the application instances.

@QuarkusTest
@QuarkusTestResource(UnleashTestResource.class)
public class BaseTest {

    @InjectUnleashAdmin
    UnleashAdmin admin;

    @InjectUnleash
    Unleash client;

    @Test
    public void test() {

        admin.toggleOff("toggle-1");
        admin.toggleOn("toggle-2");

        // wait for client change
        await().atLeast(12, SECONDS)
                .pollInterval(4, SECONDS)
                .until(() -> client.isEnabled("toggle-2"));

        boolean toggleOn = client.isEnabled("toggle-2");

        // ... test my application

    }
}

Dev-Services

Dev Services for Unleash is automatically enabled unless:

quarkus.unleash.devservices.enabled is set to false
quarkus.unleash.url is configured

Dev Service for Unleash relies on Docker to start the broker. If your environment does not support Docker, you will need to start the broker manually, or connect to an already running broker. You can configure the broker address using quarkus.unleash.url.

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.unleash.devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_ENABLED`	boolean	`true`
`quarkus.unleash.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_PORT`	int
`quarkus.unleash.devservices.shared` Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container. The discovery uses the `quarkus-dev-service-unleash` label. The value is configured using the `service-name` property. Container sharing is only used in dev mode. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_SHARED`	boolean	`true`
`quarkus.unleash.devservices.service-name` The value of the `quarkus-dev-service-unleash` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Unleash looks for a container with the `quarkus-dev-service-unleash` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-unleash` label set to the specified value. This property is used when you need multiple shared Unleash servers. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_SERVICE_NAME`	string	`unleash`
`quarkus.unleash.devservices.image-name` The container image name to use, for container based DevServices providers. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_IMAGE_NAME`	string
`quarkus.unleash.devservices.reuse` Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass `testcontainers.reuse.enable=true` in your `.testcontainers.properties` file, to be stored in your home. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_REUSE`	boolean	`false`
`quarkus.unleash.devservices.import-file` The import data from file during the start. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_IMPORT_FILE`	string
`quarkus.unleash.devservices.db.image-name` The container image name to use, for unleash database. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_DB_IMAGE_NAME`	string	`postgres:15.2`
`quarkus.unleash.devservices.db.service-name` The value of the `quarkus-dev-service-unleash-db` label attached to the started container. This property is used when `shared` is set to `true`. In this case, before starting a container, Dev Services for Unleash DB looks for a container with the `quarkus-dev-service-unleash-db` label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the `quarkus-dev-service-unleash-db` label set to the specified value. This property is used when you need multiple shared Unleash DB servers. Environment variable: `QUARKUS_UNLEASH_DEVSERVICES_DB_SERVICE_NAME`	string	`unleash-db`
`quarkus.unleash.url` Unleash URL service endpoint Environment variable: `QUARKUS_UNLEASH_URL`	string	required
`quarkus.unleash.application` Application name Environment variable: `QUARKUS_UNLEASH_APPLICATION`	string
`quarkus.unleash.project` Project name Environment variable: `QUARKUS_UNLEASH_PROJECT`	string
`quarkus.unleash.instance-id` Instance ID. Environment variable: `QUARKUS_UNLEASH_INSTANCE_ID`	string
`quarkus.unleash.disable-metrics` Disable Unleash metrics Environment variable: `QUARKUS_UNLEASH_DISABLE_METRICS`	boolean	`false`
`quarkus.unleash.token` Application Unleash token Environment variable: `QUARKUS_UNLEASH_TOKEN`	string
`quarkus.unleash.environment` Application environment Environment variable: `QUARKUS_UNLEASH_ENVIRONMENT`	string
`quarkus.unleash.fetch-toggles-interval` Fetch toggles interval Environment variable: `QUARKUS_UNLEASH_FETCH_TOGGLES_INTERVAL`	long	`10`
`quarkus.unleash.send-metrics-interval` Send metrics interval Environment variable: `QUARKUS_UNLEASH_SEND_METRICS_INTERVAL`	long	`60`
`quarkus.unleash.backup-file` Backup file Environment variable: `QUARKUS_UNLEASH_BACKUP_FILE`	string
`quarkus.unleash.synchronous-fetch-on-initialisation` A synchronous fetch on initialisation Environment variable: `QUARKUS_UNLEASH_SYNCHRONOUS_FETCH_ON_INITIALISATION`	boolean	`false`
`quarkus.unleash.enable-proxy-authentication-by-jvm-properties` Enable proxy authentication by JVM properties Environment variable: `QUARKUS_UNLEASH_ENABLE_PROXY_AUTHENTICATION_BY_JVM_PROPERTIES`	boolean	`false`

Configuration property

Type

Default

quarkus.unleash.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode and when Docker is running.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_ENABLED

boolean

true

quarkus.unleash.devservices.port

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_PORT

int

quarkus.unleash.devservices.shared

Indicates if the Unleash server managed by Quarkus Dev Services is shared. When shared, Quarkus looks for running containers using label-based service discovery. If a matching container is found, it is used, and so a second one is not started. Otherwise, Dev Services for Unleash starts a new container. The discovery uses the quarkus-dev-service-unleash label. The value is configured using the service-name property. Container sharing is only used in dev mode.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_SHARED

boolean

true

quarkus.unleash.devservices.service-name

The value of the quarkus-dev-service-unleash label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Unleash looks for a container with the quarkus-dev-service-unleash label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-unleash label set to the specified value. This property is used when you need multiple shared Unleash servers.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_SERVICE_NAME

string

unleash

quarkus.unleash.devservices.image-name

The container image name to use, for container based DevServices providers.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_IMAGE_NAME

string

quarkus.unleash.devservices.reuse

Helper to define the stop strategy for containers created by DevServices. In particular, we don’t want to actually stop the containers when they have been flagged for reuse, and when the Testcontainers configuration has been explicitly set to allow container reuse. To enable reuse, ass testcontainers.reuse.enable=true in your .testcontainers.properties file, to be stored in your home.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_REUSE

boolean

false

quarkus.unleash.devservices.import-file

The import data from file during the start.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_IMPORT_FILE

string

quarkus.unleash.devservices.db.image-name

The container image name to use, for unleash database.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_DB_IMAGE_NAME

string

postgres:15.2

quarkus.unleash.devservices.db.service-name

The value of the quarkus-dev-service-unleash-db label attached to the started container. This property is used when shared is set to true. In this case, before starting a container, Dev Services for Unleash DB looks for a container with the quarkus-dev-service-unleash-db label set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it starts a new container with the quarkus-dev-service-unleash-db label set to the specified value. This property is used when you need multiple shared Unleash DB servers.

Environment variable: QUARKUS_UNLEASH_DEVSERVICES_DB_SERVICE_NAME

string

unleash-db

quarkus.unleash.url

Unleash URL service endpoint

Environment variable: QUARKUS_UNLEASH_URL

string

required

quarkus.unleash.application

Application name

Environment variable: QUARKUS_UNLEASH_APPLICATION

string