Sync documentation of main branch

quarkusio · Oct 31, 2024 · fdd4ecf · fdd4ecf
1 parent 6723c37
commit fdd4ecf
Show file tree

Hide file tree

Showing 8 changed files with 173 additions and 63 deletions.
diff --git a/_generated-doc/main/config/quarkus-all-config.adoc b/_generated-doc/main/config/quarkus-all-config.adoc
@@ -12173,6 +12173,27 @@ endif::add-copy-button-to-env-var[]
 |string
 |`X-Forwarded-Prefix`
 
+a| [[quarkus-vertx-http_quarkus-http-proxy-enable-trusted-proxy-header]] [.property-path]##link:#quarkus-vertx-http_quarkus-http-proxy-enable-trusted-proxy-header[`quarkus.http.proxy.enable-trusted-proxy-header`]##
+
+[.description]
+--
+Adds the header `X-Forwarded-Trusted-Proxy` if the request is forwarded by a trusted proxy. The value is `true` if the request is forwarded by a trusted proxy, otherwise `null`.
+
+The forwarded parser detects forgery attempts and if the incoming request contains this header, it will be removed from the request.
+
+The `X-Forwarded-Trusted-Proxy` header is a custom header, not part of the standard `Forwarded` header.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HTTP_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HTTP_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 a| [[quarkus-vertx-http_quarkus-http-proxy-trusted-proxies]] [.property-path]##link:#quarkus-vertx-http_quarkus-http-proxy-trusted-proxies[`quarkus.http.proxy.trusted-proxies`]##
 
 [.description]
@@ -13506,6 +13527,27 @@ endif::add-copy-button-to-env-var[]
 |string
 |`X-Forwarded-Prefix`
 
+a| [[quarkus-vertx-http_quarkus-management-proxy-enable-trusted-proxy-header]] [.property-path]##link:#quarkus-vertx-http_quarkus-management-proxy-enable-trusted-proxy-header[`quarkus.management.proxy.enable-trusted-proxy-header`]##
+
+[.description]
+--
+Adds the header `X-Forwarded-Trusted-Proxy` if the request is forwarded by a trusted proxy. The value is `true` if the request is forwarded by a trusted proxy, otherwise `null`.
+
+The forwarded parser detects forgery attempts and if the incoming request contains this header, it will be removed from the request.
+
+The `X-Forwarded-Trusted-Proxy` header is a custom header, not part of the standard `Forwarded` header.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_MANAGEMENT_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_MANAGEMENT_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 a| [[quarkus-vertx-http_quarkus-management-proxy-trusted-proxies]] [.property-path]##link:#quarkus-vertx-http_quarkus-management-proxy-trusted-proxies[`quarkus.management.proxy.trusted-proxies`]##
 
 [.description]
@@ -71164,23 +71206,6 @@ endif::add-copy-button-to-env-var[]
 a|`off`, `query-only`, `query-and-variables`
 |`off`
 
-a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
-
-[.description]
---
-Set the Field visibility.
-
-
-ifdef::add-copy-button-to-env-var[]
-Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
-endif::add-copy-button-to-env-var[]
-ifndef::add-copy-button-to-env-var[]
-Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
-endif::add-copy-button-to-env-var[]
---
-|string
-|`default`
-
 a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions[`quarkus.smallrye-graphql.unwrap-exceptions`]##
 
 [.description]
@@ -71385,6 +71410,23 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |`true`
 
+a| [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
+
+[.description]
+--
+Specifies the field visibility for the GraphQL schema. This configuration item allows you to define comma-separated list of patterns (GraphQLType.GraphQLField). These patterns are used to determine which fields should be excluded from the schema. Special value `no-introspection` will disable introspection fields. For more info see link:https://smallrye.io/smallrye-graphql/docs/schema/field-visibility[graphql-java documentation]
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
+endif::add-copy-button-to-env-var[]
+--
+|string
+|`default`
+
 h|[[quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui]] [.section-name.section-level0]##link:#quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui[SmallRye GraphQL UI configuration]##
 h|Type
 h|Default

diff --git a/_generated-doc/main/config/quarkus-smallrye-graphql.adoc b/_generated-doc/main/config/quarkus-smallrye-graphql.adoc
@@ -364,23 +364,6 @@ endif::add-copy-button-to-env-var[]
 a|`off`, `query-only`, `query-and-variables`
 |`off`
 
-a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
-
-[.description]
---
-Set the Field visibility.
-
-
-ifdef::add-copy-button-to-env-var[]
-Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
-endif::add-copy-button-to-env-var[]
-ifndef::add-copy-button-to-env-var[]
-Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
-endif::add-copy-button-to-env-var[]
---
-|string
-|`default`
-
 a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions[`quarkus.smallrye-graphql.unwrap-exceptions`]##
 
 [.description]
@@ -585,6 +568,23 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |`true`
 
+a| [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
+
+[.description]
+--
+Specifies the field visibility for the GraphQL schema. This configuration item allows you to define comma-separated list of patterns (GraphQLType.GraphQLField). These patterns are used to determine which fields should be excluded from the schema. Special value `no-introspection` will disable introspection fields. For more info see link:https://smallrye.io/smallrye-graphql/docs/schema/field-visibility[graphql-java documentation]
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
+endif::add-copy-button-to-env-var[]
+--
+|string
+|`default`
+
 h|[[quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui]] [.section-name.section-level0]##link:#quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui[SmallRye GraphQL UI configuration]##
 h|Type
 h|Default

diff --git a/_generated-doc/main/config/quarkus-smallrye-graphql_quarkus.smallrye-graphql.adoc b/_generated-doc/main/config/quarkus-smallrye-graphql_quarkus.smallrye-graphql.adoc
@@ -364,23 +364,6 @@ endif::add-copy-button-to-env-var[]
 a|`off`, `query-only`, `query-and-variables`
 |`off`
 
-a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
-
-[.description]
---
-Set the Field visibility.
-
-
-ifdef::add-copy-button-to-env-var[]
-Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
-endif::add-copy-button-to-env-var[]
-ifndef::add-copy-button-to-env-var[]
-Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
-endif::add-copy-button-to-env-var[]
---
-|string
-|`default`
-
 a|icon:lock[title=Fixed at build time] [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-unwrap-exceptions[`quarkus.smallrye-graphql.unwrap-exceptions`]##
 
 [.description]
@@ -585,6 +568,23 @@ endif::add-copy-button-to-env-var[]
 |boolean
 |`true`
 
+a| [[quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility]] [.property-path]##link:#quarkus-smallrye-graphql_quarkus-smallrye-graphql-field-visibility[`quarkus.smallrye-graphql.field-visibility`]##
+
+[.description]
+--
+Specifies the field visibility for the GraphQL schema. This configuration item allows you to define comma-separated list of patterns (GraphQLType.GraphQLField). These patterns are used to determine which fields should be excluded from the schema. Special value `no-introspection` will disable introspection fields. For more info see link:https://smallrye.io/smallrye-graphql/docs/schema/field-visibility[graphql-java documentation]
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_SMALLRYE_GRAPHQL_FIELD_VISIBILITY+++`
+endif::add-copy-button-to-env-var[]
+--
+|string
+|`default`
+
 h|[[quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui]] [.section-name.section-level0]##link:#quarkus-smallrye-graphql_section_quarkus-smallrye-graphql-ui[SmallRye GraphQL UI configuration]##
 h|Type
 h|Default

diff --git a/_generated-doc/main/config/quarkus-vertx-http_quarkus.http.adoc b/_generated-doc/main/config/quarkus-vertx-http_quarkus.http.adoc
@@ -2947,6 +2947,27 @@ endif::add-copy-button-to-env-var[]
 |string
 |`X-Forwarded-Prefix`
 
+a| [[quarkus-vertx-http_quarkus-http-proxy-enable-trusted-proxy-header]] [.property-path]##link:#quarkus-vertx-http_quarkus-http-proxy-enable-trusted-proxy-header[`quarkus.http.proxy.enable-trusted-proxy-header`]##
+
+[.description]
+--
+Adds the header `X-Forwarded-Trusted-Proxy` if the request is forwarded by a trusted proxy. The value is `true` if the request is forwarded by a trusted proxy, otherwise `null`.
+
+The forwarded parser detects forgery attempts and if the incoming request contains this header, it will be removed from the request.
+
+The `X-Forwarded-Trusted-Proxy` header is a custom header, not part of the standard `Forwarded` header.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_HTTP_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_HTTP_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 a| [[quarkus-vertx-http_quarkus-http-proxy-trusted-proxies]] [.property-path]##link:#quarkus-vertx-http_quarkus-http-proxy-trusted-proxies[`quarkus.http.proxy.trusted-proxies`]##
 
 [.description]

diff --git a/_generated-doc/main/config/quarkus-vertx-http_quarkus.management.adoc b/_generated-doc/main/config/quarkus-vertx-http_quarkus.management.adoc
@@ -1266,6 +1266,27 @@ endif::add-copy-button-to-env-var[]
 |string
 |`X-Forwarded-Prefix`
 
+a| [[quarkus-vertx-http_quarkus-management-proxy-enable-trusted-proxy-header]] [.property-path]##link:#quarkus-vertx-http_quarkus-management-proxy-enable-trusted-proxy-header[`quarkus.management.proxy.enable-trusted-proxy-header`]##
+
+[.description]
+--
+Adds the header `X-Forwarded-Trusted-Proxy` if the request is forwarded by a trusted proxy. The value is `true` if the request is forwarded by a trusted proxy, otherwise `null`.
+
+The forwarded parser detects forgery attempts and if the incoming request contains this header, it will be removed from the request.
+
+The `X-Forwarded-Trusted-Proxy` header is a custom header, not part of the standard `Forwarded` header.
+
+
+ifdef::add-copy-button-to-env-var[]
+Environment variable: env_var_with_copy_button:+++QUARKUS_MANAGEMENT_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++[]
+endif::add-copy-button-to-env-var[]
+ifndef::add-copy-button-to-env-var[]
+Environment variable: `+++QUARKUS_MANAGEMENT_PROXY_ENABLE_TRUSTED_PROXY_HEADER+++`
+endif::add-copy-button-to-env-var[]
+--
+|boolean
+|`false`
+
 a| [[quarkus-vertx-http_quarkus-management-proxy-trusted-proxies]] [.property-path]##link:#quarkus-vertx-http_quarkus-management-proxy-trusted-proxies[`quarkus.management.proxy.trusted-proxies`]##
 
 [.description]

diff --git a/_versions/main/guides/deploying-to-google-cloud.adoc b/_versions/main/guides/deploying-to-google-cloud.adoc
@@ -60,14 +60,14 @@ Then, you will need to create a `src/main/appengine/app.yaml` file, let's keep i
 
 [source, yaml]
 ----
-runtime: java11
+runtime: java17
 ----
 
 This will create a default service for your App Engine application.
 
 [NOTE]
 ====
-You can also use the new Java 17 runtime by defining `runtime: java17` instead.
+You can also use another Java runtime supported by App Engine, for example, for Java 21, use `runtime: java21` instead.
 ====
 
 App Engine Standard does not support the default Quarkus' specific packaging layout, therefore, you must set up your application to be packaged as an uber-jar via your `application.properties` file:
@@ -114,7 +114,7 @@ First, add the plugin to your `pom.xml`:
 <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
-    <version>2.4.4</version>
+    <version>2.7.0</version>
     <configuration>
         <projectId>GCLOUD_CONFIG</projectId> <1>
         <version>gettingstarted</version>

diff --git a/_versions/main/guides/mailer-reference.adoc b/_versions/main/guides/mailer-reference.adoc
@@ -66,9 +66,9 @@ To send a simple email, proceed as follows:
 [source, java]
 ----
 // Imperative API:
-mailer.send(Mail.withText("[email protected]", "A simple email from quarkus", "This is my body."));
+mailer.send(Mail.withText("[email protected]", "A simple email from quarkus", "This is my body.").setFrom("[email protected]"));
 // Reactive API:
-Uni<Void> stage = reactiveMailer.send(Mail.withText("[email protected]", "A reactive email from quarkus", "This is my body."));
+Uni<Void> stage = reactiveMailer.send(Mail.withText("[email protected]", "A reactive email from quarkus", "This is my body.").setFrom("[email protected]"));
 ----
 
 For example, you can use the `Mailer` in an HTTP endpoint as follows:
@@ -78,14 +78,14 @@ For example, you can use the `Mailer` in an HTTP endpoint as follows:
 @GET
 @Path("/imperative")
 public void sendASimpleEmail() {
-    mailer.send(Mail.withText("[email protected]", "A simple email from quarkus", "This is my body"));
+    mailer.send(Mail.withText("[email protected]", "A simple email from quarkus", "This is my body").setFrom("[email protected]"));
 }
 
 @GET
 @Path("/reactive")
 public Uni<Void> sendASimpleEmailAsync() {
     return reactiveMailer.send(
-            Mail.withText("[email protected]", "A reactive email from quarkus", "This is my body"));
+            Mail.withText("[email protected]", "A reactive email from quarkus", "This is my body").setFrom("[email protected]"));
 }
 ----
 
@@ -96,6 +96,20 @@ You can create new `io.quarkus.mailer.Mail` instances from the constructor or fr
 `Mail.withHtml` helper methods.
 The `Mail` instance lets you add recipients (to, cc, or bcc), set the subject, headers, sender (from) address...
 
+Most of these properties are optional, but the sender address is required. It can either be set on an individual `Mail` instances using
+
+[source,java]
+----
+.setFrom("[email protected]");
+----
+
+or a global default can be configured, using
+
+[source,properties]
+----
+[email protected]
+----
+
 You can also send several `Mail` objects in one call:
 
 [source, java]

diff --git a/_versions/main/guides/tls-registry-reference.adoc b/_versions/main/guides/tls-registry-reference.adoc
@@ -48,6 +48,13 @@ These properties are required for:
  * Creating separate, named configurations by using `+quarkus.tls.<name>.*+`.
 By specifying the `+quarkus.tls.<name>.*+` properties, you can adapt the TLS settings for a specific component.
 
+[IMPORTANT]
+====
+The default TLS configuration is not a fallback/global configuration. This means that each named TLS configuration
+(or "TLS bucket") needs to provide its own properties. For instance, `quarkus.tls.reload-period` will only be applied
+to the default TLS configuration.
+====
+
 === Configuring HTTPS for a HTTP server
 
 To ensure secure client-server communication, the client is often required to verify the server's authenticity.
@@ -620,7 +627,7 @@ If any of these checks fail, the application will not start.
 == Reloading certificates
 
 The `TlsConfiguration` obtained from the `TLSConfigurationRegistry` includes a mechanism for reloading certificates.
-The `reload` method refreshes the keystores and truststores, typically by reloading them from the file system.
+The `reload` method refreshes the keystores, truststores and CRLs, typically by reloading them from the file system.
 
 NOTE: The reload operation is not automatic and must be triggered manually.
 Additionally, the `TlsConfiguration` implementation must support reloading (which is the case for the configured certificate).
@@ -650,8 +657,10 @@ public void reload() {
     }
 }
 
-// In the server or client code
-public void onReload(@Observes CertificateUpdatedEvent reload) {
+// In the server (or client) code
+private final io.vertx.core.http.HttpServer server;
+
+public void onCertificateUpdate(@Observes CertificateUpdatedEvent reload) {
     if ("name".equals(event.getName())) {
         server.updateSSLOptions(reload.tlsConfiguration().getSSLOptions());
         // Or update the SSLContext.
@@ -678,13 +687,16 @@ quarkus.tls.key-store.pem.0.key=tls.key
 +
 [source,properties]
 ----
-quarkus.tls.http.reload-period=30min
+quarkus.tls.http.reload-period=30m
 quarkus.tls.http.key-store.pem.0.cert=tls.crt
 quarkus.tls.http.key-store.pem.0.key=tls.key
 ----
 
 IMPORTANT: Impacted server and client may need to listen to the `CertificateUpdatedEvent` to apply the new certificates.
-This is automatically done for the Quarkus HTTP server, including the management interface if it is enabled.
+This is automatically done for the Quarkus HTTP server (i.e. Quarkus REST server, gRPC server, Web Socket server) and
+the management interface if it is enabled.
+
+NOTE: In Quarkus dev mode, when files are touched, it will trigger the `CertificateUpdatedEvent` much more frequently.
 
 ifndef::no-kubernetes-secrets-or-cert-manager[]
 == Using Kubernetes secrets or cert-manager