Mechanism to register Runtime Information which depends on Configuration

[radcortez]

Currently, we have specific configurations that do not necessarily reflect the actual runtime value used by Quarkus. Many configuration names can set specific values that instruct Quarkus to either generate the final value or get the final value by some other means.

A good example is when we set quarkus.http.port=0. What we mean by this is for Quarkus to assign a random port, but how do we communicate the actual real port back to the system? Right now, we override the original config, and consumers have to query the Config system to get the correct value, which is far from ideal, causing many issues:

• Mutating our Config System (which causes inconsistencies depending on when you read the value)
• Lose the original configuration value
• Performance issues because we cannot cache the configuration
• Many workarounds in our code to be able to support the current state

Also, a few related issues:

• Assign random ports at configuration start (not later) #42986
• Test profile config properties can bleed into other test profiles #27996
• Logging configuration leaks from one test to the next #43180
• Support ephemeral ports in dev services config #48784

While the issue with quarkus.http.port is the most visible one, this also affects other properties usually related to CPU, Memory, Threads, and more.

Proposal

Add a new simple API (a poor's man simple JNDI approach :)), where the final runtime values are registered, instead of using the current Config:

int actualPort = event.result().actualPort();
QuarkusRuntime.bind("quarkus.http.port", actualPort);
...
QuarkusRuntime.lookup("quarkus.http.port");

An internal implementation can be backed up by a ConcurrentHashMap. The API may offer methods to list and remove runtime values. This is intended only for extension and is not limited to ports. It can be used to store any runtime information that does not fit in the configuration.

Each runtime value should provide specialized APIs backed by QuarkusRuntime to convey expected behaviors.

Ports

When users need to connect to Quarkus, they often use quarkus.http.host, quarkus.http.port (or configuration expressions). As we described earlier and current issues, this is not desirable.

An alternate proposal is to introduce a naming mechanism that can reference the internal Quarkus service without requiring to know or specify the details. Typically, if we want to connect to a REST endpoint, we use the following:

quarkus.rest-client.EchoClient.url=http://${quarkus.http.host}:${quarkus.http.port}

Instead, we would use:

quarkus.rest-client.EchoClient.url=@{serviceName}

Where serviceName is quarkus-http. This would give us enough information to resolve the address to Quarkus Vert.x HTTP. Each configuration that may take a @{serviceName} must be mapped by a Converter friendly class (SocketAddress?), that uses QuarkusRuntime detailed above to provide the final resolved value. Such Converter could also contain specific code to support the legacy case of http://${quarkus.http.host}:${quarkus.http.port}. Also, it should be possible for the user to keep specifying a plain URL.

As an example, a non-comprehensive list of possible names for Quarkus Services:

• quarkus-http
• quarkus-https
• quarkus-management
• quarkus-grpc
• quarkus-websockets

This should allow us to remove all our current workarounds and make our Configuration immutable. Obviously, this is just a proposal, which we should discuss and figure out if we have other ideas.

[radcortez]

//cc @cescoffier @dmlloyd @gsmet

[dmlloyd]

I'm very glad to see this proposal moving forward (as you know 🙂). Making our configuration properly immutable and solving these use cases well at the same time is very important!

A few unordered points:

• Any service/config/API which binds a socket may be reasonably expected to support multiple socket bindings (for binding to specific network interfaces for example) including binding to multiple ports. The API should be ready to support this (maybe using distinct names for each binding?).
• The port number of the server side of a socket may differ from the port number visible from the client side (for example, when using iptables/nftables or firewall/router rules to remap port 8080 to port 80).
• There are more kinds of things than network ports (or rather, network sockets) that might need to be discovered, read, and/or managed at run time. We could introduce an API just for sockets for now, but it should be possible to evolve this API to support other kinds of things in the future.

One longer point. My gut feeling is that using special configuration layer syntax to reference registered port bindings (when the client and server are in the same application, which is not a common case, right?) is not the right approach and won't scale to new problem domains (in addition to complicating something that is already hideously complex). A structural approach might work better, for example:

quarkus.rest-client.EchoClient.service-binding=serviceName

Better still would be to acknowledge that the server is in the same process as the client and bypass the whole HTTP socket thing completely in this case, but maybe that's magical thinking (or significant misunderstanding).

In WildFly there is a notion of configured socket bindings which is completely separate from the services that are bound, so that both the client and server side of the services would reference the configuration by name. There are a few downsides to this (e.g. the configuration of the socket not living in the same place as the service itself) and a few upsides (everything is uniform and managed centrally, and everything is always named as a consequence of how the configuration stacks together). Not sure if there is anything that can be done with this idea, but maybe it's a useful seed.

Remote service location is related to this but I think that is a separate (more complex) topic of conversation.

[radcortez]

One longer point. My gut feeling is that using special configuration layer syntax to reference registered port bindings (when the client and server are in the same application, which is not a common case, right?) is not the right approach and won't scale to new problem domains (in addition to complicating something that is already hideously complex). A structural approach might work better, for example:

Probably. I was not totally happy with that either, but I wanted to have a way to express and immediately tell by just looking into the configuration that a particular URL, in this case, quarkus.rest-client.EchoClient.url is set to a named service. We could keep .url, so a user can express a plain URL, and add .service-binding to connect to a named service. You can only set one, and we will use the one set.

[cescoffier]

Thanks @radcortez!

A few comments. First, it's not Quarkus that decides the random port (that would be easy); it's the OS, and it's not just 0, but also every negative number (which lets you later reference the random port using the same negative number - this is Vert.x specific).

I'm not sure about the "service" approach. First, the name "service" is confusing and could potentially confuse users.

In Stork, we address a slightly different problem using stork://<service-name> (but here it's a service). We could reuse the same approach, with the built-in interface: stork://quarkus-http (the listed one above). It would be equivalent to David's proposal without introducing a new property, just a different scheme, which then can be configured per profile.

The public/private IP David mentioned is important, too. Unfortunately, without an external service discovery system, it's not possible to retrieve an application's public IP from within the application (except if passed as a parameter somehow, but in general, that data is unknown when we launch the application). Stork can resolve this if the external service discovery is configured.

[radcortez]

A few comments. First, it's not Quarkus that decides the random port (that would be easy); it's the OS, and it's not just 0, but also every negative number (which lets you later reference the random port using the same negative number - this is Vert.x specific).

Yes, correct. The description statement was just a simplification. From a design perspective, the final implementation should not change.

I'm not sure about the "service" approach. First, the name "service" is confusing and could potentially confuse users.

Quarkus Interfaces? Quarkus Networking? Quarkus Stacks? :)

In Stork, we address a slightly different problem using stork://<service-name> (but here it's a service). We could reuse the same approach, with the built-in interface: stork://quarkus-http (the listed one above). It would be equivalent to David's proposal without introducing a new property, just a different scheme, which then can be configured per profile.

Do you suggest using Stork? I also thought about having a quarkus://, and then you could have quarkus://vertx-http, quarkus://vertx-https, and so on.

[dmlloyd]

One thing missing from the summary are the specific use cases (they're implied but not really stated directly). We discussed several, but my memory of our conversation is already fading, as it usually does. Can we list them?

One would be same-VM service discovery as discussed above. Could we get a description of the relevant circumstances? I.e. testing, etc.

One use case could be to centralize logging of socket registration so that there's just one thing that logs new open ports (for example).

One use case could be to have a central point that a service discovery mechanism of some sort (DNS-SD, SLP, or something else) could tie into.

[starksm64]

This seems like a service registry notion more than a naming service notion. The WildFly separation of network bindings from the service is what matches the reality of environments better. Both the transport and protocol are potentially things that are configured independent of a given service and injected into the service.

[cescoffier]

The last point is a Stork limitation - the extension using Stork should know the scheme. In this case, we cannot really assume this anymore. One idea I had a long time ago was to use composed schemas like: http+stork://, but here it won't help much I presume.

[dmlloyd]

Right, URLs are intended to give a concrete location for something (including its hostname and port number). Using the host/port of a URL in an abstract way like this is not in line with the described usage in the RFC. Maybe what we want is a URI instead, particularly a URN which identifies the resource in a spec-compliant way?

[radcortez]

Do you mean ..withAddressList from Stork (or an equivalent API), to take a URI instead of the plain String, to identify the scheme? And return that one by the ServerInstance? Then extensions based on that URI could send you to the right place.

The last point is a Stork limitation - the extension using Stork should know the scheme.

Was this a design decision for a particular reason? Or can we enhance this?

[radcortez]

Ping @cescoffier @dmlloyd

[dmlloyd]

I think phase one can just worry about registering things and making the registry available within a Quarkus application, right? We can worry about magical service discovery in phase 2?

[holly-cummins]

Would all consumers of config need to understand this mechanism and query both config and the new registry to get 'correct' values? Or would consumption of config continue to use the current mechanism?

[dmlloyd]

My concern is that we simply cannot afford to pollute the configuration system anymore. It's already doing way too much. Think of this: the methods on the RuntimeValue thing will have to also know about the current run time context and state from the point of view of any given caller. What does it mean when the system is starting up, shutting down, in dev mode, etc.? We're taking on more complexity and state management than we can handle. I think this design is not going to work well, and when - when - we are compelled to rewrite it, we'll have to break everything and everyone again because the current design is not describable.

And again - you're really assuming that we will always have a 1:1 relationship between configuration and run time values, which is a constraint I'm not sure we want.

Configuration is a golden hammer, and we're going to regret it.

[radcortez]

My concern is that we simply cannot afford to pollute the configuration system anymore. It's already doing way too much. Think of this: the methods on the RuntimeValue thing will have to also know about the current run time context and state from the point of view of any given caller. What does it mean when the system is starting up, shutting down, in dev mode, etc.? We're taking on more complexity and state management than we can handle. I think this design is not going to work well, and when - when - we are compelled to rewrite it, we'll have to break everything and everyone again because the current design is not describable.

RuntimeValue would have only two methods: one to retrieve the configured value and the other to delegate the call to a QuarkusRuntime, which may or may not return a value depending on the current state (we can throw an error if there is no runtime value assigned yet, for instance).

The issue is that we need to find some middle ground here. While I agree it may not be the best solution, I share some of @holly-cummins concerns. If we split them right now without a way to bridge them and with no API breakage, we are going to end up with:

• Calls to configuration that give the "correct" result in some cases, and incorrect results in others
• No way to tell which configuration may have different values at runtime
• Very easy way to mess up when we need to work with such values

Unfortunately, we cannot ignore the status-quo. This has been our approach, and we need to be even more careful moving forward. As you are aware, the concepts of our configuration phases and build time/runtime configuration are still challenging for many users to grasp.

If we don't want to offer a shorthand from the Config objects to get the real runtime value, that is fair enough. I would still recommend declaring these cases explicitly because it would allow us to warn the user about programmatic lookups and signal that the behavior has changed in the API.

And again - you're really assuming that we will always have a 1:1 relationship between configuration and run time values, which is a constraint I'm not sure we want.

It doesn't have to be 1:1. That was just an example.

[radcortez]

BTW @holly-cummins

Spring has a separate API to retrieve the runtime values. Example for port:
https://docs.spring.io/spring-boot/how-to/webserver.html

I couldn't find what happens if you try to query the configuration on the official Spring docs, but this article (which I think we can trust), says that you get a 0 if you set the port to be random: https://www.baeldung.com/spring-boot-running-port

[dmlloyd]

Pragmatism/status quo is never a valid justification for propagating yet more technical debt into this (or any) system. I don't think I'm adequately expressing how problematic this code and its logic already is. I strongly believe that the best time to clear out this technical debt was years ago, but the second-best time is right now. Otherwise there's always going to be just one more problem/use case and it's never going to happen, because the breakage will just grow and grow and the work to resolve it all will grow right along with it.

IMO the config code should no longer be touched or even breathed on, other than critical bug fixes or essential changes, until the rework is done.

[radcortez]

I wrote a small prototype for us to decide the direction (using the port example): c55008c

• A simple QuarkusRuntime with a Map to register runtime values
• A typed key RuntimeKey to carry the value type
• A specific QuarkusWebServer that allows you to read the real runtime values from the Extension (either directly or as a CDI Bean).

My idea is that each extension should offer an API (like they do today for Config), to retrieve the real runtime values It would delegate to QuarkusRuntime to store the real values. It is up to the extension to populate such runtime values. QuarkusRuntime could also offer an API to look up these objects in the same way we do with SmallRyeConfig.

[holly-cummins]

Next question :)

How will we handle priority? In the current mechanism, getOrdinal() can be used to set a priority between different runtime sources. For example, what's making the fix for #48784 hard is that in one test (extensions/redis-client), both dev services and test resources register config for redis endpoints, and we need to be able to say which one 'wins'.

[holly-cummins]

Partially... it would resolve some issues, but not all of them. It would also require us to introduce a way to mutate configuration, because the Config API has no way to mutate configuration. There is a reason why this is done with System Properties, because it is the only source that allows to mutate values (indirectly).

I just want to make sure we’re in sync on the current behaviour. I agree that using system properties as a mechanism for setting config is ugly, so we don’t do it anymore. :)

Or at least, we don’t do it anymore in the new dev services model, which is in the process of being rolled out. Ephemeral ports also work fine. (The reason the fix for ephemeral ports hasn’t been merged is that in some tests, multiple code paths contribute to the same config value, at runtime. I’m having problems finding the right set of priorities to ensure that the one the test expects to win, wins. However, in the proposed model, there’d be no possibility for the failing test to pass.)

For an example of what the switch away from system properties, have a look at the changes in https://github.com/quarkusio/quarkus/blob/main/extensions/amazon-lambda/common-deployment/src/main/java/io/quarkus/amazon/lambda/deployment/DevServicesLambdaProcessor.java. It used to use system properties for setting config, and now it doesn't.

Under the covers, there’s a new DevServicesConfigSource. I assume the intention is that we’d throw all that away. However, I’m not sure how we’d stop extension authors from implementing their own config sources and ruining the purity of the model. Would we put in a hook to throw if someone registers a config source past a certain 'cutoff' point?

[dmlloyd]

Late registration of config sources should be disallowed IMO, so from my perspective, yes we should have such a hook or rule or something.

[radcortez]

We don't support registration of late sources. Sources must be available at Config initialization; everything else is completely ignored.

Now, an extension could create its own Config instance with its own sources, but this is completely disconnected from the Quarkus-registered Config. Or an extension could add a dynamic Source that hooks into some API to update the values automatically. In either case, not much we can do. Eventually, extensions will realize that this won't work properly and will adopt our preferred mechanism.

[holly-cummins]

We don't support registration of late sources. Sources must be available at Config initialization; everything else is completely ignored.

Just to make sure we're on the same page, would what was implemented in #47610 count as late registration? It's working nicely now, so the values are definitely not ignored. :) But it feels like a violation of the spirit of the new proposal, so my assumption is it will be deleted as part of the rework?

[radcortez]

Yes, we are referring to two different things. One thing is the registration of the source itself, and that can only be done when the Config is created (meaning that there is no way to enlist new sources, once a Config is initialized, it requires to create a new Config and replace the old one in the TCCL).

In this case, the source is already part of the Config, and it is the internal implementation of the source that is doing late registration of the value, and there is nothing we can do to prevent such cases, other than advise not to do it :)

While I believe that this is not the case for what you are trying to solve with DevServices, having sources that are mutable cause all sort of issues that we should avoid:

• @ConfigMapping objects are initialized with the Config and cached, since they are expensive to create. If a configuration value provided by a mutable source affects the path of a @ConfigMapping object, the new value will not be reflected in the instance.
• Config#getPropertiesNames is also cached because it is expensive to calculate, so new names will not show up in the list.

[cescoffier]

Hello,

Lazy Runtime Config Discussion

I'll try to summarize this discussion.

The Problem

Some Quarkus configuration properties receive their actual value at runtime (e.g., quarkus.http.port=0 delegates to the OS to assign a random port). Once resolved, these values:

• Mutate the config system, causing inconsistencies depending on when values are read
• Override or lose track of the original configured value
• Break immutability and caching mechanisms
• Introduce complex workarounds across extensions

This issue is not limited to ports—it affects any lazy value.

Proposed Solutions

Solution A – Adding a Quarkus Runtime Registry

Note: This version excludes integration with the config system - only a separate API is considered.

Mechanism:

• Introduce an internal registry (e.g., a ConcurrentHashMap) where runtime values are registered via QuarkusRuntime.bind(...) and retrieved via QuarkusRuntime.lookup(...).
• Optionally use CDI events to notify when values are available.
• The config system is left untouched. Users must explicitly use this API.

⠀
Pros:

• Simple and centralized
• Maintains config immutability
• Avoids config mutation while exposing runtime-resolved data
• Extensible across extensions

⠀
Cons:

• Introduces a second resolution API—users must know when and how to use it
• Assumes a 1:1 mapping between config keys and runtime values, which isn’t always valid

Integrating this directly into the config system would mutate the config and create values that change depending on resolution timing.

Solution B – Service Bindings with Specific Config Syntax

Mechanism:

• Allow config values like quarkus.rest-client.EchoClient.url=@{quarkus-http}
• Resolve named bindings to actual runtime values via a registry
• Optional fallback syntax: .service-binding=serviceName

⠀
Pros:

• Clean separation of client/server resolution
• Preserves immutability by abstracting runtime values

⠀
Cons:

• Syntax may confuse users (.url vs .service-binding)
• Ambiguity: When should the user use the binding vs the direct config value?
• What’s the expected format? Port? Interface:port? scheme://host:port?
• “Service” as a keyword could be misleading
• Supporting existing interpolated config (e.g., ${host}:${port}) is complex

⠀
While elegant, this solution raises both technical and practical concerns.

Solution C – Scheme-Based URIs (Stork-style stork:// or quarkus://)

Mechanism:

• Use URI schemes (e.g., stork://quarkus-http, quarkus://vertx-http) to denote lazy/runtime resolution
• Parsers resolve the scheme dynamically via a registry

⠀
Pros:

• Declarative and explicit about its lazy nature
• Aligns with existing patterns in Stork

⠀
Cons:

• Adds dependency on scheme parsing or Stork-like API (possibly for Quarkus 4)
• Less flexible if multiple schemes or formats are needed
• Do we need separate schemes for internal vs external (e.g., quarkus:// vs stork://)?
• Doesn’t clearly communicate when a value is resolvable
  ⠀

Solution D – Socket Binding Registry (WildFly Style)

Mechanism:

• Inspired by WildFly: socket bindings are named and used by both client and server
• Bindings configured centrally, possibly reused across interfaces

⠀
Pros:

• Clean separation of concerns
• Supports complex setups (e.g., IPv4/IPv6, NAT)

⠀
Cons:

• Adds a new config abstraction layer
• May contradict Quarkus’ philosophy of minimal/simple configuration
• Likely limited to ports and network addresses

⠀
Usage examples would help validate the approach.

Solution E – Two-Phase Plan: Registry First, Discovery Later

This approach limits initial impact and opens the door to broader features in Quarkus 4.

Mechanism:

• Phase 1: Implement runtime value registry (A)
• Phase 2: Introduce discovery/bindings later (C)

⠀
Pros:

• Incremental rollout
• Reduces immediate complexity

⠀
Cons:

• Future evolution might require refactoring if the registry is not designed with forward compatibility in mind

⠀

Summary Table

Solution	Pros	Cons
(A) QuarkusRuntime registry	Simple, centralized, preserves config immutability	Introduces a parallel API; resolution timing issues
(B) Service-binding config syntax	Decouples client/server config, no mutation	Complex syntax; ambiguous use cases; unclear output
(C) URI scheme (stork://, quarkus://)	Declarative, explicit, reuses known patterns	Parsing overhead; unclear lifecycle; dependency concerns
(D) Socket-binding registry (WildFly-style)	Reusable, good for complex network setups	Adds config complexity; may feel out of place in Quarkus
(E) Two-phase plan (A → C)	Allows progressive rollout with minimal risk	Risk of future breaking changes or retrofits

[holly-cummins]

I have a hunch that at least some things put themselves as build-time activities that would more logically be runtime activities because they want that sequencing + chaining.

[holly-cummins]

... on the other hand, I also have a feeling that there's a gravitational pull to move things into runtime because they get dragged there by other things, and for performance + security + footprint reasons, that pull should be resisted. Some of that resistance might include more powerful mechanisms for data flows in the build-time phase, beyond "use runtime config and hope no one notices."

[radcortez]

I think the other thing that would be needed for that to work is some sort of run-time chaining and conditionality mechanism. That would allow the proper sequencing and consumption of output from other parts of the system. The ability to chain is part of the reason dev services work happens at build time. (Or at least, it's one of the benefits, and stuff now depends on it.) So we'd need something like a StartupStep and StartupItem.

In the same way, we have Recorders for the Quarkus app; we can also have a component that consumes build items, but acts in this pre-runtime phase. In this case, both the Quarkus recorder and this pre-runtime phase component could consume the RuntimeConfiguration.

It also probably depends on the cost of the prep. As a user, I'd be mad if I configured a postgres datasource, and my build still insisted on pulling a postgres image down a slow network connection ("you don't need a new postgres! I already have one running and told you about it! how can you not know I told you about it??"). I forget when image pulling happens, and it might already be on container start, so that particular scenario might not be an issue, but there could be similar slownesses and oddities.

Yes, I know. Pulling only happens when you tell the client to start the container, and we don't have the image, so I think it would be ok there. Regarding other preparation steps, we may need to verify. At least for the database services, it is mostly just creating the configuration to start the image.

[radcortez]

... on the other hand, I also have a feeling that there's a gravitational pull to move things into runtime because they get dragged there by other things, and for performance + security + footprint reasons, that pull should be resisted. Some of that resistance might include more powerful mechanisms for data flows in the build-time phase, beyond "use runtime config and hope no one notices."

I understand and I agree, and while some new mechanisms could help, I think the main issue is that the ecosystem and libraries are really hard to split between these phases. Even GraalVM is moving into a more traditional runtime.

[holly-cummins]

+1 New mechanisms might help, but they also increase the complexity even more, and make it harder to explain the Quarkus core principles. "So we have two phases, except actually there's now three, and some crossover between them even with three, and ..."

[radcortez]

Currently these are the pieces that rely in the Configuration to retrieve the running port:

• Services to connect to other services running in the server (REST, GRPC, Websocket)
• GRPC Server to use the same HTTP Server
• DevConsole to open the Dev-UI in the browser
• CORSFilter to write the origin rules
• DEV Services that require scraping the server (like Prometheus)
• Quarkus, when running in remote-dev mode
• Integration tests launchers
• REST Assured
• Arquillian
• Cloud Extensions

There may be more, since there is a lot of indirection going on (via String building, expressions, etc), but it already gives us a good idea of the situation.