Sync documentation of main branch

_data/versioned/main/index/quarkus.yaml

@@ -633,6 +633,11 @@ types:
     id: security-basic-authentication-howto
     type: howto
     url: /guides/security-basic-authentication-howto
+  - title: Frequently asked questions about writing extensions
+    filename: extension-faq.adoc
+    id: extensions-faq
+    type: howto
+    url: /guides/extension-faq
   - title: Quarkus Security with Jakarta Persistence
     filename: security-jpa.adoc
     summary: You can configure your application to use Jakarta Persistence to store users' identities.

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

@@ -4071,7 +4071,9 @@ a| [[quarkus-core_quarkus-console-color]] [.property-path]##link:#quarkus-core_q
 
 [.description]
 --
-If color should be enabled or disabled. If this is not present then an attempt will be made to guess if the terminal supports color
+If color should be enabled or disabled.
+
+If this is not present then an attempt will be made to guess if the terminal supports color
 
 
 ifdef::add-copy-button-to-env-var[]
@@ -4683,9 +4685,9 @@ a| [[quarkus-core_quarkus-log-level]] [.property-path]##link:#quarkus-core_quark
 [.description]
 --
 The log level of the root category, which is used as the default log level for all categories.
-
+<p>
 JBoss Logging supports Apache-style log levels:
-
+<p>
 * {@link org.jboss.logmanager.Level#FATAL}
 * {@link org.jboss.logmanager.Level#ERROR}
 * {@link org.jboss.logmanager.Level#WARN}
@@ -5355,8 +5357,8 @@ a| [[quarkus-core_quarkus-log-syslog-block-on-reconnect]] [.property-path]##link
 
 [.description]
 --
-Enables or disables blocking when attempting to reconnect a `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++TCP
-TCP` or `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++SSL_TCP SSL TCP` protocol
+Enables or disables blocking when attempting to reconnect a `Protocol++#++TCP
+TCP` or `Protocol++#++SSL_TCP SSL TCP` protocol
 
 
 ifdef::add-copy-button-to-env-var[]
@@ -6044,8 +6046,8 @@ a| [[quarkus-core_quarkus-log-handler-syslog-syslog-handlers-block-on-reconnect]
 
 [.description]
 --
-Enables or disables blocking when attempting to reconnect a `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++TCP
-TCP` or `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++SSL_TCP SSL TCP` protocol
+Enables or disables blocking when attempting to reconnect a `Protocol++#++TCP
+TCP` or `Protocol++#++SSL_TCP SSL TCP` protocol
 
 
 ifdef::add-copy-button-to-env-var[]
@@ -51752,7 +51754,7 @@ a| [[quarkus-narayana-jta_quarkus-transaction-manager-shorten-node-name-if-neces
 
 [.description]
 --
-Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes.
+Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes, encoded to Base64 format and then shortened to 28 bytes.
 
 
 ifdef::add-copy-button-to-env-var[]

_generated-doc/main/config/quarkus-core_quarkus.console.adoc

@@ -66,7 +66,9 @@ a| [[quarkus-core_quarkus-console-color]] [.property-path]##link:#quarkus-core_q
 
 [.description]
 --
-If color should be enabled or disabled. If this is not present then an attempt will be made to guess if the terminal supports color
+If color should be enabled or disabled.
+
+If this is not present then an attempt will be made to guess if the terminal supports color
 
 
 ifdef::add-copy-button-to-env-var[]

_generated-doc/main/config/quarkus-core_quarkus.log.adoc

@@ -63,9 +63,9 @@ a| [[quarkus-core_quarkus-log-level]] [.property-path]##link:#quarkus-core_quark
 [.description]
 --
 The log level of the root category, which is used as the default log level for all categories.
-
+<p>
 JBoss Logging supports Apache-style log levels:
-
+<p>
 * {@link org.jboss.logmanager.Level#FATAL}
 * {@link org.jboss.logmanager.Level#ERROR}
 * {@link org.jboss.logmanager.Level#WARN}
@@ -735,8 +735,8 @@ a| [[quarkus-core_quarkus-log-syslog-block-on-reconnect]] [.property-path]##link
 
 [.description]
 --
-Enables or disables blocking when attempting to reconnect a `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++TCP
-TCP` or `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++SSL_TCP SSL TCP` protocol
+Enables or disables blocking when attempting to reconnect a `Protocol++#++TCP
+TCP` or `Protocol++#++SSL_TCP SSL TCP` protocol
 
 
 ifdef::add-copy-button-to-env-var[]
@@ -1424,8 +1424,8 @@ a| [[quarkus-core_quarkus-log-handler-syslog-syslog-handlers-block-on-reconnect]
 
 [.description]
 --
-Enables or disables blocking when attempting to reconnect a `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++TCP
-TCP` or `org.jboss.logmanager.handlers.SyslogHandler.Protocol++#++SSL_TCP SSL TCP` protocol
+Enables or disables blocking when attempting to reconnect a `Protocol++#++TCP
+TCP` or `Protocol++#++SSL_TCP SSL TCP` protocol
 
 
 ifdef::add-copy-button-to-env-var[]

_generated-doc/main/config/quarkus-narayana-jta.adoc

@@ -28,7 +28,7 @@ a| [[quarkus-narayana-jta_quarkus-transaction-manager-shorten-node-name-if-neces
 
 [.description]
 --
-Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes.
+Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes, encoded to Base64 format and then shortened to 28 bytes.
 
 
 ifdef::add-copy-button-to-env-var[]

_generated-doc/main/config/quarkus-narayana-jta_quarkus.transaction-manager.adoc

@@ -28,7 +28,7 @@ a| [[quarkus-narayana-jta_quarkus-transaction-manager-shorten-node-name-if-neces
 
 [.description]
 --
-Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes.
+Whether the node name should be shortened if necessary. The node name must not exceed a length of 28 bytes. If this property is set to `true`, and the node name exceeds 28 bytes, the node name is shortened by calculating the link:https://en.wikipedia.org/wiki/SHA-2[SHA-224] hash, which has a length of 28 bytes, encoded to Base64 format and then shortened to 28 bytes.
 
 
 ifdef::add-copy-button-to-env-var[]

_versions/main/guides/cdi-reference.adoc

@@ -113,7 +113,7 @@ quarkus.index-dependency.<name>.artifact-id=(this one is optional)
 quarkus.index-dependency.<name>.classifier=(this one is optional)
 ----
 
-TIP: If no `artifact-id` is specified then all dependencies with the specificed `group-id` are indexed.
+TIP: If no `artifact-id` is specified then all dependencies with the specified `group-id` are indexed.
 
 For example, the following entries ensure that the `org.acme:acme-api` dependency is indexed:
 

_versions/main/guides/extension-faq.adoc

@@ -0,0 +1,97 @@
+////
+This document is maintained in the main Quarkus repository
+and pull requests should be submitted there:
+https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
+////
+[id="extensions-faq"]
+= Frequently asked questions about writing extensions
+include::_attributes.adoc[]
+:diataxis-type: howto
+:categories: extensions
+////
+:extension-status: preview
+TODO: uncomment the above for experimental or tech-preview content.
+The document header ends at the first blank line. Do not remove the blank line between the header and the abstract summary.
+////
+
+## Should you write an extension?
+
+### Why would I want to write an extension?
+
+See the xref:writing-extensions#extension-philosophy[extension philosophy].
+
+One useful thing extensions can do is bundle other extensions.
+Have a look at the link:https://quarkus.io/extensions/io.quarkiverse.microprofile/quarkus-microprofile/[Quarkus MicroProfile extension] for an example of aggregator extensions.
+
+### Are there cases an extension isn't necessary?
+
+Not every problem needs an extension!
+ If you're just bundling up external libraries (that aren't already extensions) and making minor adjustments, you might not need an extension.
+ For example, plain libraries can create new configuration elements and register classes with Jandex (this link:https://www.loicmathieu.fr/wordpress/en/informatique/quarkus-tip-comment-ne-pas-creer-une-extension-quarkus/[blog shows how]).
+
+
+## Bytecode transformation
+
+### How can I change the code of things on the classpath?
+
+A `BytecodeTransformerBuildItem` can be used to manipulate bytecode.
+For example, see this link:https://quarkus.io/blog/solving-problems-with-extensions/[blog about removed problematic bridge methods from a dependency].
+
+## CDI
+
+### I'm working with CDI, and I don't know how to ...
+
+The xref:cdi-integration.adoc[CDI integration guide] presents solutions to a number of CDI-related use cases for extension authors.
+
+### I have transformed a user class to add an injected field, but CDI isn't working
+
+What happens if an extension transforms a user class using `BytecodeTransformerBuildItem`, and replaces `@jakarta.annotation.Resource` with `@jakarta.inject.Inject`? The field will not be injected by Arc.
+Debugging will show the transformed class being loaded in the app, but it looks like Arc doesn't see the new code.
+
+Arc-related transformations should generally be done with link:https://github.com/quarkusio/quarkus/blob/main/extensions/arc/deployment/src/main/java/io/quarkus/arc/deployment/AnnotationsTransformerBuildItem.java[AnnotationsTransformerBuildItem].
+The reason is that _all_ Quarkus's bytecode transformations are done after Jandex indexing. This means changes are never reflected back in Jandex.
+
+Most extensions use Jandex as a source of truth to find out what to do. Those extensions won't see new/modified endpoints in the bytecode itself.
+The solution to this limitation is annotation transformers. You should also be aware that while Arc and Quarkus REST honour annotation transformers, not all extensions do.
+
+### Something in my classpath has @Inject annotations, which are confusing CDI. How can I fix that?
+
+You will need to implement an `AnnotationsTransformer` and strip out out the problematic injection sites. (Remember, if the use case involves CDI, it needs to be an `AnnotationsTransformer`, not a BytecodeTransformer`.) See link:https://quarkus.io/blog/solving-problems-with-extensions-2/[this blog] about on using an `AnnotationsTransformer` extension to clean non `@Inject` annotations from the Airline library so that it can be used in CDI-enabled runtimes.
+
+## Cross-cutting concerns
+
+### How can I redirect application logging to an external service?
+
+A `LogHandlerBuildItem` is a convenient way to redirect application logs. See this link:https://quarkus.io/blog/quarkus-aws-cloudwatch_extension/[worked example of an extension which directs output to AWS CloudWatch].
+
+## Build and hosting infrastructure for extensions
+
+### Can I use Gradle to build my extension?
+
+Yes, but it's not the most typical pattern.
+See the xref:building-my-first-extension.adoc#gradle-setup[Building Your First Extension Guide] for instructions on setting up a Gradle extension. Have a look at the link:https://quarkus.io/extensions/org.jobrunr/quarkus-jobrunr/[JobRunr extension] for an example implementation.
+
+### If I want my extension to be in code.quarkus.io, does it have to be in the Quarkiverse GitHub org?
+
+Registering an extension in the catalog is independent from where the source code is.
+The link:https://hub.quarkiverse.io[quarkiverse repository] has some shortcuts to make releasing and testing extensions easier, but any extension can link:https://hub.quarkiverse.io/checklistfornewprojects/#make-your-extension-available-in-the-tooling[register into the catalog].
+
+### My extension isn't showing up on extensions.quarkus.io
+
+Every extension in the link:https://github.com/quarkusio/quarkus-extension-catalog/tree/main/extensions[extension catalog] should appear in http://code.quarkus.io, http://extensions.quarkus.io, and the command line tools.
+The web pages at http://extensions.quarkus.io are refreshed a few times a delay, so there may be a delay in new extensions showing up there.
+To debug a missing extension, first:
+
+- Check your extension is present in link:https://central.sonatype.com/[Maven Central]
+- Check the extension is included the link:https://github.com/quarkusio/quarkus-extension-catalog/tree/main/extensions[extensions catalog list] (it only needs to be included once, and future versions will be automatically detected)
+- Check if the extension is listed in the http://https://registry.quarkus.io/q/swagger-ui/#/Client/get_client_extensions_all[Quarkus registry] list of all known extensions
+- Check if there has been a green link:https://github.com/quarkusio/extensions/actions/workflows/build_and_publish.yml[build of the extensions site] since updating the catalog
+
+## Other topics
+
+
+### What's the difference between a quickstart and a codestart?
+
+Both codestarts and quickstarts are designed to help users get coding quickly.
+A codestarts is a generated application and a quickstart is browsable source code.
+Codestarts allow the creation of customised apps, which makes them quite powerful.

_versions/main/guides/grpc-generation-reference.adoc

@@ -297,3 +297,56 @@ To enable this feature, set the `quarkus.generate-code.grpc.use-arg-file` proper
 
 If you are on Windows, and the command line exceeds 8190 characters, Quarkus automatically uses an argument file to pass the arguments to the `protoc` command.
 
+== Local vs. Downloaded `protoc`
+
+To generate gRPC classes, Quarkus uses the `protoc` artifact from the `com.google.protobuf` group id.
+However, to ensure the support of various platforms, Quarkus automatically downloads _all_ the possible variants of the `protoc` artifact.
+In addition, Quarkus downloads both `protoc` and the plugin used to generate gRPC classes in Java.
+For example, even if you are using Linux, Quarkus downloads the `protoc` and the Java plugin artifacts for Windows and MacOS.
+
+The next table lists the different variants of the `protoc` and plugin artifacts:
+
+[col="1,1, 1"]
+|===
+| *Platform* | *Classifier* | *Dependencies*
+
+| Linux/ARM64 | `linux-aarch_64` | `com.google.protobuf:protoc:VERSION:exe:linux-aarch_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-aarch_64`
+| Linux/Power PC 64 bits | `linux-ppcle_64` | `com.google.protobuf:protoc:VERSION:exe:linux-ppcle_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-ppcle_64`
+| Linux/S390 64 bits | `linux-s390_64` | `com.google.protobuf:protoc:VERSION:exe:linux-s390_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-s390_64`
+| Linux/x86 32bits | `linux-x86_32` | `com.google.protobuf:protoc:VERSION:exe:linux-x86_32` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-x86_32`
+| Linux/x86 64bits | `linux-x86_64` | `com.google.protobuf:protoc:VERSION:exe:linux-x86_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:linux-x86_64`
+| Mac osx/ARM64 | `osx-aarch_64` | `com.google.protobuf:protoc:VERSION:exe:osx-aarch_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:osx-aarch_64`
+| Mac osx/x86 64bits | `osx-x86_64` | `com.google.protobuf:protoc:VERSION:exe:osx-x86_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:osx-x86_64`
+| Windows x86 32 bits | `windows-x86_32` | `com.google.protobuf:protoc:VERSION:exe:windows-x86_32` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:windows-x86_32`
+| Windows x86 64 bits | `windows-x86_64` | `com.google.protobuf:protoc:VERSION:exe:windows-x86_64` and `io.grpc:protoc-gen-grpc-java:VERSION:exe:windows-x86_64`
+|===
+
+Because of the packaging of `protoc` and the plugin (using classifier), it's not possible to exclude undesired platforms individually.
+
+You can, however, exclude the `protoc` dependency altogether and use the `quarkus.grpc.protoc-path` system property to configure the path to the `protoc` executable installed on your machine.
+Thus, you don't need to download any `protoc` variants:
+
+.Step 1: Exclusion of `protoc`
+[source, xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-grpc</artifactId>
+    <exclusions>
+        <exclusion>
+            <groupId>com.google.protobuf</groupId>
+            <artifactId>protoc</artifactId>
+        </exclusion>
+    </exclusions>
+</dependency>
+----
+
+.Step 2: Passing the `quarkus.grpc.protoc-path` property:
+[source, shell]
+----
+mvn clean quarkus:dev -Dquarkus.grpc.protoc-path=/path/to/protoc
+----
+
+IMPORTANT: Using this approach requires to have `protoc` installed locally. It will not download any `protoc` artifact.
+
+WARNING: Unfortunately, this only works for `protoc` and not for the Java plugin. The Java plugin is always downloaded.

_versions/main/guides/hibernate-reactive-panache.adoc

@@ -1133,7 +1133,7 @@ public class PanacheFunctionalityTest {
 }
 ----
 <1> Make sure the test method is run on the Vert.x event loop.
-<2> The injected `UniAsserter` agrument is used to make assertions.
+<2> The injected `UniAsserter` argument is used to make assertions.
 
 == How and why we simplify Hibernate Reactive mappings
 

_versions/main/guides/security-openid-connect-providers.adoc

@@ -207,7 +207,7 @@ In order to set up OIDC for GitHub you need to create a new OAuth application in
 
 image::oidc-github-1.png[role="thumb"]
 
-Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to `http://localhost:8080/_renarde/security/oidc-success`
+Make sure to fill in the appropriate details, but more importantly the Authorization Callback URL, set to `http://localhost:8080/github`
 (if you intend to test this using the Quarkus dev mode).
 
 Now click on `Register application` and you'll be shown your application page:

_versions/main/guides/transaction.adoc

@@ -307,6 +307,13 @@ The node name identifier needs to be unique per transaction manager deployment.
 And the node identifier needs to be stable over the transaction manager restarts.
 
 The node name identifier may be configured via the property `quarkus.transaction-manager.node-name`.
+[NOTE]
+====
+The node name cannot be longer than 28 bytes.
+To automatically shorten names longer than 28 bytes, set `quarkus.transaction-manager.shorten-node-name-if-necessary` to `true`.
+
+Shortening is implemented by hashing the node name, encoding the hash to Base64 and then truncating the result. As with all hashes, the resulting shortened node name could potentially conflict with another shortened node name, but it is https://github.com/quarkusio/quarkus/issues/30491#issuecomment-1537247764[very unlikely].
+====
 
 [[transaction-scope]]
 == Using `@TransactionScoped` to bind CDI beans to the transaction lifecycle

_versions/main/guides/vertx-reference.adoc

@@ -1243,4 +1243,34 @@ public class MyCustomizer implements VertxOptionsCustomizer {
 
 The _customizer_ beans received the `VertxOptions` (coming from the application configuration), and can modify them.
 
+== Brotli4J and cross-platform support
 
+Brotli4J is a native library that provides support for the Brotli compression algorithm.
+By default, Quarkus includes the Brotli native library matching the platform you are running on.
+But sometimes, you need to include the native library for a different platform.
+
+In this case, you need to explicitly add a dependency to your project.
+For example, if you need to include the native library for `linux-aarch64`, you can add the following dependency:
+
+[source,xml]
+----
+<dependency>
+    <groupId>com.aayushatharva.brotli4j</groupId>
+    <artifactId>native-linux-aarch64</artifactId>
+</dependency>
+----
+
+This will include the native library for `linux-aarch64` in your project, in addition to the one matching your machine.
+
+Here is the list of available brotli4j artifacts for the different platforms:
+
+* `native-linux-x86_64`
+* `native-linux-s390x`
+* `native-linux-ppc64le`
+* `native-linux-aarch64`
+* `native-linux-armv7`
+* `native-linux-riscv64`
+* `native-windows-x86_64`
+* `native-windows-aarch64`
+* `native-macos-x86_64`
+* `native-macos-aarch64`