WG - Dev Services Lifecycle

[cescoffier]

This working group proposal is an outcome of the WG - Unified Dev Service - Brainstorming · quarkusio quarkus · Discussion #47307. This is closely related to the [Test Classloading working group] (WG - Test classloading).

Objective:

This working group's main objective is to define and implement a consistent lifecycle model for Dev Services.

The Problem

The current Dev Services lifecycle has inconsistencies:

• Dev Services are started during the augmentation phase, despite being pre-runtime constructs. This is causing an issue with the new Test ClassLoading effort.
• Dev Services are not reused between modes (dev, test) or even between test runs, causing unnecessary startup times and friction in iterative workflows. It should be a choice.
• Dev Services may be shared between profiles, but the control over that is not great
• There’s no clear boundary between what is kept alive, restarted, or disposed of across development sessions.
• The lifecycle logic is embedded in various places.

These issues degrade the developer experience.

The proposed Solution

This working group will define and implement a proper lifecycle for Dev Services with the following strategic goals:

• Move Dev Services startup to a pre-runtime phase (after the augmentation phase, but before the actual start of the application), ensuring alignment with their intended usage. This work has already been started.
• Support reusing Dev Services globally across dev and test modes — including reuse between test runs when enabled.
• Clearly document and implement container/service teardown behavior to avoid runtime leaks and unintended resource retention.
• Define discoverability and sharing rules (e.g., shared vs isolated services) with minimal configuration burden. Currently, the “shared” default depends on the dev service.
• Maintain boundaries by avoiding orchestration features, but allow complementary approaches like our Docker Compose integration.

Definition of Done

The working group will be considered complete when the following are delivered:

• ADR defining the Dev Services lifecycle model, including reuse and startup rules.
• Implementation of runtime-only startup for Dev Services and deprecation of augmentation-based initialization.
• Support for reusing Dev Services across modes and test executions (configurable)
• Clear sharing rules
• Updated documentation covering lifecycle behavior and new reuse capabilities.
• Improve the development model to easily create dev service following this new lifecycle

Out of Scope:

• Dev Service orchestration (e.g., dependency graphs, lifecycle sequencing of multiple services).
• Non-lifecycle-related feature additions or individual Dev Service improvements. Some tasks have already been scheduled but won’t be part of this working group.

Organizing the Work

1. Communication and Transparency:

• GitHub issues and discussions in the main Quarkus repository.
• Work will primarily occur in the Quarkus core repo, with possible touchpoints in Quarkiverse extensions if needed (for Quarkiverse extension defining dev services).

2. Points of Contact:

• @ozangunalp, @holly-cummins

Note

A large part of this working group is covered by:
#45785

[cescoffier]

Board created: WG - Dev Services Lifecycle

[albers]

Maintain boundaries by avoiding orchestration features, but allow complementary approaches like our Docker Compose integration.
Out of Scope:
Dev Service orchestration (e.g., dependency graphs, lifecycle sequencing of multiple services).

I have a use case where a dev service needs to connect to a database container at startup, preferredly using dynamic ports.

The use case in question is the Quarkus Azure Service Bus Extension (docs) (src), which features an Azure Service Bus emulator that depends on a database container.

With the old dev services implementation, I was able to start and connect the containers with code basically like

        MSSQLServerContainer<?> database = new MSSQLServerContainer<>(databaseImageName);
		ServiceBusEmulatorContainer emulator = new ServiceBusEmulatorContainer(emulatorImageName)
			.withMsSqlServerContainer(database);
		emulator.start();

I could not figure out how to to this with the new approach.
Am I missing something here?
Any help would be appreciated.

[holly-cummins]

Got it! What you want is the serviceConfig() method. I've raised #51257 to add some javadoc explaining it, but the method probably needs a whole new name, because it's the opposite of obvious that "controlling reuse" is what it's for. The idea is that if you want your service to be restarted when the config is different, and re-used otherwise, pass through your config. If you want it to be always restarted, you could pass through something like a random number. If you want the service to be never restarted, you could either not set it (although that might NPE if you're unlucky), or set it to a constant.

Actually, thinking about it more, I think the 'never restarted' case might be what got diluted away when the plan hit reality. But always restarted should work. Please let me know if it doesn't!

[albers]

if you want your service to be restarted when the config is different, and re-used otherwise

This is perfect for restarts triggered by a config change.

But in addition to this, I also want the service to restart if a config file that was mounted into the container changed.
In the latter case, the config was not modified.
I assume that the "config" is a MP config interface representing the properties for dev service configuration.

[albers]

One solution could be not to use the config directly but wrapped in some container (a map or record) where I can also store, say, a serial number that tracks the number of config file changes. The serial number would then be passed between restarts in the LiveReloadBuildItem's context object and incremented when the watched file changed.

[holly-cummins]

As you say, the thing passed in to serviceconfig can be any object you like. So I think your suggestion is good; I'd perhaps have a set where one entry is the config object passed in from Microprofile, and the other is a string hash of your config file. Or it could be the whole contents of the config file. Or a timestamp. It just needs to be comparable.

[albers]

@holly-cummins I opted for the timestamp. It gets updated and stored in the LiveReloadBuildItem's context whenever the watched config file is among LiveReloadBuildItem.getChangedResources(). This way I do not have to read the config file again on every producer method invocation. I packed the service config and the timestamp in a record which I called RelaunchControllingConfig for clarity reasons.
For reference, here's the PR with the solution: quarkiverse/quarkus-azure-services#466
Thank you very much for your support.