Sync documentation of main branch

Author: actions-user

_data/versioned/main/index/quarkus.yaml

@@ -5,7 +5,7 @@ types:
   - title: Authorization of web endpoints
     filename: security-authorize-web-endpoints-reference.adoc
     summary: Quarkus has an integrated pluggable web security layer.
-    categories: "web, security"
+    categories: "security, web"
     id: security-authorize-web-endpoints-reference
     type: reference
     url: /guides/security-authorize-web-endpoints-reference
@@ -30,7 +30,7 @@ types:
   - title: Configure data sources in Quarkus
     filename: datasource.adoc
     summary: Use a unified configuration model to define data sources for Java Database Connectivity (JDBC) and Reactive drivers.
-    categories: "getting-started, data"
+    categories: "data, getting-started"
     id: datasources
     type: reference
     url: /guides/datasource
@@ -55,7 +55,7 @@ types:
   - title: Logging configuration
     filename: logging.adoc
     summary: "Read about the use of logging API in Quarkus, configuring logging output, and using logging adapters to unify the output from other logging APIs."
-    categories: "observability, getting-started, core"
+    categories: "getting-started, core, observability"
     id: logging
     type: reference
     url: /guides/logging
@@ -159,21 +159,21 @@ types:
   - title: Authentication mechanisms in Quarkus
     filename: security-authentication-mechanisms.adoc
     summary: "The Quarkus Security framework supports multiple authentication mechanisms, which you can use to secure your applications."
-    categories: "web, security"
+    categories: "security, web"
     id: security-authentication-mechanisms
     type: concepts
     url: /guides/security-authentication-mechanisms
   - title: Basic authentication
     filename: security-basic-authentication.adoc
     summary: HTTP Basic authentication is one of the least resource-demanding techniques that enforce access controls to web resources.
-    categories: "web, security"
+    categories: "security, web"
     id: security-basic-authentication
     type: concepts
     url: /guides/security-basic-authentication
   - title: Configuring Well-Known OpenID Connect Providers
     filename: security-openid-connect-providers.adoc
     summary: This document explains how to configure well-known social OIDC and OAuth2 providers.
-    categories: "web, security"
+    categories: "security, web"
     id: security-openid-connect-providers
     type: concepts
     url: /guides/security-openid-connect-providers
@@ -194,21 +194,21 @@ types:
   - title: OpenID Connect (OIDC) Bearer token authentication
     filename: security-oidc-bearer-token-authentication.adoc
     summary: Secure HTTP access to Jakarta REST (formerly known as JAX-RS) endpoints in your application with Bearer token authentication by using the Quarkus OpenID Connect (OIDC) extension.
-    categories: "web, security"
+    categories: "security, web"
     id: security-oidc-bearer-token-authentication
     type: concepts
     url: /guides/security-oidc-bearer-token-authentication
   - title: OpenID Connect authorization code flow mechanism for protecting web applications
     filename: security-oidc-code-flow-authentication.adoc
     summary: "To protect your web applications, you can use the industry-standard OpenID Connect (OIDC) Authorization Code Flow mechanism provided by the Quarkus OIDC extension."
-    categories: "web, security"
+    categories: "security, web"
     id: security-oidc-code-flow-authentication
     type: concepts
     url: /guides/security-oidc-code-flow-authentication
   - title: Proactive authentication
     filename: security-proactive-authentication.adoc
     summary: Proactive authentication is enabled in Quarkus by default.
-    categories: "web, security"
+    categories: "security, web"
     id: security-proactive-authentication
     type: concepts
     url: /guides/security-proactive-authentication
@@ -312,7 +312,7 @@ types:
   - title: Protect a web application by using OpenID Connect (OIDC) authorization code flow
     filename: security-oidc-code-flow-authentication-tutorial.adoc
     summary: "With the Quarkus OpenID Connect (OIDC) extension, you can protect application HTTP endpoints by using the OIDC Authorization Code Flow mechanism."
-    categories: "web, security"
+    categories: "security, web"
     id: security-oidc-code-flow-authentication-tutorial
     type: tutorial
     url: /guides/security-oidc-code-flow-authentication-tutorial
@@ -338,7 +338,7 @@ types:
   - title: Your second Quarkus application
     filename: getting-started-dev-services.adoc
     summary: Discover some of the features that make developing with Quarkus a joyful experience.
-    categories: "getting-started, data, core"
+    categories: "data, getting-started, core"
     id: getting-started-dev-services-tutorial
     type: tutorial
     url: /guides/getting-started-dev-services
@@ -1033,7 +1033,7 @@ types:
   - title: Simplified Hibernate ORM with Panache and Kotlin
     filename: hibernate-orm-panache-kotlin.adoc
     summary: This explains the specifics of using Hibernate ORM with Panache in a Kotlin project.
-    categories: "alt-languages, data"
+    categories: "data, alt-languages"
     type: guide
     url: /guides/hibernate-orm-panache-kotlin
   - title: Simplified Hibernate Reactive with Panache
@@ -1051,7 +1051,7 @@ types:
   - title: Simplified MongoDB with Panache and Kotlin
     filename: mongodb-panache-kotlin.adoc
     summary: This guide covers the usage of MongoDB using active records and repositories in a Kotlin project.
-    categories: "alt-languages, data"
+    categories: "data, alt-languages"
     type: guide
     url: /guides/mongodb-panache-kotlin
   - title: SmallRye Fault Tolerance
@@ -1223,7 +1223,7 @@ types:
   - title: Using SSL With Native Executables
     filename: native-and-ssl.adoc
     summary: "In this guide, we will discuss how you can get your native images to support SSL, as native images don't support it out of the box."
-    categories: "security, native, core"
+    categories: "native, security, core"
     type: guide
     url: /guides/native-and-ssl
   - title: Using Security with .properties File
@@ -1336,13 +1336,13 @@ types:
   - title: Validation with Hibernate Validator
     filename: validation.adoc
     summary: This guide covers how to use Hibernate Validator/Bean Validation in your REST services.
-    categories: "web, data"
+    categories: "data, web"
     type: guide
     url: /guides/validation
   - title: Writing JSON REST Services
     filename: rest-json.adoc
     summary: JSON is now the lingua franca between microservices.
-    categories: "web, serialization"
+    categories: "serialization, web"
     type: guide
     url: /guides/rest-json
   - title: Writing REST Services with RESTEasy Reactive

_generated-doc/main/config/quarkus-all-build-items.adoc

@@ -255,7 +255,7 @@ a| `String name` :: +++<i>No Javadoc found</i>+++
 
 a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedResourceBuildItem.java[`io.quarkus.deployment.builditem.GeneratedResourceBuildItem`, window="_blank"] :: +++<i>No Javadoc found</i>+++
 a| `String name` :: +++<i>No Javadoc found</i>+++
-`byte[] classData` :: +++<i>No Javadoc found</i>+++
+`byte[] data` :: +++<i>No Javadoc found</i>+++
 `boolean excludeFromDevCL` :: +++<i>No Javadoc found</i>+++
 
 a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/builditem/HotDeploymentWatchedFileBuildItem.java[`io.quarkus.deployment.builditem.HotDeploymentWatchedFileBuildItem`, window="_blank"] :: +++Identifies a file from a that, if modified, may result in a hot redeployment when in the dev mode. <p> A file may be identified with an exact location or a matching predicate. See  and . <p> If multiple build items match the same file then the final value of  is computed as a logical OR of all the  values.+++

_versions/main/guides/images/oidc-google-authorized-redirects.png

@@ -542,10 +542,68 @@ Finally,  you need to configure the Google Calendar address and request  the Goo
 
 [source,properties]
 ----
+quarkus.oidc.provider=google
+quarkus.oidc.client-id=<Client ID>
+quarkus.oidc.credentials.secret=<Secret>
+
+# Add a required calendar scope
 quarkus.oidc.authentication.extra-params.scope=https://www.googleapis.com/auth/calendar
+
+# Point REST client to Google Calendar endpoint
 quarkus.rest-client.google-calendar-api.url=https://www.googleapis.com/calendar/v3
 ----
 
+Now you are ready to have users authenticated with Google and support updating their `Google` calendars on their behalf, for example:
+
+[source,java]
+----
+package org.acme.calendar;
+
+import org.eclipse.microprofile.jwt.JsonWebToken;
+import org.eclipse.microprofile.rest.client.inject.RestClient;
+
+import io.quarkus.oidc.IdToken;
+import io.quarkus.security.Authenticated;
+import io.smallrye.mutiny.Uni;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+
+@Path("/calendar")
+@Authenticated
+public class CalendarService {
+
+    @Inject
+    @IdToken
+    JsonWebToken jwt;
+
+    @Inject
+    @RestClient
+    GoogleCalendarClient calendarClient;
+
+    @GET
+    @Path("/event")
+    @Produces("text/plain")
+    public Uni<String> get() {
+        return calendarClient.addEvent(new Event()).onItem()
+           .transform(c -> ("Hello " + jwt.getName() + ", new event: " + c));
+    }
+}
+----
+
+You must update the application registered with the xref:google[Google] provider to list `http://localhost:8080/calendar/event` as one of the authorized redirect URIs if you would like to test this endpoint on the local host, for example:
+
+image::oidc-google-authorized-redirects.png[role="thumb"]
+
+You might also have to register one or more test users:
+
+image::oidc-google-test-users.png[role="thumb"]
+
+Follow the same approach if the endpoint must access other Google services.
+
+The pattern of authenticating with a given provider, where the endpoint uses either an ID token or UserInfo (especially if an OAuth2-only provider such as `GitHub` is used) to get some information about the currently authenticated user and using an access token to access some downstream services (provider or application specific ones) on behalf of this user can be universally applied, irrespectively of which provider is used to secure the application.
+
 == HTTPS Redirect URL
 
 Some providers will only accept HTTPS-based redirect URLs. Tools such as https://ngrok.com/[ngrok] https://linuxhint.com/set-up-use-ngrok/[can be set up] to help testing such providers with Quarkus endpoints running on localhost in devmode.

_versions/main/guides/images/oidc-google-test-users.png

@@ -462,6 +462,73 @@ quarkus.virtual-threads.name-prefix=
 
 ----
 
+== Testing virtual thread applications
+
+As mentioned above, virtual threads have a few limitations that can drastically affect your application performance and memory usage.
+The _junit5-virtual-threads_ extension provides a way to detect pinned carrier threads while running your tests.
+Thus, you can eliminate one of the most prominent limitations or be aware of the problem.
+
+To enable this detection:
+
+* 1) Add the `junit5-virtual-threads` dependency to your project:
+[source, xml]
+----
+<dependency>
+    <groupId>io.quarkus.junit5</groupId>
+    <artifactId>junit5-virtual-threads</artifactId>
+    <scope>test</scope>
+</dependency>
+----
+
+* 2) In your test case, add the `io.quarkus.test.junit5.virtual.VirtualThreadUnit`  and `io.quarkus.test.junit.virtual.ShouldNotPin` annotations:
+[source, java]
+----
+@QuarkusTest
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+@VirtualThreadUnit // Use the extension
+@ShouldNotPin // Detect pinned carrier thread
+class TodoResourceTest {
+    // ...
+}
+----
+
+When you run your test (remember to use Java 21+), Quarkus detects pinned carrier threads.
+When it happens, the test fails.
+
+The `@ShouldNotPin` can also be used on methods directly.
+
+The _junit5-virtual-threads_ also provides a `@ShouldPin` annotation for cases where pinning is unavoidable.
+The following snippet demonstrates the `@ShouldPin` annotation usage and the possibility to inject a `ThreadPinnedEvents` instance in your test to verify when the carrier thread was pinned manually.
+
+[source, java]
+----
+@VirtualThreadUnit // Use the extension
+public class LoomUnitExampleTest {
+
+    CodeUnderTest codeUnderTest = new CodeUnderTest();
+
+    @Test
+    @ShouldNotPin
+    public void testThatShouldNotPin() {
+        // ...
+    }
+
+    @Test
+    @ShouldPin(atMost = 1)
+    public void testThatShouldPinAtMostOnce() {
+        codeUnderTest.pin();
+    }
+
+    @Test
+    public void testThatShouldNotPin(ThreadPinnedEvents events) { // Inject an object to check the pin events
+        Assertions.assertTrue(events.getEvents().isEmpty());
+        codeUnderTest.pin();
+        await().until(() -> events.getEvents().size() > 0);
+        Assertions.assertEquals(events.getEvents().size(), 1);
+    }
+
+}
+----
 
 == Additional references