Sync documentation of main branch

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

@@ -9598,6 +9598,10 @@ _No Javadoc found_
 
 _No Javadoc found_
 
+`io.quarkus.websockets.next.deployment.Callback onPingMessage` 
+
+_No Javadoc found_
+
 `io.quarkus.websockets.next.deployment.Callback onPongMessage` 
 
 _No Javadoc found_

_versions/main/guides/datasource.adoc

@@ -294,6 +294,19 @@ AgroalDataSource defaultDataSource;
 In the above example, the type is `AgroalDataSource`, a `javax.sql.DataSource` subtype.
 Because of this, you can also use `javax.sql.DataSource` as the injected type.
 
+===== Oracle considerations
+
+As documented in https://github.com/quarkusio/quarkus/issues/36265[issue #36265],
+Oracle has a very weird behavior of committing the uncommitted transactions on connection closing.
+
+Which means that when stopping Quarkus for instance, in progress transactions might be committed even if incomplete.
+
+Given that is not the expected behavior and that it could lead to data loss, we added an interceptor that rolls back any unfinished transactions at connection close,
+provided you are not using XA (in which case the transaction manager handles things for you).
+
+If this behavior introduced in 3.18 causes issues for your specific workload, you can disable it by setting the `-Dquarkus-oracle-no-automatic-rollback-on-connection-close` system property to `true`.
+Please take the time to report your use case in our https://github.com/quarkusio/quarkus/issues[issue tracker] so that we can adjust this behavior if needed.
+
 [[reactive-datasource]]
 ==== Reactive datasource
 

_versions/main/guides/deploying-to-kubernetes.adoc

@@ -301,7 +301,7 @@ of secret that contains the required credentials. Quarkus can automatically gene
 quarkus.kubernetes.generate-image-pull-secret=true
 ----
 
-More specifically a `Secret`like the one bellow is genrated:
+More specifically a `Secret` like the one below is generated:
 
 [source,yaml]
 ----

_versions/main/guides/kubernetes-client.adoc

@@ -474,49 +474,43 @@ public class OpenShiftClientProducer {
 }
 ----
 
-Mock support is also provided in a similar fashion:
+Mock support is also provided in a similar fashion by using the `@WithKubernetesTestServer` explained in the previous section:
 
 [source, java]
 ----
-@QuarkusTestResource(OpenShiftMockServerTestResource.class)
+@WithKubernetesTestServer
 @QuarkusTest
 public class OpenShiftClientTest {
 
-    @MockServer
-    private OpenShiftMockServer mockServer;
-...
-----
-
-Or by using the `@WithOpenShiftTestServer` similar to the `@WithKubernetesTestServer` explained in the
-previous section:
-
-[source, java]
-----
-@WithOpenShiftTestServer
-@QuarkusTest
-public class OpenShiftClientTest {
+    @KubernetesTestServer
+    KubernetesServer mockServer;
+    @Inject
+    OpenShiftClient client;
 
-    @OpenShiftTestServer
-    private OpenShiftServer mockOpenShiftServer;
-...
+    @Test
+    public void testInteractionWithAPIServer() {
+        RestAssured.when().get("/route/test").then()
+                .body("size()", is(2));
+    }
+}
 ----
 
-To use this feature, you have to add a dependency on `quarkus-test-openshift-client`:
+To use this feature, you have to add a dependency on `quarkus-test-kubernetes-client`:
 
 [source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
 .pom.xml
 ----
 <dependency>
     <groupId>io.quarkus</groupId>
-    <artifactId>quarkus-test-openshift-client</artifactId>
+    <artifactId>quarkus-test-kubernetes-client</artifactId>
     <scope>test</scope>
 </dependency>
 ----
 
 [source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
 .build.gradle
 ----
-testImplementation("io.quarkus:quarkus-test-openshift-client")
+testImplementation("io.quarkus:quarkus-test-kubernetes-client")
 ----
 
 == Configuration Reference

_versions/main/guides/security-webauthn.adoc

@@ -1179,6 +1179,7 @@ import io.quarkus.test.security.webauthn.WebAuthnEndpointHelper;
 import io.quarkus.test.security.webauthn.WebAuthnHardware;
 import io.restassured.RestAssured;
 import io.restassured.filter.Filter;
+import io.restassured.filter.cookie.CookieFilter;
 import io.restassured.specification.RequestSpecification;
 import io.vertx.core.json.JsonObject;
 
@@ -1207,7 +1208,7 @@ public class WebAuthnResourceTest {
     }
     
     private void testWebAuthn(String username, User user, Endpoint endpoint) {
-        Filter cookieFilter = new RenardeCookieFilter();
+        Filter cookieFilter = new CookieFilter();
         WebAuthnHardware token = new WebAuthnHardware(url);
 
         verifyLoggedOut(cookieFilter);

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

@@ -79,7 +79,7 @@ implementation("io.quarkus:quarkus-websockets-next")
 
 Both the <<server-api>> and <<client-api>> define _endpoints_ that are used to consume and send messages.
 The endpoints are implemented as CDI beans and support injection.
-Endpoints declare <<callback-methods,_callback methods_>> annotated with `@OnTextMessage`, `@OnBinaryMessage`, `@OnPong`, `@OnOpen`, `@OnClose` and `@OnError`.
+Endpoints declare <<callback-methods,_callback methods_>> annotated with `@OnTextMessage`, `@OnBinaryMessage`, `@OnPingMessage`, `@OnPongMessage`, `@OnOpen`, `@OnClose` and `@OnError`.
 These methods are used to handle various WebSocket events.
 Typically, a method annotated with `@OnTextMessage` is called when the connected client sends a message to the server and vice versa.
 
@@ -210,6 +210,7 @@ A WebSocket endpoint may declare:
 
 * At most one `@OnTextMessage` method: Handles the text messages from the connected client/server.
 * At most one `@OnBinaryMessage` method: Handles the binary messages from the connected client/server.
+* At most one `@OnPingMessage` method: Handles the ping messages from the connected client/server.
 * At most one `@OnPongMessage` method: Handles the pong messages from the connected client/server.
 * At most one `@OnOpen` method: Invoked when a connection is opened.
 * At most one `@OnClose` method: Executed when the connection is closed.
@@ -551,39 +552,55 @@ Item find(Item item) {
 1. Specify the codec to use for the deserialization of the incoming message
 2. Specify the codec to use for the serialization of the outgoing message
 
-=== Ping/pong messages
+=== Ping/Pong messages
 
 A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2[ping message] may serve as a keepalive or to verify the remote endpoint.
 A https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3[pong message] is sent in response to a ping message and it must have an identical payload.
 
-Server/client endpoints automatically respond to a ping message sent from the client/server.
-In other words, there is no need for `@OnPingMessage` callback declared on an endpoint.
+==== Sending ping messages
 
-The server can send ping messages to a connected client.
-`WebSocketConnection`/`WebSocketClientConnection` declare methods to send ping messages; there is a non-blocking variant: `sendPing(Buffer)` and a blocking variant: `sendPingAndAwait(Buffer)`.
-By default, the ping messages are not sent automatically.
-However, the configuration properties `quarkus.websockets-next.server.auto-ping-interval` and `quarkus.websockets-next.client.auto-ping-interval` can be used to set the interval after which, the server/client sends a ping message to a connected client/server automatically.
+Ping messages are optional and not sent by default. However, server and client endpoints can be configured to automatically send ping messages on an interval.
 
 [source,properties]
 ----
 quarkus.websockets-next.server.auto-ping-interval=2 <1>
+quarkus.websockets-next.client.auto-ping-interval=10 <2>
 ----
-<1> Sends a ping message from the server to a connected client every 2 seconds.
+<1> Sends a ping message from the server to each connected client every 2 seconds.
+<2> Sends a ping message from all connected client instances to their remote servers every 10 seconds.
 
-The `@OnPongMessage` annotation is used to define a callback that consumes pong messages sent from the client/server.
-An endpoint must declare at most one method annotated with `@OnPongMessage`.
+Servers and clients can send ping messages programmatically at any time using `WebSocketConnection` or `WebSocketClientConnection`.
+There is a non-blocking variant: `Sender#sendPing(Buffer)` and a blocking variant: `Sender#sendPingAndAwait(Buffer)`.
+
+==== Sending pong messages
+
+Server and client endpoints will always respond to a ping message sent from the remote party with a corresponding pong message, using the application data from the ping message.
+This behavior is built-in and requires no additional code or configuration.
+
+Servers and clients can send unsolicited pong messages that may serve as a unidirectional heartbeat using `WebSocketConnection` or `WebSocketClientConnection`. There is a non-blocking variant: `Sender#sendPong(Buffer)` and a blocking variant: `Sender#sendPongAndAwait(Buffer)`.
+
+==== Handling ping/pong messages
+
+Because ping messages are handled automatically and pong messages require no response, it is not necessary to write handlers for these messages to comply with the WebSocket protocol.
+However, it is sometimes useful to know when ping or pong messages are received by an endpoint.
+
+The `@OnPingMessage` and `@OnPongMessage` annotations can be used to define callbacks that consume ping or pong messages sent from the remote party.
+An endpoint may declare at most one `@OnPingMessage` callback and at most  one `@OnPongMessage` callback.
 The callback method must return either `void` or `Uni<Void>` (or be a Kotlin `suspend` function returning `Unit`), and it must accept a single parameter of type `Buffer`.
 
 [source,java]
 ----
+@OnPingMessage
+void ping(Buffer data) {
+    // an incoming ping that will automatically receive a pong
+}
+
 @OnPongMessage
 void pong(Buffer data) {
-    // ....
+    // an incoming pong in response to the last ping sent
 }
 ----
 
-NOTE: The server/client can also send unsolicited pong messages that may serve as a unidirectional heartbeat. There is a non-blocking variant: `WebSocketConnection#sendPong(Buffer)` and also a blocking variant: `WebSocketConnection#sendPongAndAwait(Buffer)`.
-
 [[inbound-processing-mode]]
 === Inbound processing mode