Sync documentation of main branch

Author: actions-user

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

@@ -32,10 +32,12 @@ _No Javadoc found_
 a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/builditem/AdditionalClassLoaderResourcesBuildItem.java[`io.quarkus.deployment.builditem.AdditionalClassLoaderResourcesBuildItem`, window="_blank"]
 [.description]
 --
-_No Javadoc found_
+A build item that allows extensions to register additional resources that should be available from the ClassLoader at runtime. 
+These resources are typically generated or discovered during the build process and are not located in the standard `src/main/resources` directory. Multiple instances of this build item can be produced, and all registered resources will be aggregated. 
+The key of the map represents the resource path (e.g., `META-INF/my-config.properties` ), and the value is the byte content of the resource.
 -- a|`java.util.Map<String,byte[]> resources` 
 
-_No Javadoc found_
+A map where keys are resource paths and values are the corresponding resource content as byte arrays.
 
 
 

_versions/main/guides/apicurio-registry-dev-services.adoc

@@ -79,3 +79,19 @@ You can select any 2.x version from https://hub.docker.com/r/apicurio/apicurio-r
 ----
 quarkus.apicurio-registry.devservices.image-name=apicurio/apicurio-registry-mem:latest-snapshot
 ----
+
+[[Compose]]
+== Compose
+
+The Apicurio Dev Services supports xref:compose-dev-services.adoc[Compose Dev Services].
+It relies on a `compose-devservices.yml`, such as:
+
+[source,yaml]
+----
+name: <application name>
+services:
+  apicurio:
+    image: apicurio/apicurio-registry-mem:2.4.2.Final
+    ports:
+      - "8080"
+----

_versions/main/guides/compose-dev-services.adoc

@@ -558,6 +558,7 @@ In the example above:
 The mapped properties will contain the host port that is mapped to the container port,
 which may be different from the container port if you're using dynamic port mapping (e.g., `- '5432'` instead of `- '7432:5432'`).
 
+[[exposing-port-mappings-to-running-containers]]
 ==== Exposing port mappings to running containers
 
 In some cases, containers need to know the host ports they're mapped to at runtime.

_versions/main/guides/databases-dev-services.adoc

@@ -294,6 +294,43 @@ In the labels tab, we see that Quarkus added the datasource label, which can be
 Dev Services have been started.
 ====
 
+[[Compose]]
+== Compose
+
+The Database Dev Services supports xref:compose-dev-services.adoc[Compose Dev Services].
+It relies on a `compose-devservices.yml`, such as:
+
+[source,yaml]
+----
+name: <application name>
+services:
+  postgresql:
+    image: docker.io/postgres:17
+    ports:
+      - "5432"
+    environment:
+      POSTGRES_USER: quarkus
+      POSTGRES_PASSWORD: quarkus
+      POSTGRES_DB: quarkus
+  oracle:
+    image: docker.io/gvenzl/oracle-free:23-slim-faststart
+    ports:
+      - "1521"
+    environment:
+      ORACLE_PASSWORD: quarkus
+      ORACLE_DATABASE: quarkus
+      APP_USER: quarkus
+      APP_USER_PASSWORD: quarkus
+  mssql:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    ports:
+      - "1433"
+    environment:
+      ACCEPT_EULA: "Y"
+      MSSQL_SA_PASSWORD: Quarkus123
+    labels:
+      io.quarkus.devservices.compose.jdbc.parameters: trustServerCertificate=true
+----
 
 [[configuration-reference]]
 == Configuration Reference

_versions/main/guides/kafka-dev-services.adoc

@@ -122,6 +122,41 @@ quarkus.kafka.devservices.redpanda.transaction-enabled=false
 
 NOTE: Redpanda transactions does not support exactly-once processing.
 
+[[Compose]]
+== Compose
+
+The Kafka Dev Services supports xref:compose-dev-services.adoc[Compose Dev Services].
+It relies on a `compose-devservices.yml`, such as:
+
+[source,yaml]
+----
+name: <application name>
+services:
+  kafka:
+    image: apache/kafka-native:3.9.0
+    restart: "no"
+    ports:
+      - '9092'
+    labels:
+      io.quarkus.devservices.compose.exposed_ports: /etc/kafka/docker/ports
+    environment:
+      KAFKA_NODE_ID: 1
+      KAFKA_PROCESS_ROLES: broker,controller
+      KAFKA_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
+      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
+      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
+      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
+      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
+      KAFKA_NUM_PARTITIONS: 3
+    command: "/kafka.sh"
+    volumes:
+      - './kafka.sh:/kafka.sh'
+----
+
+For the broker to advertise its externally accessible address to clients, it requires an additional file `kafka.sh` as described in xref:compose-dev-services.adoc#exposing-port-mappings-to-running-containers[Exposing port mappings to running containers].
+
 [[configuration-reference-devservices]]
 == Configuration reference
 

_versions/main/guides/mongodb-dev-services.adoc

@@ -29,6 +29,22 @@ The default service name is `mongodb`.
 Sharing is enabled by default in dev mode, but disabled in test mode.
 You can disable the sharing with `quarkus.mongodb.devservices.shared=false`.
 
+[[Compose]]
+== Compose
+
+The MongoDB Dev Services supports xref:compose-dev-services.adoc[Compose Dev Services].
+It relies on a `compose-devservices.yml`, such as:
+
+[source,yaml]
+----
+name: <application name>
+services:
+  mongo:
+    image: docker.io/mongo:7.0
+    ports:
+      - "27017"
+----
+
 == Configuration reference
 
 include::{generated-dir}/config/quarkus-mongodb-client_quarkus.mongodb.devservices.adoc[opts=optional, leveloffset=+1]

_versions/main/guides/websockets-next-reference.adoc

@@ -1070,6 +1070,101 @@ When you plan to use bearer access tokens during the opening WebSocket handshake
 * Use a custom WebSocket ticket system which supplies a random token with the HTML page which hosts the JavaScript WebSockets client which must provide this token during the initial handshake request as a query parameter.
 ====
 
+Before the bearer access token sent on the initial HTTP request expires, you can send a new bearer access token as part of a message and update current `SecurityIdentity` attached to the WebSocket server connection:
+
+[source, java]
+----
+package io.quarkus.websockets.next.test.security;
+
+import io.quarkus.security.Authenticated;
+import io.quarkus.security.identity.SecurityIdentity;
+import io.quarkus.websockets.next.OnTextMessage;
+import io.quarkus.websockets.next.WebSocket;
+import io.quarkus.websockets.next.WebSocketSecurity;
+import jakarta.inject.Inject;
+
+@Authenticated
+@WebSocket(path = "/end")
+public class Endpoint {
+
+    record Metadata(String token) {}
+    record RequestDto(Metadata metadata, String message) {}
+
+    @Inject
+    SecurityIdentity securityIdentity;
+
+    @Inject
+    WebSocketSecurity webSocketSecurity;
+
+    @OnTextMessage
+    String echo(RequestDto request) {
+        if (request.metadata != null && request.metadata.token != null) {
+            webSocketSecurity.updateSecurityIdentity(request.metadata.token); <1>
+        }
+        String principalName = securityIdentity.getPrincipal().getName(); <2>
+        return request.message + " " + principalName;
+    }
+
+}
+----
+<1> Asynchronously update the `SecurityIdentity` attached to the WebSocket server connection.
+<2> The current `SecurityIdentity` instance is still available and can be used during the `SecurityIdentity` update.
+
+The xref:security-oidc-bearer-token-authentication.adoc[OIDC Bearer token authentication] mechanism has builtin support for the `SecurityIdentity` update.
+If you use other authentication mechanisms, you must implement the `io.quarkus.security.identity.IdentityProvider` provider that supports the `io.quarkus.websockets.next.runtime.spi.security.WebSocketIdentityUpdateRequest` authentication request.
+
+[IMPORTANT]
+====
+The new bearer access token must have the same `sub` claim value as the token used during the initial HTTP request.
+Please also make sure the `SecurityIdentity` is only updated when necessary and the WebSocket message with credentials do not appear in your application logs.
+Always use the `wss` protocol to enforce encrypted HTTP connection via TLS when sending credentials as part of the WebSocket message.
+====
+
+WebSocket client application have to send a new access token before previous one expires:
+
+[source,html]
+----
+<script type="module">
+    import Keycloak from 'https://cdn.jsdelivr.net/npm/[email protected]/lib/keycloak.js'
+    const keycloak = new Keycloak({
+        url: 'http://localhost:39245',
+        realm: 'quarkus',
+        clientId: 'websockets-js-client'
+    });
+    function getToken() {
+        return keycloak.token
+    }
+
+    await keycloak
+        .init({onLoad: 'login-required'})
+        .then(() => console.log('User is now authenticated.'))
+        .catch(err => console.log('User is NOT authenticated.', err));
+
+    // open Web socket - reduced for brevity
+    let connectionOpened = true;
+    const subprotocols = [ "quarkus", encodeURI("quarkus-http-upgrade" + "#Authorization#Bearer " + getToken()) ]
+    const socket = new WebSocket("wss://" + location.host + "/chat/username", subprotocols);
+
+    setInterval(() => {
+        keycloak
+            .updateToken(15)
+            .then(result => {
+                if (result && connectionOpened) {
+                    console.log('Token updated, sending new token to the server')
+                    socket.send(JSON.stringify({
+                        metadata: {
+                            token: `${getToken()}`
+                        }
+                    }));
+                }
+            })
+            .catch(err => console.error(err))
+    }, 10000);
+</script>
+----
+
+Complete example is located in the `security-openid-connect-websockets-next-quickstart` link:{quickstarts-tree-url}/security-openid-connect-websockets-next-quickstart[directory].
+
 === Inspect and/or reject HTTP upgrade
 
 To inspect an HTTP upgrade, you must provide a CDI bean implementing the `io.quarkus.websockets.next.HttpUpgradeCheck` interface.