From 591bd1599e1873f93bc50c1ff53371b6b975e3c6 Mon Sep 17 00:00:00 2001
From: Martin Kouba <mkouba@redhat.com>
Date: Tue, 10 Oct 2023 13:20:17 +0200
Subject: [PATCH] Config: docs for config value mismatch detection

- follow-up of #36281
---
 .../runtime/annotations/StaticInitSafe.java   |  2 -
 docs/src/main/asciidoc/config-reference.adoc  | 62 +++++++++++++++++++
 2 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/core/runtime/src/main/java/io/quarkus/runtime/annotations/StaticInitSafe.java b/core/runtime/src/main/java/io/quarkus/runtime/annotations/StaticInitSafe.java
index 1e7e956c84743..509e90f235248 100644
--- a/core/runtime/src/main/java/io/quarkus/runtime/annotations/StaticInitSafe.java
+++ b/core/runtime/src/main/java/io/quarkus/runtime/annotations/StaticInitSafe.java
@@ -9,8 +9,6 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
-import org.eclipse.microprofile.config.inject.ConfigProperty;
-
 /**
  * Used to mark a configuration object as safe to be initialized during the STATIC INIT phase.
  * <p>
diff --git a/docs/src/main/asciidoc/config-reference.adoc b/docs/src/main/asciidoc/config-reference.adoc
index 2206592c4f7a9..8879d4d37305d 100644
--- a/docs/src/main/asciidoc/config-reference.adoc
+++ b/docs/src/main/asciidoc/config-reference.adoc
@@ -704,6 +704,68 @@ options exposed by a `org.eclipse.microprofile.config.Config` instance. Which me
 build configuration options since MicroProfile Config specification allows configuration sources not to expose all the property names they provide to users.
 ====
 
+== Config property values injected during static intialization phase
+
+Quarkus collects the config property values injected in CDI beans during xref:writing-extensions.adoc#bootstrap-three-phases[static intialization phase].
+The collected values are then compared with their runtime initialization counterparts and if a mismatch is detected the application startup fails.
+How can it happen?
+For example, let's have a CDI bean `org.acme.MyBean`.
+`MyBean` injects a `@ConfigProperty` of name `foo` and is initialized during the native build.
+The config property does not exist during the native build and so the default value `bar` is used.
+But later, when the application is started the property is defined with a system property: `-Dfoo=baz`.
+This would lead to inconsistent state and unexpected behavior.
+Therefore, Quarkus would fail in this situation by default.
+
+[source,java]
+----
+package org.acme;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.context.Initialized;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+
+@ApplicationScoped
+public class MyBean {
+
+   @ConfigProperty(name = "foo", defaultValue = "bar") <1>
+   String foo;
+
+    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) { <2>
+       // this observer method is notified during STATIC_INIT...
+    }
+}
+----
+<1> The config property is injected when the bean is created and the value is fixed.
+<2> In this particular case, the observer `@Initialized(ApplicationScoped.class)` caused the initialization of the bean. However, there are other possibilities. For example, some extensions initialize components during static intialization phase.
+
+You can annotate an injected field/parameter with `@io.quarkus.runtime.annotations.StaticInitSafe` to mark the injected configuration object as safe to be initialized during the static intialization phase.
+
+[source,java]
+----
+package org.acme;
+
+import jakarta.enterprise.context.ApplicationScoped;
+import jakarta.enterprise.event.Observes;
+import jakarta.enterprise.context.Initialized;
+import org.eclipse.microprofile.config.inject.ConfigProperty;
+import io.quarkus.runtime.annotations.StaticInitSafe;
+
+@ApplicationScoped
+public class MyBeanNoFailure {
+
+   @StaticInitSafe <1>
+   @ConfigProperty(name = "foo", defaultValue = "bar")
+   String foo;
+
+    void onInit(@Observes @Initialized(ApplicationScoped.class) Object event) {
+       // this observer method is notified during STATIC_INIT...
+    }
+}
+----
+<1> Instructs Quarkus not to fail if a mismatch is detected.
+
+
 [[additional-information]]
 == Additional Information