Sync documentation of main branch

Author: actions-user

_data/versioned/main/index/quarkus.yaml

@@ -1903,7 +1903,7 @@ types:
     url: /guides/quarkus-reactive-architecture
   - title: Quarkus Security with Jakarta Persistence
     filename: security-jpa.adoc
-    summary: "Quarkus provides a Jakarta Persistence (formerly known as JPA) identity provider, similar to the JDBC identity provider, suitable for use with the Basic and Form-based Quarkus Security mechanisms, which require a combination of username and password credentials."
+    summary: This guide explains how your application can use Jakarta Persistence to store users identities.
     categories: security
     topics:
     - security

_versions/main/guides/performance-measure.adoc

@@ -14,6 +14,7 @@ This guide covers:
 * how we measure memory usage
 * how we measure startup time
 * which additional flags will Quarkus apply to native-image by default
+* Coordinated omission Problem in Tools
 
 All of our tests are run on the same hardware for a given batch.
 It goes without saying, but it's better when you say it.
@@ -237,3 +238,24 @@ circumstances one could observe non-negligible impact from the other flags too.
 If you're to investigate some differences in detail make sure to check what Quarkus is invoking exactly: when the build
 plugin is producing a native image, the full command lines are logged.
 
+
+== Coordinated Omission Problem in Tools
+
+When measuring performance of a framework like Quarkus the latency experience by users are especially interesting and for that there are many different tools. Unfortunately, many fail to measure the latency correctly and instead fall short and create the Coordinate Omission problem. Meaning tools fails to acoomodate for delays to submit new requests when system is under load and aggregate these numbers making the latency and throughput numbers very misleading.
+
+A good walkthrough of the issue is https://www.youtube.com/watch?v=lJ8ydIuPFeU[this video] where Gil Tene the author of wrk2 explains the issue and https://www.youtube.com/watch?v=xdG8b9iDYbE[Quarkus Insights #22] have John O'Hara from Quarkus performance team show how it can show up.
+
+Although that video and related papers and articles date all back to 2015 then even today you will find tools that fall short with the coordinated oission problem
+
+Tools that at current time of writing is known to excert the problem and should NOT be used for measuring latency/throughput (it may be used for other things):
+
+ * JMeter
+ * wrk
+
+Tools that are known to not be affected are:
+
+ * https://github.com/giltene/wrk2[wrk2]
+ * https://hyperfoil.io[HyperFoil]
+
+Mind you, the tools are not better than your own understanding of what they measure thus even when using `wrk2` or `hyperfoil` make sure you understand what the numbers mean.
+

_versions/main/guides/security-architecture.adoc

@@ -15,14 +15,14 @@ The primary mechanism for securing HTTP applications in Quarkus is the `HttpAuth
 
 == Overview of the Quarkus Security architecture
 
-When a client sends an HTTP request, Quarkus Security orchestrates security authentication and authorization by interacting with several built-in core components including `HttpAuthenticationMechanism`, `IdentityProvider`, and `SecurityIdentityAugmentor`.
+When a client sends an HTTP request, Quarkus Security orchestrates security authentication and authorization by interacting with several built-in core components, including `HttpAuthenticationMechanism`, `IdentityProvider`, and `SecurityIdentityAugmentor`.
 
 The sequential security validation process results in one of three outcomes:
 
-* The HTTP request gets authenticated and authorized and access to the Quarkus application gets granted.
-* The HTTP request authentication fails and the requester receives a challenge specific to the authentication mechanism, for example, a `401` error, a URL redirect to reauthenticate, or some other custom authentication challenge response.
-For some practical examples of challenge responses, see the Quarkus xref:security-customization.adoc[Security Tips and Tricks] guide.
-* The HTTP request authorization fails and the requester gets denied access to the Quarkus application.
+* The HTTP request gets authenticated and authorized, and access to the Quarkus application gets granted.
+* The HTTP request authentication fails, and the requester receives a challenge specific to the authentication mechanism, for example, a `401` error, a URL redirect to reauthenticate, or some other custom authentication challenge response.
+For practical examples of challenge responses, see the Quarkus xref:security-customization.adoc[Security Tips and Tricks] guide.
+* The HTTP request authorization fails, and the requester gets denied access to the Quarkus application.
 
 The following diagram steps through the detailed process flow of the Quarkus Security architecture:
 
@@ -35,9 +35,9 @@ image::security-architecture-overview.png[alt=Quarkus Security architecture proc
 Quarkus Security uses `HttpAuthenticationMechanism` to extract the authentication credentials from the HTTP request and delegates them to `IdentityProvider` to convert the credentials to `SecurityIdentity`.
 For example, the credentials can come from the `Authorization` header, client HTTPS certificates, or cookies.
 
-When an authentication request is rejected by Quarkus Security, `HttpAuthenticationMechanism` sends an authentication challenge back to the client.
+When Quarkus Security rejects an authentication request, `HttpAuthenticationMechanism` returns an authentication challenge to the client.
 The type of challenge depends on the authentication mechanism.
-For example, with the OIDC OpenID Connect (OIDC) Authorization Code Flow mechanism, a redirect URL gets generated and the client is sent back to the OpenID Connect provider to authenticate.
+For example, with the OIDC OpenID Connect (OIDC) Authorization Code Flow mechanism, a redirect URL gets generated, and the client is returned to the OpenID Connect provider to authenticate.
 
 === `IdentityProvider`
 `IdentityProvider` verifies the authentication credentials and maps them to `SecurityIdentity`, which has the username, roles, original authentication credentials, and other attributes.
@@ -49,7 +49,7 @@ In other contexts, it is possible to have other parallel representations of the
 For more information, see the Quarkus xref:security-identity-providers.adoc[Identity providers] guide.
 
 === `SecurityIdentityAugmentor`
-Because Quarkus Security is customizable, for example, you can add authorization roles to `SecurityIdentity`, you can register and prioritize one or more custom security augmentors.
+Because Quarkus Security is customizable, you can, for example, add authorization roles to `SecurityIdentity` and register and prioritize one or more `SecurityAugmentor` implementations.
 
 Registered instances of `SecurityIdentityAugmentor` are invoked during the final stage of the security authentication process.
 For more information, see the xref:security-customization.adoc#security-identity-customization[Security Identity Customization] section of the "Security Tips and Tricks" guide.
@@ -58,7 +58,7 @@ For more information, see the xref:security-customization.adoc#security-identity
 == Supported authentication mechanisms
 
 The Quarkus Security framework supports multiple authentication mechanisms, which can also be combined.
-Some supported authentication mechanisms are built into Quarkus, while others require you to add an extension. 
+Some supported authentication mechanisms are built into Quarkus, while others require you to add an extension.
 
 To learn about security authentication in Quarkus and the supported mechanisms and protocols, see the Quarkus xref:security-authentication-mechanisms.adoc[Authentication mechanisms in Quarkus] guide.
 

_versions/main/guides/security-jpa.adoc

@@ -7,14 +7,15 @@ https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 = Quarkus Security with Jakarta Persistence
 include::_attributes.adoc[]
 :categories: security
+:summary: This guide explains how your application can use Jakarta Persistence to store users identities.
 :topics: security,identity-providers,sql,database,jpa,jdbc
 :extensions: io.quarkus:quarkus-security-jpa-reactive
 
 Quarkus provides a Jakarta Persistence (formerly known as JPA) identity provider, similar to the xref:security-jdbc.adoc[JDBC identity provider], suitable for use with the xref:security-basic-authentication.adoc[Basic] and xref:security-authentication-mechanisms.adoc#form-auth[Form-based] Quarkus Security mechanisms, which require a combination of username and password credentials.
 
 The Jakarta Persistence `IdentityProvider` creates a `SecurityIdentity` instance, which is used during user authentication to verify and authorize access requests making your Quarkus application secure.
 
-For an example of practical use of Basic authentication and Jakarta Persistence, see the xref:security-basic-authentication-tutorial.adoc[Secure a Quarkus application with Basic authentication and Jakarta Persistence] tutorial.
+For an example of practical use of Basic authentication and Jakarta Persistence, see the xref:security-getting-started-tutorial.adoc[Getting Started with Security using Basic authentication and Jakarta Persistence] tutorial.
 
 
 == Jakarta Persistence entity specification
@@ -111,19 +112,24 @@ public class User extends PanacheEntity {
 public class Role extends PanacheEntity {
 
     @ManyToMany(mappedBy = "roles")
-    public List<ExternalRolesUserEntity> users;
+    public List<User> users;
 
     @RolesValue
     public String role;
 }
 ----
 
+[NOTE]
+====
+The example shows how to store and access the roles, but if there's a need to update the existing user or create a new user. There will be a need to annotate `public List<Role> roles` with `@Cascade(CascadeType.ALL)` or select the specific type of `CascadeType`.
+====
+
 == Password storage and hashing
 
 When developing applications with Quarkus, you can decide how to manage password storage and hashing. You can choose to keep the default password and hashing settings of Quarkus, or you can hash passwords manually.
 
 With the default option, passwords are stored and hashed with https://en.wikipedia.org/wiki/Bcrypt[bcrypt] under the
-https://en.wikipedia.org/wiki/Crypt_(C)[Modular Crypt Format] (MCF).
+https://en.wikipedia.org/wiki/Crypt_\(C)[Modular Crypt Format] (MCF).
 While using MCF, the hashing algorithm, iteration count, and salt are stored as a part of the hashed value.
 As such, we do not need dedicated columns to keep them.
 
@@ -132,14 +138,23 @@ As such, we do not need dedicated columns to keep them.
 In cryptography, a salt is a name for random data used as an additional input to a one-way function that hashes data, a password, or a passphrase.
 ====
 
-To represent passwords stored in the database which were hashed using different hashing algorithms, create a class that implements `org.wildfly.security.password.PasswordProvider` as shown in the example below.
+To represent passwords stored in the database which were hashed using different hashing algorithms, create a class that implements `io.quarkus.security.jpa.PasswordProvider` as shown in the example below.
 
 The following snippet shows how to set a custom password provider that represents a password which was hashed with the SHA256 hashing algorithm.
 
 [source,java]
 ----
-import org.wildfly.security.password.Password;
-import org.wildfly.security.password.PasswordProvider;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+import io.quarkus.security.jpa.Password;
+import io.quarkus.security.jpa.PasswordType;
+import io.quarkus.security.jpa.Roles;
+import io.quarkus.security.jpa.UserDefinition;
+import io.quarkus.security.jpa.Username;
 
 @UserDefinition
 @Table(name = "test_user")
@@ -160,6 +175,16 @@ public class CustomPasswordUserEntity {
     @Roles
     public String role;
 }
+----
+
+[source,java]
+----
+import jakarta.xml.bind.DatatypeConverter;
+
+import org.wildfly.security.password.Password;
+import org.wildfly.security.password.interfaces.SimpleDigestPassword;
+
+import io.quarkus.security.jpa.PasswordProvider;
 
 public class CustomPasswordProvider implements PasswordProvider {
     @Override