Techland

Quarkus Extension Custom Dev Service - Partie III

contact@techland.info (LE BARO Romain) — Fri, 11 Oct 2024 15:07:03 +0200

In the previous article, we discussed how to automatically launch a container that exposes an API connected to its own database using a Quarkus extension. Now, we will explore how to communicate with this API from our main application.

To Call an API, We Need Its URL!

In the previous article, we saved the access URL for our API in a RunningDevService. Now, we’ll use this URL to inject this value into our main application. To do this, we will create a new class named DemoClientApiProcessor:

@BuildSteps(onlyIf = { GlobalDevServicesConfig.Enabled.class })
public class DemoClientApiProcessor {

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createSDK(List<DevServicesResultBuildItem> devServicesResultBuildItem, DemoServiceRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set Inside DemoExtensionProcessor
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(DemoServiceContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find Demo-service url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoConfig.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());
    }


    @BuildStep
    public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
        additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
        additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
    }
}

The createSDK method, annotated with @BuildStep, takes a list of DevServicesResultBuildItem as a parameter. Quarkus will call this method after instantiating our database and API containers. The other parameters include a DemoServiceRecorder and a BuildProducer of SyntheticBeanBuildItem. Recorders and synthetic beans were already covered in a previous article. In summary, we retrieve the API URL from the devServicesResultBuildItem object and create a DemoConfig containing this URL, which will then be injectable.

The recorder is defined as follows:

package info.techland.demo.extension.runtime;

import io.quarkus.runtime.RuntimeValue;
import io.quarkus.runtime.annotations.Recorder;



@Recorder
public class DemoServiceRecorder {

    public RuntimeValue<DemoConfig> createConfig(String url) {
        return new RuntimeValue<>(new DemoConfig(url));
    }
}

The recorder is defined in the runtime package of our extension. Its role is to instantiate our DemoConfig object with the URL passed as a parameter so that Quarkus can record the resulting bytecode.

package info.techland.demo.extension.runtime;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class DemoConfig {

    private String url;

    // Only for CDI injection
    @SuppressWarnings("unused")
    private DemoConfig() {}

    public DemoConfig(String url) {
        this.url = url;
    }

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }
}

Our DemoConfig is just a bean containing the URL of our API once deployed as a devService.

@BuildStep
public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
    additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
    additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
}

This step declares our syntheticBean as injectable in our final application.

Building a RestClient in Our Application

Now we have an instance of DemoConfig that is injectable into any class of our main application. Let’s start by creating an interface for our RestClient in our main application to call our Demo API.

package info.techland.demo.app;


@Path("/api")
public interface DemoService {

    @GET
    Set<Demo> fetchAll();
}

/**
 * Somewhere in our principal application...
 */
@Path("")
public class AppResource {

    private DemoConfig demoConfig;
    private final DemoService demoService;

    public AppResource(DemoConfig demoConfig) {
        this.demoConfig = demoConfig;

        demoService = QuarkusRestClientBuilder.newBuilder()
            .baseUri(URI.create(demoConfig.getUrl()))
            .build(ExtensionsService.class);
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Set<Demo> fetchDemo() {
        return this.demoService.fetch();
    }
}

In our main application, we inject our DemoConfig object, which contains the URL of our API, and use it to configure a RestClient programmatically. Our fetchDemo method returns a Set of Demo objects, which is a simple POJO. Our main application is now automatically linked to our API. But this can be improved further. What if our RestClient wasn’t created by our main application, but by our extension and made injectable, like our DemoConfig?

Migrating the RestClient to Our Extension

Do this, it’s quite simple. First, we will move our DemoService class to our extension, within the runtime package. Next, we will create a DemoResource class responsible for creating our RestClient.

package info.techland.demo.extension.runtime;

import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import java.net.URI;
import java.util.List;

@Path("/")
public class DemoResource {

    private DemoService demoService;

    // Only for CDI injection
    @SuppressWarnings("unused")
    private DemoResource() {
    }

    public DemoResource(String url) {
        this.demoService = QuarkusRestClientBuilder.newBuilder()
                .baseUri(URI.create(url))
                .build(DemoService.class);
    }

    @GET
    public Set<Demo> fetchAsync() {
        return demoService.fetchAsync();
    }
}

The Demo POJO is also moved to our extension so that it’s available in any application using our extension.

Next, in our DemoServiceRecorder, we will add the instantiation of our DemoResource:

@Recorder
public class DemoServiceRecorder {

    public RuntimeValue<DemoResource> createSDK(String url) {
        return new RuntimeValue<>(new DemoResource(url));
    }

    public RuntimeValue<DemoConfig> createConfig(String url) {
        return new RuntimeValue<>(new DemoConfig(url));
    }
}

The final step is to configure Quarkus to inject our DemoResource via a SyntheticBean in our DemoClientApiProcessor:

@BuildSteps(onlyIf = { GlobalDevServicesConfig.Enabled.class })
public class DemoClientApiProcessor {

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createSDK(List<DevServicesResultBuildItem> devServicesResultBuildItem, DemoServiceRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set Inside DemoExtensionProcessor
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(DemoServiceContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find Demo-service url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoConfig.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoResource.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createSDK("http://"+apiUrl))
                .done());
    }


    @BuildStep
    public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
        additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
        additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
    }

    /**
     * A jandex file is mandatory by the maven-quarkus-plugin to resolve CDI dependency in the package phase.
     * At runtime, we need to remove this beans because we provide our own via syntheticBean
     * @param buildExclusionsBuildItemBuildProducer Producer for beans that will be excluded
     */
    @BuildStep
    public void removeJandexDemoBean(BuildProducer<ExcludedTypeBuildItem> buildExclusionsBuildItemBuildProducer) {
        buildExclusionsBuildItemBuildProducer.produce(new ExcludedTypeBuildItem(DemoConfig.class.getName()));
        buildExclusionsBuildItemBuildProducer.produce(new ExcludedTypeBuildItem(DemoResource.class.getName()));
    }
}

Our RestClient is now usable via injection of a DemoResource in our application. Let’s update the code in our AppResource, which is now much simpler:

@Path("")
public class AppResource {

    private final DemoResource demoResource;

    public AppResource(DemoResource demoResource) {
        this.demoResource = demoResource;
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Set<Demo> fetchDemo() {
        return this.demoResource.fetch();
    }
}

Conclusion

This concludes our series on using Quarkus extensions to develop custom dev services. For API consumers, usage is greatly simplified. A simple Maven import is all that’s required, providing a readily available SDK that simplifies calling our API. Future updates to our service are now as easy as updating the Maven dependency in the project. When there is a change in our API, it may be handled transparently by the SDK; otherwise, it will be detectable at compile time through a change in the Java method signature.

Quarkus Extension Custom Dev Service - Partie II

contact@techland.info (LE BARO Romain) — Thu, 10 Oct 2024 15:07:03 +0200

In the previous article, we saw how to automatically launch a database using a Quarkus extension. Now, we will see how to start our service in the same way and make it use the database we just deployed. I won’t go over the points covered in the previous article, so I encourage you to read it before continuing.

We take the same ones and start again.

The creation of our container for our service happens in the same way as the database. So, we’ll start by adding the necessary configurations to our DevServicesConfig:

    /**
     * The container image name to use, for container based DevServices providers.
     * If you want to use a specific version of demo, use:
     * {@code demo:<version>}.
     */
    @WithDefault("scandinave/demo")
    String imageName();

    /**
     * Optional fixed port the dev service will listen to.
     * <p>
     * If not defined, the port will be chosen randomly.
     */
    OptionalInt port();

    /**
     * The value of the {@code quarkus-dev-service-demo} label attached to the started container.
     * This property is used when {@code shared} is set to {@code true}.
     * In this case, before starting a container, Dev Services for Demo looks for a container with the
     * {@code quarkus-dev-service-demo} 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 {@code quarkus-dev-service-demo} label set to the specified value.
     * <p>
     */
    @WithDefault("demo")
    String serviceName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();

We begin by adding an option for the Docker image name that will be used to start our container. This way, the user can choose a specific version if they wish. The port is random by default but can also be specified. Finally, the label applied to the container can also be customized.

DemoExtensionProcessor

In our DemoExtensionProcessor, we add the code to initialize the container of our service.

  @BuildSteps(onlyIf = {GlobalDevServicesConfig.Enabled.class})
  public class DemoExtensionProcessor {
  
    /** stuff from previous article 
     * ...
     */

    private static volatile RunningDevService demoApiDevService;

    @BuildStep
    public void createContainer(DockerStatusBuildItem dockerStatusBuildItem,
                                List<DevServicesSharedNetworkBuildItem> devServicesSharedNetworkBuildItem,
                                DemoBuildTimeConfig buildTimeConfig,
                                GlobalDevServicesConfig devServicesConfig,
                                BuildProducer<DevServicesResultBuildItem> devServicesResult) {

      runningConfiguration = buildTimeConfig.devservices();

      try {
          /** 
           * DemoApiRunningDevService newAPIDevService = startDemoContainer...
           */

           DemoApiRunningDevService newAPIDevService = startDemoContainer(
                    dockerStatusBuildItem,
                    !devServicesSharedNetworkBuildItem.isEmpty(),
                    devServicesConfig.timeout.orElse(Duration.of(0, ChronoUnit.SECONDS)),
                    runningConfiguration,
                    newDatabaseDevService,
                    errors
            );
          // Get the RunningDevService instance.
          demoApiDevService = newAPIDevService.getRunningDevService();
      } catch (Throwable t) {
          throw new RuntimeException(t);
      }
      Log.info("Dev Services for Demo started.");

      devServicesResult.produce(demoApiDevService.toBuildItem());
    }
  }

Our startDemoContainer method also takes as a parameter the result of the call to the startDatabaseContainer method, which contains an instance of a DevRunningDevService. In this instance, we stored the URL for accessing our database. I mentioned earlier that this would be useful later.

return new DevServicesResultBuildItem.RunningDevService(feature, databaseContainer.getContainerId(),
        databaseContainer::close,
        Map.of(
            "url", databaseContainer.getHost() + ":" + databaseContainer.getPort(),
            "url-internal", databaseContainer.getContainerName().substring(1) + ":" + POSTGRES_INTERNAL_PORT
        )
);

startDemoContainer


private DemoApiRunningDevService startDemoContainer(DockerStatusBuildItem dockerStatusBuildItem, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DemoDatabaseRunningDevService runningService, List<String> errors) {
    if (!devServicesConfig.enabled()) {
        // explicitly disabled
        Log.debug("Not starting Dev Services for Demo as it has been disabled in the config");
        return null;
    }


    if (!dockerStatusBuildItem.isDockerAvailable()) {
        Log.warn("Please get a working docker instance");
        errors.add("Please get a working docker instance");
        return null;
    }

    String dbUrl = Optional.ofNullable(runningService.getRunningDevService().getConfig()).orElseThrow(() -> new IllegalStateException("Database does not start properly")).get("url-internal");

    final Optional<ContainerAddress> maybeExistingContainer = demoAPIDevModeContainerLocator.locateContainer(
            devServicesConfig.serviceName(),
            devServicesConfig.shared(),
            LaunchMode.current());

    String imageName = devServicesConfig.imageName();
    DockerImageName dockerImageName = DockerImageName.parse(imageName).asCompatibleSubstituteFor(imageName);


    return maybeExistingContainer
            .map(existingContainer -> new DemoApiRunningDevService(new RunningDevService(DemoApiContainer.CONTAINER_NAME, existingContainer.getId(),
                    null, Map.of("url", existingContainer.getHost() + ":" + existingContainer.getPort()))))
            .orElseGet(() -> new DemoApiRunningDevService(useSharedNetwork, timeout, devServicesConfig, dbUrl, dockerImageName, runningService));
}
}

We start with the same checks regarding the presence of Docker and the activation of dev services, then we retrieve the internal Docker connection URL for the database from our instance of RunningDevService. The method then checks if another container already exists using a new ContainerLocator:

`1`	`private static final ContainerLocator demoAPIDevModeContainerLocator = new ContainerLocator(DemoApiContainer.DEV_SERVICE_LABEL, DEMO_INTERNAL_PORT);`

If a container for our service is already running, the method returns a RunningDevService with the information of the existing container. Otherwise, a new RunningDevService for the new container is returned. This new RunningDevService takes the database URL as a parameter.

DemoApiRunningDevService

public class DemoApiRunningDevService {

    private DemoApiContainer demoContainer;
    private final DevServicesResultBuildItem.RunningDevService runningDevServiceSupplier;

    public DemoApiRunningDevService(boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, String dbUrl, DockerImageName
            dockerImageName, DemoDatabaseRunningDevService runningService) {
        runningDevServiceSupplier = this.run(useSharedNetwork, timeout, devServicesConfig, dbUrl, dockerImageName, runningService);
    }

    public DemoApiRunningDevService(DevServicesResultBuildItem.RunningDevService runningDevService) {
        runningDevServiceSupplier = runningDevService;
        demoContainer = null;
    }


    public DevServicesResultBuildItem.RunningDevService run(boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, String dbUrl, DockerImageName dockerImageName, DemoDatabaseRunningDevService runningService) {
        if (devServicesConfig.port().isPresent()) {
            try (DemoApiContainer container = new DemoApiContainer(dockerImageName, devServicesConfig.port().getAsInt(), useSharedNetwork, devServicesConfig.shared(), devServicesConfig.serviceName())) {
                demoContainer = container;
            }
        } else {
            try (DemoApiContainer container = new DemoApiContainer(dockerImageName, useSharedNetwork, devServicesConfig.shared(), devServicesConfig.serviceName())) {
                demoContainer = container;
            }
        }

        Optional.ofNullable(timeout).ifPresent(demoContainer::withStartupTimeout);
        demoContainer.withEnv(devServicesConfig.containerEnv());


        demoContainer.withEnv("POSTGRES_USER", devServicesConfig.db().username());
        demoContainer.withEnv("POSTGRES_PASSWORD", devServicesConfig.db().password());
        demoContainer.withEnv("DB_URL", dbUrl + "/" + devServicesConfig.db().name());
        if (runningService.getDatabaseContainer().isPresent()) { // Wait for database container to start. If container is null, it means that a database was already started so no need to wait.
            demoContainer.withNetwork(runningService.getDatabaseContainer().get().getNetwork());
            demoContainer.dependsOn(runningService.getDatabaseContainer().get());
        }

        demoContainer.start();

        return new DevServicesResultBuildItem.RunningDevService(DemoApiContainer.CONTAINER_NAME, demoContainer.getContainerId(),
                demoContainer::close, Map.of("url", demoContainer.getHost() + ":" + demoContainer.getPort()));

    }

    public Optional<GenericContainer<DemoApiContainer>> getDatabaseContainer() {
        return Optional.ofNullable(demoContainer);
    }

    public DevServicesResultBuildItem.RunningDevService getRunningDevService() {
        return runningDevServiceSupplier;
    }
}

Our class defines two constructors: the first that simply returns the existing RunningDevService if the container already exists, and the second that creates a new RunningDevService. Our run method first checks if a port is specified in the dev-service configuration. If it is, our container will be started on that port; otherwise, an available random port will be allocated (the default behavior).

Once the instance of our DemoApiContainer is created, we configure it by passing the expected environment variables through the withEnv method. We use our devServiceConfig to retrieve the database connection credentials and the URL passed as a parameter. Then, we configure the container to be on the same network as the database and wait for it to finish starting.

Finally, we return our RunningDevService, containing the ID of our container as well as the configuration that includes the URL for accessing our API, which will also be useful for the next steps.

DemoApiContainer

All that remains is to look at the DemoApiContainer class to complete this second post on creating a DevService with Quarkus.

import io.quarkus.devservices.common.ConfigureUtil;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

public class DemoApiContainer extends GenericContainer<DemoApiContainer> {

    public static final String CONTAINER_NAME = "demo";
    public static final String DEV_SERVICE_LABEL="quarkus-dev-service-demo";
    private final Integer exposedPort;
    public static final int DEMO_INTERNAL_PORT = 8600;
    private final boolean useSharedNetwork;
    private final String serviceName;
    private String hostname;
    private final boolean sharedContainer;

    public DemoApiContainer(DockerImageName image, boolean useSharedNetwork, boolean isShared, String serviceName) {
        this(image, null, useSharedNetwork, isShared, serviceName);
    }

    public DemoApiContainer(DockerImageName image, Integer exposedPort, boolean useSharedNetwork, boolean isShared, String serviceName) {
        super(image);
        this.exposedPort = exposedPort;
        this.useSharedNetwork = useSharedNetwork;
        this.sharedContainer = isShared;
        this.serviceName = serviceName;


    }

    @Override
    protected void configure() {
        super.configure();

        if (this.useSharedNetwork) {
            hostname = ConfigureUtil.configureSharedNetwork(this, "demo");
        }

        if(this.exposedPort != null) {
          addFixedExposedPort(this.exposedPort, DEMO_INTERNAL_PORT);
          if(useSharedNetwork) {
              // expose random port for which we are able to ask Testcontainers for the actual mapped port at runtime
              // as from the host's perspective Testcontainers actually expose container ports on random host port
              addExposedPort(DEMO_INTERNAL_PORT);
          }
        } else {
            addExposedPort(DEMO_INTERNAL_PORT);
        }

        withLabel(DEV_SERVICE_LABEL, serviceName);

        // Tell the dev service how to know the container is ready
        waitingFor(Wait.forLogMessage(".*demo.*started.*", 1));
    }

    @Override
    public String getHost() {
        if(this.useSharedNetwork) {
            return hostname;
        }
        return super.getHost();
    }

    public int getPort() {
        if (useSharedNetwork) {
            return DEMO_INTERNAL_PORT;
        }
        if (exposedPort != null) {
            return exposedPort;
        }
        return getFirstMappedPort();
    }
}

I won’t dwell on this class as it is identical to that of our DemoDatabaseContainer. The only difference is the wait for the event indicating the end of the process startup in the container. Here, we wait for a log in our application containing the words demo and started.

Conclusion

Our extension now launches a dockerized service along with its database, all automatically configured to work together. Since we already included the extension in the previous step, there is nothing more we need to do to benefit from this update.

In a future article, we will see how to interact with our API using the URL saved in our RunningDevService and how to provide an SDK that allows this API to be exploited through a simple dependency injection into our client application.

Quarkus Extension Custom Dev Service - Part I

contact@techland.info (LE BARO Romain) — Tue, 08 Oct 2024 22:34:03 +0200

Today, we’re tackling a major topic with a use case that is not documented by Quarkus but is extremely useful. Quarkus offers extensions with “dev services.” Once included in your project, these extensions automatically launch services when the project starts in dev mode. We will see how to create our own “dev service” for Quarkus applications. The idea is to provide an extension for each of our services to make them easily usable by others.

Use Case

Imagine a company with multiple projects and several teams. It’s common for services to be shared between different projects. Two solutions are usually implemented:

A shared dev instance
A Docker Compose to be run alongside the project in dev mode.

The first solution involves complicated administration with data management across different teams. If one team breaks the service, it impacts the others. During an update, all teams are affected as well.

The second solution is more flexible, as the services run on the developer’s machine. However, it adds an extra step when starting the project in dev mode. It also raises the issue of updating the Docker Compose.

A “dev service” helps solve these problems. Distributed as a Maven extension, they can be kept up to date using a Maven BOM. Quarkus starts them automatically when the project launches, eliminating the need to manually manage Docker containers.

The Extension

Our extension will need to start a Quarkus service with its database. The extension should allow the service to start with default parameters and make them customizable.

Let’s start by creating the extension with the following command:

1
2
3

mvn io.quarkus.platform:quarkus-maven-plugin:3.14.4:create-extension -N \
    -DgroupId=info.techland \
    -DextensionId=demo-extension

This will create an extension with the following structure:

demo-extension
|__ deployment
|__ integration-tests
|__ runtime
|__ pom.xml

At the end, the architecture of our extension will look like the following diagram:

Diagram of our extension for the database

Creating the Database for Our Dev Service

Our service needs a database to function. So we will configure our extension to launch a database in a Docker container. Before that, let’s create some configurations for our extension to make it customizable.

DemoExtensionBuildTimeConfig

package info.techland.demo.extension.deployment;

import io.quarkus.runtime.annotations.ConfigPhase;
import io.quarkus.runtime.annotations.ConfigRoot;
import io.smallrye.config.ConfigMapping;


@ConfigMapping(prefix = "quarkus.demo")
@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
public interface DemoExtensionBuildTimeConfig {

    /**
     * Dev services configuration.
     */
    DevServicesConfig devservices();

}

This class registers the entry point of our dev service configuration. Our configuration will be accessible in the application.properties file under the quarkus.demo key.

DevServiceConfig

package info.techland.demo.extension.deployment;

import java.util.Map;

import io.quarkus.runtime.annotations.ConfigGroup;
import io.smallrye.config.WithDefault;

@ConfigGroup
public interface DevServicesConfig {

    /**
     * If DevServices has been explicitly enabled or disabled. DevServices is generally enabled
     * by default, unless there is an existing configuration present.
     * <p>
     * When DevServices is enabled Quarkus will attempt to automatically configure and start
     * a demo instance when running in Dev or Test mode and when Docker is running.
     */
    @WithDefault("true")
    boolean enabled();


    /**
     * Indicates if the demo 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 demo starts a new container.
     * <p>
     * The discovery uses the {@code quarkus-dev-service-redis} label.
     * The value is configured using the {@code service-name} property.
     * <p>
     * Container sharing is only used in dev mode.
     */
    @WithDefault("true")
    boolean shared();

    /**
     * The value of the {@code quarkus-dev-service-demo} label attached to the started container.
     * This property is used when {@code shared} is set to {@code true}.
     * In this case, before starting a container, Dev Services for demo looks for a container with the
     * {@code quarkus-dev-service-demo} 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 {@code quarkus-dev-service-demo} label set to the specified value.
     * <p>
     * This property is used when you need multiple shared demo servers.
     */
    @WithDefault("demo")
    String serviceName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();

    /**
     * Configuration for the postgresql database use by demo service.
     * @return The database configuration
     */
    DatabaseConfig db();
}

This class configures our dev service with access to the database configuration of the dev service. The database configuration will be accessible under the quarkus.dev.db key. Each entry has a default value to allow the extension to be used without particular configuration.

DatabaseConfig

package info.techland.demo.extension.deployment;

import io.quarkus.runtime.annotations.ConfigGroup;
import io.smallrye.config.WithDefault;

import java.util.Map;
import java.util.OptionalInt;

@ConfigGroup
public interface DatabaseConfig {

    /**
     * The database password used by the demo service.
     */
    @WithDefault("demo")
    String username();

    /**
     * The database password used by the demo service.
     */
    @WithDefault("demo")
    String password();

    /**
     * The database name used by the demo service
     */
    @WithDefault("demo")
    String name();

    /**
     * The number of reactive connection to use.
     */
    @WithDefault("20")
    int reactiveMaxSize();

    /**
     * The port used by the database.
     * @return The database port
     */
    OptionalInt port();

    /**
     * Name of the postgresql image to use to start the database
     * @return The image name.
     */
    @WithDefault("docker.io/postgres")
    String imageName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();
}

The database configuration contains connection information for the PostgreSQL database used by default. Again, we favor convention over configuration by applying default values.

DemoExtensionProcessor

To ask Quarkus to start a container, we will need to configure our DemoExtensionProcessor. Let’s start by adding a createContainer method that will act as a @BuildStep to start and configure our container.

  @BuildSteps(onlyIf = {GlobalDevServicesConfig.Enabled.class})
  public class DemoExtensionProcessor {
  
    /**
     * The current configuration. either from running container instance or an instance that is about to start.
     */
    private static volatile DevServicesConfig runningConfiguration;
    private static volatile RunningDevService demoDatabaseDevService;

    @BuildStep
    public void createContainer(DockerStatusBuildItem dockerStatusBuildItem,
                                List<DevServicesSharedNetworkBuildItem> devServicesSharedNetworkBuildItem,
                                DemoBuildTimeConfig buildTimeConfig,
                                GlobalDevServicesConfig devServicesConfig,
                                BuildProducer<DevServicesResultBuildItem> devServicesResult) {

      runningConfiguration = buildTimeConfig.devservices();

      try {
          List<String> errors = new ArrayList<>();
          DemoDatabaseRunningDevService newDatabaseDevService = startDatabaseContainer(
                  dockerStatusBuildItem,
                  !devServicesSharedNetworkBuildItem.isEmpty(),
                  devServicesConfig.timeout.orElse(Duration.of(0, ChronoUnit.SECONDS)),
                  runningConfiguration,
                  errors
          );


          // Get the RunningDevService instance.
          demoDatabaseDevService = newDatabaseDevService.getRunningDevService();
      } catch (Throwable t) {
          throw new RuntimeException(t);
      }
      Log.info("Dev Services for Demo started.");

      // Call to toBuildItem method to get the DevServicesResultBuildItem need by the BuildStep producer.
      devServicesResult.produce(demoDatabaseDevService.toBuildItem());
    }
  }

Our method is injected with the following build items:

DockerStatusBuildItem : Allows retrieving the status of a Docker instance.
DevServicesSharedNetworkBuildItem : Determines if containers are started on a shared network.
DemoBuildTimeConfig : Configuration of our extension.
GlobalDevServicesConfig : Global configuration for dev services provided by Quarkus.
DevServicesResultBuildItem : The build item to produce for referencing our container to Quarkus.

Our method then calls the startDatabaseContainer method, which is responsible for creating an instance of DemoDatabaseRunningDevService. This class provides a RunningDevService, via devServicesResult.produce(demoDatabaseDevService.toBuildItem()), which is returned by our @BuildStep to request Quarkus to launch a container.

startDatabaseContainer


private DemoDatabaseRunningDevService startDatabaseContainer(DockerStatusBuildItem dockerStatusBuildItem, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, List<String> errors) {
    if (!devServicesConfig.enabled()) {
        // explicitly disabled
        Log.debug("Not starting Dev Services for Demo as it has been disabled in the config");
        return null;
    }


    if (!dockerStatusBuildItem.isDockerAvailable()) {
        Log.warn("Please get a working docker instance");
        errors.add("Please get a working docker instance");
        return null;
    }

    final Optional<ContainerAddress> maybeExistingContainer = demoDBDevModeContainerLocator.locateContainer(
            devServicesConfig.serviceName() + "_db",
            devServicesConfig.shared(),
            LaunchMode.current());

    // Get the image name from the configuration.
    String imageName = devServicesConfig.db().imageName();
    DockerImageName dockerImageName = DockerImageName.parse(imageName).asCompatibleSubstituteFor(imageName);

    return maybeExistingContainer
            .map(existingContainer -> new DemoDatabaseRunningDevService(new RunningDevService(DemoDatabaseContainer.CONTAINER_NAME, existingContainer.getId(),
                    null, Map.of("url", existingContainer.getHost() + ":" + existingContainer.getPort()))))
            .orElseGet(() -> new DemoDatabaseRunningDevService(DemoDatabaseContainer.CONTAINER_NAME, useSharedNetwork, timeout, devServicesConfig,
                    dockerImageName, devServicesConfig.serviceName() + "_db"));
}

We start with a few checks. If dev services are globally disabled, the launch is canceled, and if Docker is unavailable, an error is returned. The method then checks if another container already exists. This may happen if two Quarkus services use the same extension. This is done using a ContainerLocator:

`1`	`private static final ContainerLocator demoDBDevModeContainerLocator = new ContainerLocator(DemoDatabaseContainer.DEV_SERVICE_LABEL, POSTGRES_INTERNAL_PORT);`

If a database container is already running, the method returns a RunningDevService with the information from the existing container. Otherwise, a new RunningDevService is returned for the new container.

DemoDatabaseRunningDevService

public class DemoDatabaseRunningDevService {

    private DemoDatabaseContainer databaseContainer;
    private final DevServicesResultBuildItem.RunningDevService runningDevServiceSupplier;

    public DemoDatabaseRunningDevService(String feature, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DockerImageName
            dockerImageName, String serviceName) {
        runningDevServiceSupplier = this.run(feature, useSharedNetwork, timeout, devServicesConfig, dockerImageName, serviceName);
    }

    public DemoDatabaseRunningDevService(DevServicesResultBuildItem.RunningDevService runningDevService) {
        runningDevServiceSupplier = runningDevService;
        databaseContainer = null;
    }

    public DevServicesResultBuildItem.RunningDevService  run(String feature, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DockerImageName
            dockerImageName, String serviceName) {

        if(devServicesConfig.db().port().isPresent()) {
            databaseContainer = new DemoDatabaseContainer(dockerImageName, devServicesConfig.db().port().getAsInt(), useSharedNetwork, serviceName);
        } else {
            databaseContainer = new DemoDatabaseContainer(dockerImageName, useSharedNetwork, serviceName);
        }

        Optional.ofNullable(timeout).ifPresent(databaseContainer::withStartupTimeout);
        databaseContainer.withEnv(devServicesConfig.db().containerEnv());


        databaseContainer.withEnv("POSTGRES_USER", devServicesConfig.db().username());
        databaseContainer.withEnv("POSTGRES_PASSWORD", devServicesConfig.db().password());
        databaseContainer.withEnv("POSTGRES_DB",devServicesConfig.db().name());
        databaseContainer.withNetwork(useSharedNetwork ? Network.SHARED : Network.newNetwork());
        databaseContainer.start();

        return new DevServicesResultBuildItem.RunningDevService(feature, databaseContainer.getContainerId(),
                databaseContainer::close,
                Map.of(
                    "url", databaseContainer.getHost() + ":" + databaseContainer.getPort(),
                    "url-internal", databaseContainer.getContainerName().substring(1) + ":" + POSTGRES_INTERNAL_PORT
                )
        );

    }

    public Optional<GenericContainer<DemoDatabaseContainer>> getDatabaseContainer() {
        return Optional.ofNullable(databaseContainer);
    }

    public DevServicesResultBuildItem.RunningDevService getRunningDevService() {
        return runningDevServiceSupplier;
    }
}

Our class defines two constructors. The first simply returns the existing RunningDevService in case the container already exists. The second creates a new RunningDevService. The run method first checks if a port is specified in the dev-service configuration. If so, our container will be started on this port; otherwise, a random available port will be allocated (this is the default behavior).

Once the instance of our DemoDatabaseContainer is created, we configure it by passing the environment variables it expects via the withEnv method. Next comes the configuration of the Docker network used. If the user has explicitly specified that the containers should be attached to the shared Docker network create by TestContainer, we use the withNetwork method with the value Network.SHARED. Otherwise, a new network is created for the container.

Finally, we return our RunningDevService, containing the ID of our container along with the configuration that will be useful later.

DemoDatabaseContainer

Now, let’s look at the DemoDatabaseContainer class to finish this first post on creating a DevService with Quarkus.

import io.quarkus.devservices.common.ConfigureUtil;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

public class DemoDatabaseContainer extends GenericContainer<DemoDatabaseContainer> {


    public static final String CONTAINER_NAME="demo-db";
    private static final String DEV_SERVICE_LABEL="quarkus-dev-service-db";
    private final String serviceName;
    private final Integer fixedExposedPort;
    public final static int POSTGRES_INTERNAL_PORT = 5432;
    private final boolean useSharedNetwork;
    private String hostname;

    public DemoDatabaseContainer(DockerImageName image, boolean useSharedNetwork, String serviceName) {
        this(image, null, useSharedNetwork, serviceName);
    }

    public DemoDatabaseContainer(DockerImageName image, Integer exposedPort, boolean useSharedNetwork, String serviceName) {
        super(image);
        this.fixedExposedPort = exposedPort;
        this.useSharedNetwork = useSharedNetwork;
        this.serviceName = serviceName;
    }

    @Override
    protected void configure() {
        super.configure();

        if (this.useSharedNetwork) {
            hostname = ConfigureUtil.configureSharedNetwork(this, "demo");
            return;
        }

        if(this.fixedExposedPort != null) {
          addFixedExposedPort(this.fixedExposedPort, POSTGRES_INTERNAL_PORT);
        } else {
            addExposedPort(POSTGRES_INTERNAL_PORT);
        }

        withLabel(DEV_SERVICE_LABEL, serviceName);

        super.setWaitStrategy(Wait.forListeningPorts(POSTGRES_INTERNAL_PORT));
    }

    @Override
    public String getHost() {
        if(this.useSharedNetwork) {
            return hostname;
        }
        return super.getHost();
    }

    public int getPort() {
        if (useSharedNetwork) {
            return POSTGRES_INTERNAL_PORT;
        }
        if (fixedExposedPort != null) {
            return fixedExposedPort;
        }
        return getFirstMappedPort();
    }
}

This class extends GenericContainer and contains the configuration used by TestContainer to start our Docker container. In the configure method, we first check if the container should use the shared network. If so, ConfigureUtil.configureSharedNetwork handles everything. Otherwise, we configure the port (fixed or random), add a label, and specify the port to listen to for service startup completion.

Conclusion

Our database extension is now functional. It provides an implementation of a GenericContainer through a RunningDevService to our DemoExtensionProcessor. Everything is customizable via Quarkus’s standard configuration. All we need to do is to include the extension in a Quarkus application via a Maven import to have the database started in parallel.

In the next article, we’ll see how to launch a service in its own container using this database to expose an API to our Quarkus application.

Backstage oidc Provider

contact@techland.info (LE BARO Romain) — Wed, 25 Sep 2024 08:40:03 +0200

Backstage is an excellent dashboard tool for developers. Its plugin system makes it particularly flexible. However, configuring these plugins can be tedious. Backstage is constantly evolving, which sometimes makes it difficult for the documentation to keep up. This has been the case since the migration to the new Backend system. Backstage provides several plugins for connecting to most identity providers via OIDC. However, if you want to connect Backstage to a custom provider, like an enterprise Keycloak, the documentation is not very clear. That’s what we will explore in this post.

OIDC plugin configuration

Backstage provides an OIDC provider but no ready-to-use plugin. We will need to create a module to extend Backstage’s Auth plugin with our OIDC support. We use the Backstage CLI for this:

1
2
3

backstage-cli new --select backend-module
# ? Enter the ID of the plugin [required] : auth
# ? Enter the ID of the module [required] : oidc

Backstage has now generated a plugin structure in the plugins/auth-backend-module-oidc folder. Let’s start by adding the OIDC provider dependency provided by Backstage:

1
2

cd plugins/auth-backend-module-oidc
yarn add @backstage/plugin-auth-backend-module-oidc-provider

Once this is done, in the src/module.ts file, replace the content with the following:

import { oidcAuthenticator } from '@backstage/plugin-auth-backend-module-oidc-provider';
import { authProvidersExtensionPoint, createOAuthProviderFactory } from '@backstage/plugin-auth-node'
import {
  coreServices,
  createBackendModule,
} from '@backstage/backend-plugin-api';
import { DEFAULT_NAMESPACE, stringifyEntityRef } from '@backstage/catalog-model';

export const authModuleOidc = createBackendModule({
  pluginId: 'auth',
  moduleId: 'oidc',
  register(reg) {
    reg.registerInit({
      deps: { logger: coreServices.logger, providers: authProvidersExtensionPoint },
      async init({ logger, providers }) {
        logger.info('Registering OIDC provider!');
        providers.registerProvider({
          providerId: 'sso-auth-provider',
          factory: createOAuthProviderFactory({
            authenticator: oidcAuthenticator,
            async signInResolver(info, ctx) {
              const userRef = stringifyEntityRef({
                kind: 'User',
                name: info.result.fullProfile.userinfo.sub,
                namespace: DEFAULT_NAMESPACE
              });
              return ctx.issueToken({
                claims: {
                  sub: userRef, // The user's own identity
                  ent: [userRef], // A list of identities that the user claims ownership through
                }
              });
            }
          })
        });
      },
    });
  },
});

Our module is now operational. Let’s check that the module is properly enabled in packages/backend/index.ts. The following line should be present:

`1`	`backend.add(import('backstage-plugin-auth-backend-module-oidc'))`

Api Factory configuration

Now, we will reference the plugin as the authentication API in the front end. To do this, add the following code in the packages/app/src/apis.ts file:

import {
  AnyApiFactory,
  ApiRef,
  BackstageIdentityApi,
  configApiRef,
  createApiFactory,
  createApiRef,
  discoveryApiRef,
  oauthRequestApiRef,
  OpenIdConnectApi,
  ProfileInfoApi,
  SessionApi,
} from '@backstage/core-plugin-api';
import { OAuth2 } from '@backstage/core-app-api';

export const oidcAuthApiRef: ApiRef <
  OpenIdConnectApi & // The OIDC API that will handle authentification
  ProfileInfoApi & // Profile API for requesting user profile info from the auth provider in question
  BackstageIdentityApi & // Backstage Identity API to handle and associate the user profile with backstage identity
  SessionApi // Sesssion API, to handle the session the user will have while logged in
> = createApiRef({
  id: 'sso-auth-provider' // Can be anything as long as it doesn't conflict with other API ref IDs
})

export const apis: AnyApiFactory[] = [
  createApiFactory({
    api: oidcAuthApiRef,
    deps: {
      discoveryApi: discoveryApiRef,
      oauthRequestApi: oauthRequestApiRef,
      configApi: configApiRef
    },
    factory: ({ discoveryApi, oauthRequestApi, configApi }) => Oauth2.create({
      configApi,
      discoveryApi,
      oauthRequestApi,
      provider: {
        id: 'sso-auth-provider',
        title: 'Enterprise SSO',
        icon: () => null
      },
      environment: configApi.getOptionalString('auth.environment'),
      defaultScopes: ['openId', 'profile', 'email'],
      popupOptions: {
        size: {
          // fullscreen: true
          // or specify popup width and height
          width: 1000,
          height: 1000,
        }
      }
    })
  }),
  // Other createApiFactory
]

Adding the connection button into the interface

Now let’s go to the packages/app/src/App.tsx file to add the login button to Backstage.

import { apis, oidcAuthApiRef } from './apis';
import { configApiRef, useApi } from '@backstage/core-plugin-api';

const app = createApp({
  // Other stuff...
  components: {
    SignInPage: props => (<SignInPage {...props} auto providers={ useApi(configApiRef).getString('auth.environment') === 'development' ? ['guest'] : [{
      id: 'sso-auth-provider',
      title: 'Enterprise SSO',
      message: 'Sign in with Enterprise SSO',
      apiRef: oidcAuthApiRef
    }]}/>)
  }
  // Other stuff...
})

and in the app-config.production.yaml file:

1
2

auth:
  environment: development

et dans le fichier app-config.production.yaml

auth:
  environment: production
  providers:
    guest: {}
    sso-auth-provider:
      production:
        metadataUrl: ${AUTH_REALM_URL}/.well-known/openid-configuration
        clientId: ${AUTH_MY_CLIENT_ID}
        clientSecret: ${AUTH_MY_CLIENT_SECRET}

With the above configuration, authentication will occur as a guest in development mode and via SSO in production mode. For more information, you can check the official documentation

Congratulations, your Backstage application now supports OIDC login. Also take a look at the Keycloak integration for automatique import of user and groups into Backstage.

Quarkus Extension Synthetic Build Item

Sun, 07 Jul 2024 12:29:05 +0200

In the previous post on the AdditionalBeanBuildItem, we discussed how to reference a bean with the ARC dependency manager. While useful, there are cases where you need the manager to inject a specific instance of a pre-configured bean. Since AdditionalBeanBuildItem only accepts a bean class as a parameter, it cannot be used for this purpose. This is where the SyntheticBeanBuildItem comes into play.

Use Case

Imagine your extension needs to provide a configuration as an injectable bean to communicate with a third-party API. You’ll need to instruct Quarkus on which bean instance to inject and with what values.

SyntheticBeanBuildItem

The name of this build item is not very descriptive, and it took me some time to understand its purpose. In summary, it’s an AdditionalBeanBuildItem that accepts an instance of a class instead of a class as a parameter, making it very powerful. To produce a class instance, you first need to provide this instance in the form of a Recorder.

Recorder

Let’s start by creating our API configuration bean in the runtime module of our extension:

@ApplicationScoped
public class Config {

    private String url;

    // Only for CDI injection during mvn package phase
    @SuppressWarnings("unused")
    private Config() {}

    public Config(String url) {
        this.url = url;
    }

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }
}

Our bean must be “CDI compatible,” meaning it needs to have a default constructor and accessors. In our case, we use a private default constructor to ensure the class is not used in unintended ways. The Quarkus Maven plugin checks for injectable beans during the packaging phase. Without this default constructor, our project build would fail with an Unsatisfied dependency error. We define our bean with the @ApplicationScoped scope so that the same instance is always injected.

Now, let’s create the recorder for our Config class:

@Recorder
public class ConfigRecorder {

    public RuntimeValue<Config> createConfig(String url) {
        return new RuntimeValue<>(new Config(url));
    }
}

When a recorder is declared, Quarkus will execute it during the build phase and record the bytecode produced by the recorder. During runtime, Quarkus will provide this bytecode directly instead of recalculating it dynamically, which greatly speeds up startup time. In our example, the recorder returns a RuntimeValue<Config> object containing our configuration instance. This RuntimeValue will be consumed by our SyntheticBeanBuildItem.

BuildStep

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createConfig(List<DevServicesResultBuildItem> devServicesResultBuildItem, ConfigRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set inside ApiContainer
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(ApiContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find api url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(ConfigRecorder.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());
    }

To configure our SyntheticBuildItem, we use a method annotated with @Record(ExecutionTime.RUNTIME_INIT). Here, ExecutionTime.STATIC_INIT won’t work because our recorder won’t be available yet. Next, we retrieve our API URL via a DevServicesResultBuildItem, which we will discuss in a future post. Once the API URL is retrieved, we construct our SyntheticBeanBuildItem with our recorder. The unremovable method ensures that our bean instance will not be removed by Quarkus during the extension’s compilation, even if the bean is not used. Without this, our bean won’t be accessible in the Maven module importing our extension. Since we used @Record(ExecutionTime.RUNTIME_INIT), we inform Quarkus that our bean instance will be available during the RuntimeInit phase using the setRuntimeInit method. Finally, we pass our config bean instance to the runtimeValue method to complete the initialization of our SyntheticBeanBuildItem.

If you don’t have control over the produced bean class, you can add a missing qualifier using the .addQualifier(ApplicationScoped.class) method.

Bean Injection

In a project importing our extension:

<dependency>
    <groupId>org.example</groupId>
    <artifactId>example-extension</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

We can now inject our configuration bean to use it:

public class MyClassExample {

    private final Config config;

    public MyClassExample(Config config) {
        this.config = config;
    }
}

Conclusion

A SyntheticBeanBuildItem is the dynamic counterpart of the AdditionalBeanBuildItem. It uses a Recorder to record the bytecode produced by our instance during Quarkus’s build phase. This bytecode is provided as-is during the application’s runtime, accelerating its startup.

Quarkus Extension Additional Application Archive Marker Build Item

Thu, 29 Feb 2024 11:23:22 +0100

In the previous post about the AdditionalBeanBuildItem, we saw how to reference a bean in the ARC dependency manager. This is very convenient, but in some cases, we want the manager to inject a specific instance of an already configured bean. Since AdditionalBeanBuildItem only takes a bean class as a parameter, it can’t be used for this. This is where SyntheticBeanBuildItem comes in.

Use Case

Imagine your extension wants to provide a configuration as an injectable bean to communicate with a third-party API. You need to tell Quarkus which bean instance to inject and with what values.

SyntheticBeanBuildItem

The name of this build item isn’t very descriptive, and it took me a while to understand its purpose. In summary, it’s an AdditionalBeanBuildItem that takes an instance of a class instead of a class as a parameter, making it very powerful. To produce a class instance, you first need to provide this instance in the form of a Recorder.

Recorder

Let’s start by creating our API configuration bean in the runtime module of our extension:

@ApplicationScoped
public class Config {

    private String url;

    // Only for CDI injection during mvn package phase
    @SuppressWarnings("unused")
    private Config() {}

    public Config(String url) {
        this.url = url;
    }

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }
}

Our bean must be “CDI compatible”. This requires a default constructor and accessors. In our case, we use a private default constructor to prevent unintended use. The Quarkus Maven plugin checks for injectable beans during the package phase. Without this default constructor, our project build fails with an Unsatisfied dependency error. We define our bean in the @ApplicationScoped scope to ensure the same instance is always injected.

Now let’s create the recorder for our Config class:

@Recorder
public class ConfigRecorder {

    public RuntimeValue<Config> createConfig(String url) {
        return new RuntimeValue<>(new Config(url));
    }
}

When a recorder is declared, Quarkus executes it during the build phase and records the produced bytecode. At runtime, Quarkus provides this bytecode directly instead of recalculating it dynamically, greatly speeding up startup time. In our example, the recorder returns a RuntimeValue object containing our configuration instance. This RuntimeValue will be consumed by our SyntheticBeanBuildItem.

BuildStep

@Record(ExecutionTime.RUNTIME_INIT)
@BuildStep
public void createConfig(List<DevServicesResultBuildItem> devServicesResultBuildItem, ConfigRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
    // Retrieve config set Inside ApiContainer
    String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(ApiContainer.CONTAINER_NAME))
            .findFirst()
            .orElseThrow(() -> new IllegalStateException("Can't find api url"))
            .getConfig().get("url");

    syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(ConfigRecorder.class)
            .unremovable()
            .setRuntimeInit()
            .runtimeValue(recorder.createConfig("http://"+apiUrl))
            .done());
}

To configure our syntheticBuildItem, we use a method annotated with @Record(ExecutionTime.RUNTIME_INIT). Here, ExecutionTime.STATIC_INIT won’t work because our recorder won’t be available yet. Next, we retrieve our API URL via a DevServicesResultBuildItem, which we’ll discuss in a future article. Once the API URL is obtained, we build our SyntheticBeanBuildItem with our recorder. The unremovable method ensures our bean instance isn’t removed by Quarkus during the extension compilation even if the bean isn’t used. Without this, our bean wouldn’t be accessible in the Maven module importing our extension. By using @Record(ExecutionTime.RUNTIME_INIT), we inform Quarkus that our bean instance will be available during the RuntimeInit phase using the setRuntimeInit method. Finally, we pass our config bean instance to the runtimeValue method to complete the initialization of our SyntheticBeanBuildItem.

If you don’t have control over the produced bean’s class, you can add a missing qualifier via the .addQualifier(ApplicationScoped.class) method.

Bean Injection

In a project importing our extension:

<dependency>
    <groupId>org.example</groupId>
    <artifactId>example-extension</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

We can now inject our configuration bean to use it:

public class MyClassExample {

    private final Config config;

    public MyClassExample(Config config) {
        this.config = config;
    }
}

Conclusion

A SyntheticBeanBuildItem is the dynamic counterpart to the AdditionalBeanBuildItem. It uses a Recorder to record the bytecode produced by our instance during the Quarkus build phase. This bytecode is provided as-is at runtime to speed up application startup.

Quarkus Extension - Additional Bean Build Item

Mon, 08 Jan 2024 19:36:46 +0100

After discussing the ApplicationIndexBuildItem and CombinedIndexBuildItem, let’s continue exploring Quarkus build items with the AdditionalBeanBuildItem. This build item is part of the configuration items for the Arc library , which handles dependency injection in Quarkus.

Quarkus and Dependency Injection

Quarkus heavily relies on dependency injection, allowing for loose coupling between different objects in a Quarkus application. Quarkus uses a library called Arc that automatically scans the application’s classpath and references all classes declared as beans (e.g., those annotated with @Controller, @Service, etc.) for injection.

In an extension, it may be beneficial to declare objects provided by the extension as beans to make them injectable. An extension might also need to declare objects from the target application or its dependencies as injectable beans, even if they are not annotated with a Quarkus-recognized annotation. This is where AdditionalBeanBuildItem comes into play.

AdditionalBeanBuildItem

This build item is very simple to use in its most basic form, taking the class to be declared as a bean as a parameter.

@BuildStep()
void addBeans(BuildProducer<AdditionalBeanBuildItem> producer) {
    producer.produce(new AdditionalBeanBuildItem("my.package.Foo"));
    // or
    producer.produce(new AdditionalBeanBuildItem(Foo.class));
}

It is often combined with another BuildItem (e.g., CombinedIndexBuildItem) to retrieve the classes to be declared as beans.

By default, only the beans detected as used during the Quarkus build will be retained. This can be configured as follows:

@BuildStep()
void addBeans(BuildProducer<AdditionalBeanBuildItem> producer) {
    producer.produce(AdditionalBeanBuildItem.unremovableOf("my.package.Foo"));
    // or

    producer.produce(AdditionalBeanBuildItem.Builder()
            .addBeanClasses(Foo.class)
            .setUnremovable()); // Will not be removed if not link during compiled time (e.g: Used with reflection)
}

The bean’s scope can also be specified as follows if the class does not specify a scope. According to the documentation, this method should only be used if no annotation can be directly applied to the target class.

@BuildStep()
void addBeans(BuildProducer<AdditionalBeanBuildItem> producer) {
    producer.produce(AdditionalBeanBuildItem.Builder()
            .addBeanClasses(Foo.class)
            .setUnremovable()
            .setDefaultScope(DotNames.APPLICATION_SCOPED));
}

Conclusion

The AdditionalBeanBuildItem is a widely used build item by Quarkus extensions to make their beans injectable in applications using these extensions. The second use case is to make objects from third-party libraries, which are not declared as beans, injectable.

Quarkus Extension - Index Build Item

Mon, 08 Jan 2024 07:32:57 +0100

Quarkus has a very powerful extension system based on the concept of BuildItem. Each BuildItem allows you to configure an extension in a specific way. However, the documentation for these BuildItems is very incomplete. Among the hundreds of BuildItems that exist, I propose to study two of them in this post. Let’s focus on ApplicationIndexBuildItem and CombinedIndexBuildItem.

A Story of Jandex

Quarkus needs to gather information about the application at build time. Jandex allows analyzing and storing metadata of the application’s classes in a jandex.idx file. This file is then used by Quarkus to retrieve information about the classes. This is a significant improvement over using runtime introspection.

Creating a Jandex Index

The simplest way to create a Jandex index is to use the Maven plugin: jandex-maven-plugin.

<build>
    <plugins>
        <plugin>
            <!-- https://github.com/wildfly/jandex-maven-plugin -->
            <groupId>org.jboss.jandex</groupId>
            <artifactId>jandex-maven-plugin</artifactId>
            <version>1.2.3</version>
            <executions>
                <execution>
                    <id>make-index</id>
                    <goals>
                        <!-- phase is 'process-classes' by default -->
                        <goal>jandex</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

The creation of the META-INF/jandex.idx file occurs right after the compilation phase. This prevents the index from being recalculated each time by all the applications using this dependency.

ApplicationIndexBuildItem and CombinedIndexBuildItem

Functionally, these two build items do exactly the same thing: they scan the application. The only difference is that ApplicationIndexBuildItem only scans the application’s classpath, whereas CombinedIndexBuildItem scans both the application’s and its dependencies’ classpath. In practice, CombinedIndexBuildItem is often preferred.

Example

Let’s now see an example of usage:

@BuildStep()
void indexClassPath(ApplicationIndexBuildItem appIndex, CombinedIndexBuildItem fullIndex) {
    // Application classpath scanning
    appIndex.getIndex().getAnnotations(Foo.class)
            .forEach(annotationInstance -> {
                LOG.info(annotationInstance.target.asClass().name());
            });
    // Application + dependencies classpath scanning
    fullIndex.getIndex().getAnnotations(Foo.class)
            .forEach(annotationInstance -> {
                LOG.info(annotationInstance.target.asClass().name());
            });
}

In this example, all classes annotated with @Foo are discovered and printed to the console. Other methods are also available, such as getKnownClasses(), getAllKnownImplementors(), and getAllKnownSubClasses(), which respectively list all classes, those implementing a specific interface, and those extending a particular class.

It is then possible to provide the found classes to other BuildItems to, for example, add these classes as injectable Beans by Quarkus.

@BuildStep()
void indexClassPath(CombinedIndexBuildItem fullIndex, BuildProducer<AdditionalBeanBuildItem> producer) {
    // Application + dependencies classpath scanning
    fullIndex.getIndex().getAnnotations(Foo.class)
            .forEach(annotationInstance -> producer.produce(
                    new AdditionalBeanBuildItem(annotationInstance.target().asClass().name().toString()))
            );
}

Conclusion

ApplicationIndexBuildItem and CombinedIndexBuildItem make it easy to retrieve information about the classes present in the classpath, which can then be used in your extension. This scan is performed during the application’s build via Jandex.