From fdd4ecfe4e248fbe007599d97f90658162df5694 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Thu, 31 Oct 2024 02:05:12 +0000 Subject: [PATCH] Sync documentation of main branch --- .../main/config/quarkus-all-config.adoc | 76 ++++++++++++++----- .../main/config/quarkus-smallrye-graphql.adoc | 34 ++++----- ...lrye-graphql_quarkus.smallrye-graphql.adoc | 34 ++++----- .../quarkus-vertx-http_quarkus.http.adoc | 21 +++++ ...quarkus-vertx-http_quarkus.management.adoc | 21 +++++ .../guides/deploying-to-google-cloud.adoc | 6 +- _versions/main/guides/mailer-reference.adoc | 22 +++++- .../main/guides/tls-registry-reference.adoc | 22 ++++-- 8 files changed, 173 insertions(+), 63 deletions(-) diff --git a/_generated-doc/main/config/quarkus-all-config.adoc b/_generated-doc/main/config/quarkus-all-config.adoc index ff22e4b19f..73e2c26f75 100644 --- 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 index a75daffcc7..a2321503b0 100644 --- 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 index a75daffcc7..a2321503b0 100644 --- 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 index e6d8f70347..d72bada8d6 100644 --- 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 index e7c837455c..71a3f0e398 100644 --- 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 index 664b7c28d3..7a3a7ea54e 100644 --- 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`: com.google.cloud.tools appengine-maven-plugin - 2.4.4 + 2.7.0 GCLOUD_CONFIG <1> gettingstarted diff --git a/_versions/main/guides/mailer-reference.adoc b/_versions/main/guides/mailer-reference.adoc index 14d523190f..45ceed5cf8 100644 --- 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("to@acme.org", "A simple email from quarkus", "This is my body.")); +mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body.").setFrom("from@acme.org")); // Reactive API: -Uni stage = reactiveMailer.send(Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body.")); +Uni stage = reactiveMailer.send(Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body.").setFrom("from@acme.org")); ---- 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("to@acme.org", "A simple email from quarkus", "This is my body")); + mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body").setFrom("from@acme.org")); } @GET @Path("/reactive") public Uni sendASimpleEmailAsync() { return reactiveMailer.send( - Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body")); + Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body").setFrom("from@acme.org")); } ---- @@ -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("from@acme.org"); +---- + +or a global default can be configured, using + +[source,properties] +---- +quarkus.mailer.from=from@acme.org +---- + 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 index 390d66e3c1..2e7322e56b 100644 --- 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..*+`. By specifying the `+quarkus.tls..*+` 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