<commit_before>////
This guide 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
////
= HTTP Reference
include::_attributes.adoc[]
:categories: web
:summary: Learn more about configuring Quarkus' Vert.x based HTTP layer - and Undertow if you are using servlets.
:numbered:
:sectnums:
:sectnumlevels: 4
:toc:

:numbered:
:sectnums:
:sectnumlevels: 4


This document explains various HTTP features that you can use in Quarkus.

HTTP is provided using Eclipse Vert.x as the base HTTP layer. Servlet's are supported using a modified version of Undertow that
runs on top of Vert.x, and RESTEasy is used to provide JAX-RS support. If Undertow is present RESTEasy will run as a
Servlet filter, otherwise it will run directly on top of Vert.x with no Servlet involvement.

== Serving Static Resources

To serve static resources you must place them in the `META-INF/resources` directory of your application. This location
was chosen as it is the standard location for resources in `jar` files as defined by the Servlet spec. Even though
Quarkus can be used without Servlet following this convention allows existing code that places its resources in this
location to function correctly.

=== WebJar Locator Support

If you are using webjars, like the following JQuery one:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.1.1</version>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("org.webjars:jquery:3.1.1")
----

and rather write `/webjars/jquery/jquery.min.js` instead of `/webjars/jquery/3.1.1/jquery.min.js`
in your HTML files, you can add the `quarkus-webjars-locator` extension to your project.
To use it, add the following to your project's dependencies:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-webjars-locator</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-webjars-locator")
----

=== HTTP Compression

The response body of a static resource is not compressed by default.
You can enable the HTTP compression support by means of `quarkus.http.enable-compression=true`.
If compression support is enabled then the response body is compressed if the `Content-Type` header derived from the file name of a resource is a compressed media type as configured via `quarkus.http.compress-media-types`.

TIP: By default, the following list of media types is compressed: `text/html`, `text/plain`, `text/xml`, `text/css`, `text/javascript` and `application/javascript`.

NOTE: If the client does not support HTTP compression then the response body is not compressed.

[[context-path]]
== Configuring the Context path

By default, Quarkus will serve content from under the root context. If you want to change this you can use the
`quarkus.http.root-path` config key to set the context path.

If you are using Servlet you can control the Servlet context path via `quarkus.servlet.context-path`. This item is relative
to the http root above, and will only affect Servlet and things that run on top of Servlet. Most applications will
want to use the HTTP root as this affects everything that Quarkus serves.

If both are specified then all non-Servlet web endpoints will be relative to `quarkus.http.root-path`, while Servlet's
will be served relative to `{quarkus.http.root-path}/{quarkus.servlet.context-path}`.

If REST Assured is used for testing and `quarkus.http.root-path` is set then Quarkus will automatically configure the
base URL for use in Quarkus tests, so test URL's should not include the root path.


In general, path configurations for web content are interpreted relative to `quarkus.http.root-path` (which is / by default).

- To specify paths within this context root, use a relative path that does not begin with a forward slash.

- If you want to specify the URI explicitly, so it is always the same regardless of the value of `quarkus.http.root-path`, use an absolute path that begins with a forward slash.

As an example, if an extension configures a `service` path, that endpoint will be served from `${quarkus.http.root-path}/service`. If you change the configuration of that path to `/service`, that endpoint will be served from `/service`.

The link:https://quarkus.io/blog/path-resolution-in-quarkus/[Path Resolution in Quarkus] blog post further explains how path resolution works for both user and extension defined paths.

[[ssl]]
== Supporting secure connections with SSL

In order to have Quarkus support secure connections, you must either provide a certificate and associated key file, or supply a keystore.

In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.

[TIP]
====
To enable SSL support with native executables, please refer to our xref:native-and-ssl.adoc[Using SSL With Native Executables guide].
====

=== Providing a certificate and key file

If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below.
Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback.
The certificate / key pair will be loaded into a newly created keystore on startup.

Your `application.properties` would then look like this:

[source,properties]
----
quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key
----

=== Providing a keystore

An alternate solution is to directly provide a keystore which already contains a default entry with a certificate
 You will need to at least provide the file and a password.

As with the certificate/key file combination, Quarkus will first try to resolve the given path as a resource, before attempting to read it from the filesystem.

Add the following property to your `application.properties`:

[source,bash]
----
quarkus.http.ssl.certificate.key-store-file=/path/to/keystore
----

As an optional hint, the type of keystore can be provided as one of the options listed.
If the type is not provided, Quarkus will try to deduce it from the file extensions, defaulting to type JKS.

[source,properties]
----
quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]
----

=== Setting the password

In both aforementioned scenarios, a password needs to be provided to create/load the keystore with.
The password can be set in your `application.properties` (in plain-text) using the following property:

[source, properties]
----
quarkus.http.ssl.certificate.key-store-password=<PASSWORD>
----

However, instead of providing the password as plain-text in the configuration file (which is considered bad practice), it can instead be supplied (using link:https://github.com/eclipse/microprofile-config[MicroProfile Config])
as the environment variable `QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD`.
This will also work in tandem with link:https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-environment-variables[Kubernetes secrets].

_Note: in order to remain compatible with earlier versions of Quarkus (before 0.16) the default password is set to "password". It is therefore not a mandatory parameter!_

=== Disable the HTTP port

It is possible to disable the HTTP port and only support secure requests. This is done via the
`quarkus.http.insecure-requests` property in `application.properties`. There are three possible
values:

`enabled`:: The default, HTTP works as normal
`redirect`:: HTTP requests will be redirected to the HTTPS port
`disabled`:: The HTTP port will not be opened.

NOTE: if you use `redirect` or `disabled` and have not added an SSL certificate or keystore, your server will not start!

== Additional HTTP Headers

To enable HTTP headers to be sent on every response, add the following properties:

[source, properties]
----
quarkus.http.header."X-Content-Type-Options".value=nosniff
----

This will include the `X-Content-Type-Options: nosniff` HTTP Header on responses for requests performed on any resource in the application.

You can also specify a `path` pattern and the HTTP `methods` the header needs to be applied:

[source, properties]
----<commit_msg>Add HTTPS port configuration in the HTTP reference guide<commit_after>////
This guide 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
////
= HTTP Reference
include::_attributes.adoc[]
:categories: web
:summary: Learn more about configuring Quarkus' Vert.x based HTTP layer - and Undertow if you are using servlets.
:numbered:
:sectnums:
:sectnumlevels: 4
:toc:

:numbered:
:sectnums:
:sectnumlevels: 4


This document explains various HTTP features that you can use in Quarkus.

HTTP is provided using Eclipse Vert.x as the base HTTP layer. Servlet's are supported using a modified version of Undertow that
runs on top of Vert.x, and RESTEasy is used to provide JAX-RS support. If Undertow is present RESTEasy will run as a
Servlet filter, otherwise it will run directly on top of Vert.x with no Servlet involvement.

== Serving Static Resources

To serve static resources you must place them in the `META-INF/resources` directory of your application. This location
was chosen as it is the standard location for resources in `jar` files as defined by the Servlet spec. Even though
Quarkus can be used without Servlet following this convention allows existing code that places its resources in this
location to function correctly.

=== WebJar Locator Support

If you are using webjars, like the following JQuery one:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.1.1</version>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("org.webjars:jquery:3.1.1")
----

and rather write `/webjars/jquery/jquery.min.js` instead of `/webjars/jquery/3.1.1/jquery.min.js`
in your HTML files, you can add the `quarkus-webjars-locator` extension to your project.
To use it, add the following to your project's dependencies:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-webjars-locator</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-webjars-locator")
----

=== HTTP Compression

The response body of a static resource is not compressed by default.
You can enable the HTTP compression support by means of `quarkus.http.enable-compression=true`.
If compression support is enabled then the response body is compressed if the `Content-Type` header derived from the file name of a resource is a compressed media type as configured via `quarkus.http.compress-media-types`.

TIP: By default, the following list of media types is compressed: `text/html`, `text/plain`, `text/xml`, `text/css`, `text/javascript` and `application/javascript`.

NOTE: If the client does not support HTTP compression then the response body is not compressed.

[[context-path]]
== Configuring the Context path

By default, Quarkus will serve content from under the root context. If you want to change this you can use the
`quarkus.http.root-path` config key to set the context path.

If you are using Servlet you can control the Servlet context path via `quarkus.servlet.context-path`. This item is relative
to the http root above, and will only affect Servlet and things that run on top of Servlet. Most applications will
want to use the HTTP root as this affects everything that Quarkus serves.

If both are specified then all non-Servlet web endpoints will be relative to `quarkus.http.root-path`, while Servlet's
will be served relative to `{quarkus.http.root-path}/{quarkus.servlet.context-path}`.

If REST Assured is used for testing and `quarkus.http.root-path` is set then Quarkus will automatically configure the
base URL for use in Quarkus tests, so test URL's should not include the root path.


In general, path configurations for web content are interpreted relative to `quarkus.http.root-path` (which is / by default).

- To specify paths within this context root, use a relative path that does not begin with a forward slash.

- If you want to specify the URI explicitly, so it is always the same regardless of the value of `quarkus.http.root-path`, use an absolute path that begins with a forward slash.

As an example, if an extension configures a `service` path, that endpoint will be served from `${quarkus.http.root-path}/service`. If you change the configuration of that path to `/service`, that endpoint will be served from `/service`.

The link:https://quarkus.io/blog/path-resolution-in-quarkus/[Path Resolution in Quarkus] blog post further explains how path resolution works for both user and extension defined paths.

[[ssl]]
== Supporting secure connections with SSL

In order to have Quarkus support secure connections, you must either provide a certificate and associated key file, or supply a keystore.

In both cases, a password must be provided. See the designated paragraph for a detailed description of how to provide it.

[TIP]
====
To enable SSL support with native executables, please refer to our xref:native-and-ssl.adoc[Using SSL With Native Executables guide].
====

=== Providing a certificate and key file

If the certificate has not been loaded into a keystore, it can be provided directly using the properties listed below.
Quarkus will first try to load the given files as resources, and uses the filesystem as a fallback.
The certificate / key pair will be loaded into a newly created keystore on startup.

Your `application.properties` would then look like this:

[source,properties]
----
quarkus.http.ssl.certificate.files=/path/to/certificate
quarkus.http.ssl.certificate.key-files=/path/to/key
----

=== Providing a keystore

An alternate solution is to directly provide a keystore which already contains a default entry with a certificate
 You will need to at least provide the file and a password.

As with the certificate/key file combination, Quarkus will first try to resolve the given path as a resource, before attempting to read it from the filesystem.

Add the following property to your `application.properties`:

[source,bash]
----
quarkus.http.ssl.certificate.key-store-file=/path/to/keystore
----

As an optional hint, the type of keystore can be provided as one of the options listed.
If the type is not provided, Quarkus will try to deduce it from the file extensions, defaulting to type JKS.

[source,properties]
----
quarkus.http.ssl.certificate.key-store-file-type=[one of JKS, JCEKS, P12, PKCS12, PFX]
----

=== Setting the password

In both aforementioned scenarios, a password needs to be provided to create/load the keystore with.
The password can be set in your `application.properties` (in plain-text) using the following property:

[source, properties]
----
quarkus.http.ssl.certificate.key-store-password=<PASSWORD>
----

However, instead of providing the password as plain-text in the configuration file (which is considered bad practice), it can instead be supplied (using link:https://github.com/eclipse/microprofile-config[MicroProfile Config])
as the environment variable `QUARKUS_HTTP_SSL_CERTIFICATE_KEY_STORE_PASSWORD`.
This will also work in tandem with link:https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-environment-variables[Kubernetes secrets].

_Note: in order to remain compatible with earlier versions of Quarkus (before 0.16) the default password is set to "password". It is therefore not a mandatory parameter!_

=== Configure the HTTPS port

By default, Quarkus listens to port 8443 for SSL secured connections and 8444 when running tests.

These ports can be configured in your `application.properties` with the properties `quarkus.http.ssl-port` and `quarkus.http.test-ssl-port`.

=== Disable the HTTP port

It is possible to disable the HTTP port and only support secure requests. This is done via the
`quarkus.http.insecure-requests` property in `application.properties`. There are three possible
values:

`enabled`:: The default, HTTP works as normal
`redirect`:: HTTP requests will be redirected to the HTTPS port
`disabled`:: The HTTP port will not be opened.

NOTE: if you use `redirect` or `disabled` and have not added an SSL certificate or keystore, your server will not start!

== Additional HTTP Headers

To enable HTTP headers to be sent on every response, add the following properties:

[source, properties]
----
quarkus.http.header."X-Content-Type-Options".value=nosniff
----

This will include the `X-Content-Type-Options: nosniff` HTTP Header on responses for requests performed on any resource in the application.

You can also specify a `path` pattern and the HTTP `methods` the header needs to be applied:

[source, properties]
----
{'fraction_non_alphanumeric': 0.08204776596960348, 'fraction_numerical': 0.0025139984001828364, 'mean_word_length': 4.519709870703248, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3619297', 'n_tokens_mistral': 4916, 'n_tokens_neox': 4665, 'n_words': 2212}