Merge branch 'main' into QDOCS-114-Annotations-for-Quarkus-endpoints

.github/quarkus-github-bot.yml

@@ -547,7 +547,7 @@ triage:
  - id: resteasy-reactive
  labels: [area/resteasy-reactive]
  title: resteasy.reactive
- notify: [geoand, FroMage, stuartwdouglas]
+ notify: [geoand, FroMage, stuartwdouglas, Sgitario]
  directories:
  - extensions/resteasy-reactive/
  - id: scala

.github/workflows/jdk-early-access-build.yml

@@ -10,7 +10,7 @@ on:
  description: 'JDK version'
  required: true
  # make sure to keep the matrix entries (see below) in sync!
- default: '20'
+ default: '21'
  jdkDistribution:
  description: 'JDK distribution'
  required: true
@@ -44,7 +44,8 @@ jobs:
  && format( '{{ "include": [{{ "version": "{0}", "dist": "{1}" }}] }}',
  github.event.inputs.jdkVersion, github.event.inputs.jdkDistribution )
  || '{ "include": [{ "version": 19, "dist": "jdk.java.net" },
- { "version": 20, "dist": "jdk.java.net" }] }'
+ { "version": 20, "dist": "jdk.java.net" },
+ { "version": 21, "dist": "jdk.java.net" }] }'
  )
  }}
  if: "github.repository == 'quarkusio/quarkus' || github.event_name == 'workflow_dispatch'"

bom/application/pom.xml

@@ -142,7 +142,7 @@
  <reactive-streams.version>1.0.3</reactive-streams.version>
  <jboss-logging.version>3.5.0.Final</jboss-logging.version>
  <mutiny.version>1.8.0</mutiny.version>
- <kafka3.version>3.3.1</kafka3.version>
+ <kafka3.version>3.3.2</kafka3.version>
  <lz4.version>1.8.0</lz4.version> <!-- dependency of the kafka-clients that could be overridden by other imported BOMs in the platform -->
  <snappy.version>1.1.8.4</snappy.version>
  <strimzi-test-container.version>0.100.0</strimzi-test-container.version>

core/deployment/src/main/java/io/quarkus/deployment/pkg/PackageConfig.java

@@ -11,27 +11,82 @@
 @ConfigRoot
 public class PackageConfig {
 
- public static final String JAR = "jar";
- public static final String UBER_JAR = "uber-jar";
- public static final String FAST_JAR = "fast-jar";
- public static final String MUTABLE_JAR = "mutable-jar";
+ /**
+ * @deprecated Use {@link Type#JAR} instead
+ */
+ @Deprecated
+ public static final String JAR = BuiltInType.JAR.name;
+ /**
+ * @deprecated Use {@link Type#UBER_JAR} instead
+ */
+ @Deprecated
+ public static final String UBER_JAR = BuiltInType.UBER_JAR.name;
+ /**
+ * @deprecated Use {@link Type#FAST_JAR} instead
+ */
+ @Deprecated
+ public static final String FAST_JAR = BuiltInType.FAST_JAR.name;
+ /**
+ * @deprecated Use {@link Type#MUTABLE_JAR} instead
+ */
+ @Deprecated
+ public static final String MUTABLE_JAR = BuiltInType.MUTABLE_JAR.name;
  /**
  * @deprecated use 'legacy-jar' instead
  */
  @Deprecated
- public static final String LEGACY = "legacy";
- public static final String LEGACY_JAR = "legacy-jar";
- public static final String NATIVE = "native";
+ public static final String LEGACY = BuiltInType.LEGACY.name;
+ /**
+ * @deprecated Use {@link Type#LEGACY_JAR} instead
+ */
+ @Deprecated
+ public static final String LEGACY_JAR = BuiltInType.LEGACY_JAR.name;
+ /**
+ * @deprecated Use {@link Type#NATIVE} instead
+ */
+ @Deprecated
+ public static final String NATIVE = BuiltInType.NATIVE.name;
+ /**
+ * @deprecated Use {@link Type#NATIVE_SOURCES} instead
+ */
+ @Deprecated
  // does everything 'native' but stops short of actually executing the 'native-image' command
- public static final String NATIVE_SOURCES = "native-sources";
+ public static final String NATIVE_SOURCES = BuiltInType.NATIVE_SOURCES.name;
+
+ public enum BuiltInType {
+ JAR("jar"),
+ UBER_JAR("uber-jar"),
+ FAST_JAR("fast-jar"),
+ MUTABLE_JAR("mutable-jar"),
+ /**
+ * @deprecated use {@link #LEGACY_JAR} instead
+ */
+ @Deprecated
+ LEGACY("legacy"),
+ LEGACY_JAR("legacy-jar"),
+ NATIVE("native"),
+ // does everything 'native' but stops short of actually executing the 'native-image' command
+ NATIVE_SOURCES("native-sources");
+
+ private final String name;
+
+ private BuiltInType(final String name) {
+ this.name = name;
+ }
+
+ @Override
+ public String toString() {
+ return name;
+ }
+ }
 
  /**
  * The requested output type.
  * <p>
  * The default built in types are 'jar' (which will use 'fast-jar'), 'legacy-jar' for the pre-1.12 default jar
- * packaging, 'uber-jar', 'native' and 'native-sources'.
+ * packaging, 'uber-jar', 'mutable-jar' (for remote development mode), 'native' and 'native-sources'.
  */
- @ConfigItem(defaultValue = JAR)
+ @ConfigItem(defaultValue = "jar")
  public String type;
 
  /**

docs/src/main/asciidoc/qute-reference.adoc

@@ -1386,16 +1386,20 @@ class MyBean {
 <2> The `Location` qualifier instructs the container to inject a template from a path relative from `src/main/resources/templates`. In this case, the full path is `src/main/resources/templates/detail/items2_v1.html`. 
 <3> Inject the configured `Engine` instance.
 
-It's also possible to contribute to the engine configuration via a CDI observer method.
+=== Engine Customization
+
+Additional components can be registered manually via `EngineBuilder` methods in a CDI observer method at runtime:
 
-.`EngineBuilder` Observer Example
 [source,java]
 ----
 import io.quarkus.qute.EngineBuilder;
 
 class MyBean {
 
  void configureEngine(@Observes EngineBuilder builder) {
+ // Add a custom section helper
+ builder.addSectionHelper(new CustomSectionFactory());
+ // Add a custom value resolver
  builder.addValueResolver(ValueResolver.builder()
  .appliesTo(ctx -> ctx.getBase() instanceof Long && ctx.getName().equals("tenTimes"))
  .resolveSync(ctx -> (Long) ec.getBase() * 10)
@@ -1404,8 +1408,52 @@ class MyBean {
 }
 ----
 
+However, in this particular case the section helper factory is ignored during validation at build time.
+If you want to register a section that participates in validation of templates at build time then use the convenient `@EngineConfiguration` annotation:
+
+[source,java]
+----
+import io.quarkus.qute.EngineConfiguration;
+import io.quarkus.qute.SectionHelper;
+import io.quarkus.qute.SectionHelperFactory;
+
+@EngineConfiguration <1>
+public class CustomSectionFactory implements SectionHelperFactory<CustomSectionHelper> {
+
+ @Inject
+ Service service; <2>
+
+ @Override
+ public List<String> getDefaultAliases() {
+ return List.of("custom");
+ }
+
+ @Override
+ public SectionHelper initialize(SectionInitContext context) {
+ if (context.getParameter("foo") == null) {
+ throw new IllegalStateException("Foo param not found"); <3>
+ }
+ return new CustomSectionHelper();
+ }
+
+ class CustomSectionHelper implements SectionHelper {
+
+ @Override
+ public CompletionStage<ResultNode> resolve(SectionResolutionContext context) {
+ return CompletableFuture.completedStage(new SingleResultNode(service.getValue(), null)); <4>
+ }
+ }
+}
+----
+<1> A `SectionHelperFactory` annotated with `@EngineConfiguration` is used during validation of templates at build time and automatically registered at runtime (a) as a section factory and (b) as a CDI bean.
+<2> A CDI bean instance is used at runtime - this means that the factory can define injection points
+<3> Validate that `foo` parameter is always present; e.g. `{#custom foo='bar' /}` is ok but `{#custom /}` results in a build failure.
+<4> Use the injected `Service` during rendering.
+
+The `@EngineConfiguration` annotation can be also used to register ``ValueResolver``s and ``NamespaceResolver``s.
+
 [[template-locator-registration]]
-=== Template Locator Registration
+==== Template Locator Registration
 
 The easiest way to register <<template-locator,template locators>> is to make them CDI beans.
 As the custom locator is not available during the build time when a template validation is done, you need to disable the validation via the `@Locate` annotation.

docs/src/main/asciidoc/security-basic-authentication-tutorial.adoc

@@ -3,7 +3,7 @@
 include::_attributes.adoc[]
 :categories: security, getting-started
 
-Secure your Quarkus application endpoints by combining xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider to enable role-based access control (RBAC). 
+Secure your Quarkus application endpoints by combining xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider to enable role-based access control (RBAC).
 The JPA `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.
 
 This tutorial prepares you for implementing more advanced security mechanisms in Quarkus, for example, how to use the OpenID Connect (OIDC) authentication mechanism.
@@ -18,7 +18,7 @@ To demonstrate different authorization policies, the steps in this tutorial guid
 
 [cols="20%,40% ",options="header"]
 |===
-|Endpoint | Description 
+|Endpoint | Description
 |`/api/public`| The `/api/public` endpoint can be accessed anonymously.
 |`/api/admin`| The `/api/admin` endpoint is protected with role-based access control (RBAC), and only users who have been granted the `admin` role can access it.
 At this endpoint, the `@RolesAllowed` annotation enforces the access constraint declaratively.
@@ -183,7 +183,7 @@ public class User extends PanacheEntity {
  public String password;
  @Roles <4>
  public String role;
- 
+
  /**
  * Adds a new user to the database
  * @param username the username
@@ -217,7 +217,7 @@ The `security-jpa` extension initializes only if there is a single entity annota
 +
 [NOTE]
 ====
-When secure access is required and no other authentication mechanisms are enabled, xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] is the fallback authentication mechanism. 
+When secure access is required and no other authentication mechanisms are enabled, xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] is the fallback authentication mechanism.
 Therefore, in this tutorial, you do not need to set the property `quarkus.http.auth.basic=true`.
 ====
 +
@@ -285,7 +285,7 @@ Add the integration tests before you run your application in production mode.
 
 Use xref:https://quarkus.io/guides/dev-services#databases[Dev Services for PostgreSQL] for the integration testing of your application in JVM and native modes.
 
-The following properties configuration demonstrates how you can enable PostgreSQL testing to run in production (`prod`) mode only. 
+The following properties configuration demonstrates how you can enable PostgreSQL testing to run in production (`prod`) mode only.
 In this scenario, `Dev Services for PostgreSQL` launches and configures a `PostgreSQL` test container.
 
 [source,properties]
@@ -373,7 +373,7 @@ As you can see in this code sample, you do not need to start the test container
 [NOTE]
 ====
 If you start your application in dev mode, `Dev Services for PostgreSQL` launches a `PostgreSQL` `devmode` container so that you can start developing your application.
-While developing your application, you can also start to add tests one by one and run them by using the xref:continuous-testing.adoc[Continuous Testing] feature. 
+While developing your application, you can also start to add tests one by one and run them by using the xref:continuous-testing.adoc[Continuous Testing] feature.
 `Dev Services for PostgreSQL` supports testing while you develop by providing a separate `PostgreSQL` test container that does not conflict with the `devmode` container.
 ====
 
@@ -415,7 +415,7 @@ Run the application:
 
 === Access and test the application security
 
-When your application is running, you can access your application by using one of the following `curl` commands. 
+When your application is running, you can access your application by using one of the following `curl` commands.
 You can also access the same endpoint URLs by using a browser.
 
 * Connect to a protected endpoint anonymously:
@@ -536,7 +536,7 @@ public class Role extends PanacheEntity {
 
 === Password storage and hashing
 
-By default, passwords are stored and hashed by using https://en.wikipedia.org/wiki/Bcrypt[bcrypt] under the 
+By default, passwords are stored and hashed by using https://en.wikipedia.org/wiki/Bcrypt[bcrypt] under the
 https://en.wikipedia.org/wiki/Crypt_(C)[Modular Crypt Format] (MCF).
 
 When creating a hashed password, you can use the convenient `String BcryptUtil.bcryptHash(String password)` function, which defaults to creating a random salt and hashing in 10 iterations.
@@ -585,17 +585,17 @@ For applications running in production, do not store passwords in plain text.
 Congratulations!
 You have learned how to create and test a secure Quarkus application by combining the xref:security-built-in-authentication-support-concept.adoc#basic-auth[Quarkus built-in basic HTTP authentication] with the JPA identity provider.
 
-After you have completed this tutorial, explore some of the more advanced security mechanisms in Quarkus. 
+After you have completed this tutorial, explore some of the more advanced security mechanisms in Quarkus.
 Use the following information to learn how you can securely use `OpenID Connect` to provide secure single sign-on access to your Quarkus endpoints:
 
-* xref:security-openid-connect.adoc[Using OpenID Connect (OIDC) to Protect Service Applications using Bearer Token Authorization]
+* xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication]
 * xref:security-openid-connect-web-authentication.adoc[Using OpenID Connect (OIDC) to Protect Web Applications using Authorization Code Flow
 ]
 
 == References
 
 * xref:security-overview-concept.adoc[Quarkus Security overview]
-* xref:security-openid-connect.adoc[Using OpenID Connect (OIDC) to Protect Service Applications using Bearer Token Authorization]
+* xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication]
 * xref:security-openid-connect-web-authentication.adoc[Using OpenID Connect (OIDC) to Protect Web Applications using Authorization Code Flow
 ]
 * xref:hibernate-orm-panache.adoc[Simplified Hibernate ORM with Panache]

docs/src/main/asciidoc/security-jwt-build.adoc

@@ -346,6 +346,6 @@ SmallRye JWT supports the following properties which can be used to customize th
 * link:https://tools.ietf.org/html/rfc7516[JSON Web Encryption]
 * link:https://tools.ietf.org/html/rfc7518[JSON Web Algorithms]
 * link:https://bitbucket.org/b_c/jose4j/wiki/Home[Jose4J]
-* xref:security-openid-connect.adoc[Using OpenID Connect to Protect Service Applications]
+* xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication]
 * xref:security-jwt.adoc[Using Smallrye JWT to Protect Service Applications]
 * xref:security-overview-concept.adoc[Quarkus Security overview]

docs/src/main/asciidoc/security-jwt.adoc

@@ -14,7 +14,7 @@ This guide explains how your Quarkus application can utilize https://github.com/
 to verify https://tools.ietf.org/html/rfc7519[JSON Web Token]s, represent them as MicroProfile JWT `org.eclipse.microprofile.jwt.JsonWebToken`
 and provide secured access to the Quarkus HTTP endpoints using Bearer Token Authorization and https://en.wikipedia.org/wiki/Role-based_access_control[Role-Based Access Control].
 
-NOTE: Quarkus OpenID Connect `quarkus-oidc` extension also supports Bearer Token Authorization and uses `smallrye-jwt` to represent the bearer tokens as `JsonWebToken`, please read the xref:security-openid-connect.adoc[Using OpenID Connect to Protect Service Applications] guide for more information.
+NOTE: Quarkus OpenID Connect `quarkus-oidc` extension also supports Bearer Token Authorization and uses `smallrye-jwt` to represent the bearer tokens as `JsonWebToken`, please read the xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication] guide for more information.
 OpenID Connect extension has to be used if the Quarkus application needs to authenticate the users using OIDC Authorization Code Flow, please read xref:security-openid-connect-web-authentication.adoc[Using OpenID Connect to Protect Web Applications] guide for more information.
 
 == Prerequisites
@@ -291,7 +291,7 @@ quarkus.native.resources.includes=publicKey.pem #<3>
 <1> We are setting public key location to point to a classpath publicKey.pem location. We will add this key in part B, <<Adding a Public Key>>.
 <2> We are setting the issuer to the URL string `https://example.com/issuer`.
 <3> We are including the public key as a resource in the native executable.
- 
+
 === Adding a Public Key
 
 The https://tools.ietf.org/html/rfc7519[JWT specification] defines various levels of security of JWTs that one can use.
@@ -795,7 +795,7 @@ Please see xref:security-openid-connect-client.adoc#token-propagation[Token Prop
 [[integration-testing-wiremock]]
 ==== Wiremock
 
-If you configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-openid-connect.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Wiremock` section but only change the `application.properties` to use MP JWT configuration properties instead:
+If you configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-authentication-concept.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Wiremock` section but only change the `application.properties` to use MP JWT configuration properties instead:
 
 [source, properties]
 ----
@@ -807,7 +807,7 @@ mp.jwt.verify.issuer=${keycloak.url}/realms/quarkus
 [[integration-testing-keycloak]]
 ==== Keycloak
 
-If you work with Keycloak and configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-openid-connect.adoc#integration-testing-keycloak[OpenID Connect Bearer Token Integration testing] Keycloak section but only change the `application.properties` to use MP JWT configuration properties instead:
+If you work with Keycloak and configure `mp.jwt.verify.publickey.location` to point to HTTPS or HTTP based JsonWebKey (JWK) set then you can use the same approach as described in the xref:security-oidc-bearer-authentication-concept.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] Keycloak section but only change the `application.properties` to use MP JWT configuration properties instead:
 
 [source, properties]
 ----
@@ -835,7 +835,7 @@ mp.jwt.verify.issuer=${client.quarkus.oidc.auth-server-url}
 [[integration-testing-public-key]]
 ==== Local Public Key
 
-You can use the same approach as described in the xref:security-openid-connect.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Local Public Key` section but only change the `application.properties` to use MP JWT configuration properties instead:
+You can use the same approach as described in the xref:security-oidc-bearer-authentication-concept.adoc#integration-testing[OpenID Connect Bearer Token Integration testing] `Local Public Key` section but only change the `application.properties` to use MP JWT configuration properties instead:
 
 [source, properties]
 ----

docs/src/main/asciidoc/security-keycloak-admin-client.adoc

@@ -202,6 +202,6 @@ include::{generated-dir}/config/quarkus-keycloak-admin-client.adoc[leveloffset=+
 * https://www.keycloak.org/documentation.html[Keycloak Documentation]
 * xref:security-keycloak-authorization.adoc[Keycloak Authorization extension]
 * xref:security-openid-connect-web-authentication.adoc[Using OpenID Connect to Protect Web Application]
-* xref:security-openid-connect.adoc[Using OpenID Connect to Protect Service Applications]
+* xref:security-oidc-bearer-authentication-concept.adoc[OIDC Bearer authentication]
 * xref:security-openid-connect-client.adoc[OpenID Connect Client and Token Propagation Quickstart]
 * xref:security-overview-concept.adoc[Quarkus Security overview]