1. About the Documentation
This section provides a brief overview of Reactor Netty
reference documentation. You do not
need to read this guide in a linear fashion. Each piece stands on its own, though they
often refer to other pieces.
1.1. Latest Version and Copyright Notice
The Reactor Netty
reference guide is available as HTML
documents. The latest copy is available
at https://projectreactor.io/docs/netty/release/reference/index.html
Copies of this document may be made for your own use and for distribution to others,
provided that you do not charge any fee for such copies and further provided that each
copy contains this Copyright Notice
, whether distributed in print or electronically.
1.2. Contributing to the Documentation
The reference guide is written in Asciidoc, and you can find its sources at https://github.com/reactor/reactor-netty/tree/1.1.x/docs/asciidoc.
If you have an improvement, we will be happy to get a pull request from you!
We recommend that you check out a local copy of the repository so that you can
generate the documentation by using the asciidoctor
Gradle task and checking the
rendering. Some of the sections rely on included files, so GitHub
rendering is
not always complete.
To facilitate documentation edits, most sections have a link at the end that opens
an edit UI directly on GitHub for the main source file for that section. These links are
only present in the HTML5 version of this reference guide. They look like the following link:
Suggest Edit to About the Documentation.
|
1.3. Getting Help
There are several ways to reach out for help with Reactor Netty
. You can:
-
Get in touch with the community on Gitter.
-
Ask a question on stackoverflow.com at
reactor-netty
. -
Report bugs in
Github
issues. The repository is the following: reactor-netty.
All of Reactor Netty is open source,
including this
documentation.
|
2. Getting Started
This section contains information that should help you get going with Reactor Netty
. It
includes the following information:
2.1. Introducing Reactor Netty
Suited for Microservices Architecture, Reactor Netty
offers
backpressure-ready network engines for HTTP
(including Websockets), TCP
, and UDP
.
2.2. Prerequisites
Reactor Netty
runs on Java 8
and above.
It has transitive dependencies on:
-
Reactive Streams v1.0.4
-
Reactor Core v3.x
-
Netty v4.1.x
2.3. Understanding the BOM and versioning scheme
Reactor Netty
is part of the Project Reactor BOM
(since the Aluminium
release train).
This curated list groups artifacts that are meant to work well together, providing
the relevant versions despite potentially divergent versioning schemes in these artifacts.
The versioning scheme has changed between 0.9.x and 1.0.x (Dysprosium and Europium). |
Artifacts follow a versioning scheme of MAJOR.MINOR.PATCH-QUALIFIER
while the BOM is versioned using a CalVer inspired scheme of YYYY.MINOR.PATCH-QUALIFIER
, where:
-
MAJOR
is the current generation of Reactor, where each new generation can bring fundamental changes to the structure of the project (which might imply a more significant migration effort) -
YYYY
is the year of the first GA release in a given release cycle (like 1.0.0 for 1.0.x) -
.MINOR
is a 0-based number incrementing with each new release cycle-
in the case of projects, it generally reflects wider changes and can indicate a moderate migration effort
-
in the case of the BOM it allows discerning between release cycles in case two get first released the same year
-
-
.PATCH
is a 0-based number incrementing with each service release -
-QUALIFIER
is a textual qualifier, which is omitted in the case of GA releases (see below)
The first release cycle to follow that convention is thus 2020.0.x
, codename Europium
.
The scheme uses the following qualifiers (note the use of dash separator), in order:
-
-M1
..-M9
: milestones (we don’t expect more than 9 per service release) -
-RC1
..-RC9
: release candidates (we don’t expect more than 9 per service release) -
-SNAPSHOT
: snapshots -
no qualifier for GA releases
Snapshots appear higher in the order above because, conceptually, they’re always "the freshest pre-release" of any given PATCH. Even though the first deployed artifact of a PATCH cycle will always be a -SNAPSHOT, a similarly named but more up-to-date snapshot would also get released after eg. a milestone or between release candidates. |
Each release cycle is also given a codename, in continuity with the previous codename-based scheme, which can be used to reference it more informally (like in discussions, blog posts, etc…). The codenames represent what would traditionally be the MAJOR.MINOR number. They (mostly) come from the Periodic Table of Elements, in increasing alphabetical order.
Up until Dysprosium, the BOM was versioned using a release train scheme with a codename followed by a qualifier, and the qualifiers were slightly different. For example: Aluminium-RELEASE (first GA release, would now be something like YYYY.0.0), Bismuth-M1, Californium-SR1 (service release would now be something like YYYY.0.1), Dysprosium-RC1, Dysprosium-BUILD-SNAPSHOT (after each patch, we’d go back to the same snapshot version. would now be something like YYYY.0.X-SNAPSHOT so we get 1 snapshot per PATCH) |
2.4. Getting Reactor Netty
As mentioned earlier, the easiest way to use
Reactor Netty
in your core is to use the BOM
and
add the relevant dependencies to your project. Note that, when adding such a dependency,
you must omit the version so that the version gets picked up from the BOM
.
However, if you want to force the use of a specific artifact’s version, you can specify
it when adding your dependency as you usually would. You can also forego the BOM
entirely
and specify dependencies by their artifact versions.
2.4.1. Maven Installation
The BOM
concept is natively supported by Maven
. First, you need to import the BOM
by
adding the following snippet to your pom.xml
. If the top section
(dependencyManagement
) already exists in your pom, add only the contents.
<dependencyManagement> (1)
<dependencies>
<dependency>
<groupId>io.projectreactor</groupId>
<artifactId>reactor-bom</artifactId>
<version>2022.0.22</version> (2)
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
1 | Notice the dependencyManagement tag. This is in addition to the regular
dependencies section. |
2 | As of this writing, 2022.0.22 is the latest version of the BOM .
Check for updates at https://github.com/reactor/reactor/releases. |
Next, add your dependencies to the relevant reactor projects, as usual (except without a
<version>
). The following listing shows how to do so:
<dependencies>
<dependency>
<groupId>io.projectreactor.netty</groupId>
<artifactId>reactor-netty-core</artifactId> (1)
(2)
</dependency>
</dependencies>
<dependencies>
<dependency>
<groupId>io.projectreactor.netty</groupId>
<artifactId>reactor-netty-http</artifactId>
</dependency>
</dependencies>
1 | Dependency on Reactor Netty |
2 | No version tag here |
2.4.2. Gradle Installation
The BOM
concept is supported in Gradle since version 5.
The following listing shows how to import the BOM
and add a dependency to Reactor Netty
:
dependencies {
// import a BOM
implementation platform('io.projectreactor:reactor-bom:2022.0.22') (1)
// define dependencies without versions
implementation 'io.projectreactor.netty:reactor-netty-core' (2)
implementation 'io.projectreactor.netty:reactor-netty-http'
}
1 | As of this writing, 2022.0.22 is the latest version of the BOM .
Check for updates at https://github.com/reactor/reactor/releases. |
2 | There is no third : separated section for the version. It is taken from the BOM . |
2.4.3. Milestones and Snapshots
Milestones and developer previews are distributed through the Spring Milestones
repository rather than Maven Central
. To add it to your build configuration
file, use the following snippet:
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones Repository</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>
For Gradle, use the following snippet:
repositories {
maven { url 'https://repo.spring.io/milestone' }
mavenCentral()
}
Similarly, snapshots are also available in a separate dedicated repository (for both Maven and Gradle):
<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshot Repository</name>
<url>https://repo.spring.io/snapshot</url>
</repository>
</repositories>
repositories {
maven { url 'https://repo.spring.io/snapshot' }
mavenCentral()
}
2.5. Support and policies
The entries below are mirroring https://github.com/reactor/.github/blob/main/SUPPORT.adoc
2.5.1. Do you have a question?
Search Stack Overflow first; discuss if necessary |
If you’re unsure why something isn’t working or wondering if there is a better way of doing it please check on Stack Overflow first and if necessary start a discussion. Use relevant tags among the ones we monitor for that purpose:
-
reactor-netty
for specific reactor-netty questions -
project-reactor
for generic reactor questions
If you prefer real-time discussion, we also have a few Gitter channels:
-
reactor
is the historic most active one, where most of the community can help -
reactor-core
is intended for more advanced pinpointed discussions around the inner workings of the library -
reactor-netty
is intended for netty-specific questions
Refer to each project’s README for potential other sources of information.
We generally discourage opening GitHub issues for questions, in favor of the two channels above.
2.5.2. Our policy on deprecations
When dealing with deprecations, given a version A.B.C
, we’ll ensure that:
-
deprecations introduced in version
A
.B
.0
will be removed no sooner than versionA
.B+1
.0
-
deprecations introduced in version
A
.B
.1+
will be removed no sooner than versionA
.B+2
.0
-
we’ll strive to mention the following in the deprecation javadoc:
-
target minimum version for removal
-
pointers to replacements for the deprecated method
-
version in which method was deprecated
-
This policy is officially in effect as of January 2021, for all modules in 2020.0 BOMs and newer release trains, as well as Dysprosium releases after Dysprosium-SR15 .
|
Deprecation removal targets are not a hard commitment, and the deprecated methods could live on further than these minimum target GA versions (ie. only the most problematic deprecated methods will be removed aggressively). |
That said, deprecated code that has outlived its minimum removal target version may be removed in any subsequent release (including patch releases, aka service releases) without further notice. So users should still strive to update their code as early as possible. |
2.5.3. Support Timeline
Our GA release cadence is annual. The next release train is 2025
. The timeline is
subject to change.
The following table summarises the support dates for each individual project followed by the BOM support.
Version | Initial OSS Release | OSS Support End | Commercial Support (*) End | Published in BOM |
---|---|---|---|---|
reactor-core |
||||
3.7 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
3.6 |
2023-11-14 |
2025-08-31 |
2026-12-31 |
2023 |
3.5 |
2022-11-08 |
2024-08-31 |
2025-12-31 |
2022 |
3.4 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-netty |
||||
1.2 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
1.1 |
2022-11-08 |
2025-08-31 |
2026-12-31 |
2022, 2023 |
1.0 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-kafka |
||||
1.3 |
2020-10-26 |
2026-08-31 |
2027-12-31 |
2020, 2022, 2023, 2024 |
reactor-pool |
||||
1.1 |
2024-11-12 |
2026-08-31 |
2027-12-31 |
2024 |
1.0 |
2022-11-08 |
2025-08-31 |
2026-12-31 |
2022, 2023 |
0.2 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-addons |
||||
3.5 |
2022-11-08 |
2026-08-31 |
2027-12-31 |
2022, 2023, 2024 |
3.4 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-kotlin-extensions |
||||
1.2 |
2022-11-08 |
2026-08-31 |
2027-12-31 |
2022, 2023, 2024 |
1.1 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-rabbitmq |
||||
1.5 |
2020-10-26 |
2024-08-31 |
2026-12-31 |
2020 |
reactor-bom |
||||
2024 |
2024-11-12 |
2026-08-31 |
2027-12-31 :leveloffset: 1 :leveloffset!: Suggest Edit to "Getting Started" :leveloffset: 1 :sourcedir: ./../../reactor-netty-core/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/tcp/server :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.tcp.TcpServer
== Starting and Stopping To start a ====
[source,java,indent=0]
.{examplesdir}/create/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/create/Application.java[lines=18..31]
----
<1> Creates a {javadoc}/reactor/netty/tcp/TcpServer.html[ The returned {javadoc}/reactor/netty/DisposableServer.html[ === Host and Port To serve on a specific ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/address/Application.java[lines=18..33]
----
<1> Configures the To serve on multiple addresses, after having configured the ====
[source,java,indent=0]
.{examplesdir}/address/MultiAddressApplication.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/address/MultiAddressApplication.java[lines=18..41]
----
<1> Configures the first == Eager Initialization By default, the initialization of the * the event loop groups
* the native transport libraries (when native transport is used)
* the native libraries for the security (in case of When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/warmup/Application.java[lines=18..36] ---- <1> Initialize and load the event loop groups, the native transport libraries and the native libraries for the security ==== == Writing Data In order to send data to a connected client, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/NettyOutbound.html[ ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/send/Application.java[lines=18..33]
----
<1> Sends == Consuming Data In order to receive data from a connected client, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/NettyInbound.html[ ==== [source,java,indent=0] .{examplesdir}/read/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/read/Application.java[lines=18..32] ---- <1> Receives data from the connected clients ==== == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked when the server channel is about to bind. |
|
Invoked when the server channel is bound. |
|
Invoked when initializing the channel. |
|
Invoked when a remote client is connected |
|
Invoked when the server channel is unbound. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..39]
----
<1> == TCP-level Configurations This section describes three kinds of configuration that you can use at the TCP level: * [server-tcp-level-configurations-channel-options] * [server-tcp-level-configurations-event-wire-logger] * [server-tcp-level-configurations-event-loop-group] By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/tcp/TcpServerBind.java ---- Unresolved directive in tcp-server.adoc - include::{sourcedir}/reactor/netty/tcp/TcpServerBind.java[lines=40..48] ---- ==== If additional options are necessary or changes to the current options are needed, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/channeloptions/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..33] ---- ==== You can find more about * {nettyjavadoc}/io/netty/channel/ChannelOption.html[Common ChannelOption] * {nettyjavadoc}/io/netty/channel/epoll/EpollChannelOption.html[Epoll ChannelOption] * {nettyjavadoc}/io/netty/channel/kqueue/KQueueChannelOption.html[KQueue ChannelOption] * Socket Options :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == SSL and TLS When you need SSL or TLS, you can apply the configuration shown in the next listing.
By default, if The following example uses ==== [source,java,indent=0] .{examplesdir}/security/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/security/Application.java[lines=18..40] ---- ==== === Server Name Indication
You can configure the The following example uses a domain name containing a wildcard: ==== [source,java,indent=0] .{examplesdir}/sni/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/sni/Application.java[lines=18..47] ---- ==== == Metrics
The TCP server supports built-in integration with The following table provides information for the TCP server metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.tcp.server.connections.total |
Gauge |
The number of all opened connections. See [observability-metrics-connections-total] |
reactor.netty.tcp.server.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.tcp.server.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.tcp.server.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
reactor.netty.tcp.server.tls.handshake.time |
Timer |
Time spent for TLS handshake. See [observability-metrics-tls-handshake-time] |
======= These additional metrics are also available:
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |
Gauge |
The number of tasks that are pending for processing on an event loop. See [observability-metrics-pending-tasks] |
======= The following example enables that integration: ==== [source,java,indent=0] .{examplesdir}/metrics/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/metrics/Application.java[lines=18..32] ---- <1> Enables the built-in integration with Micrometer ==== When TCP server metrics are needed for an integration with a system other than ====
[source,java,indent=0]
.{examplesdir}/metrics/custom/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/metrics/custom/Application.java[lines=18..35]
----
<1> Enables TCP server metrics and provides {javadoc}/reactor/netty/channel/ChannelMetricsRecorder.html[ == Tracing
The TCP server supports built-in integration with The following table provides information for the TCP server spans: [width="100%",options="header"] |
======= |
contextual name |
description |
tls handshake |
Information and time spent for TLS handshake. See [observability-spans-tls-handshake-span]. |
======= The following example enables that integration. This concrete example uses ==== [source,java,indent=0] .{examplesdir}/tracing/Application.java ---- Unresolved directive in tcp-server.adoc - include::{examplesdir}/tracing/Application.java[lines=18..81] ---- <1> Initializes Brave, Zipkin, and the Observation registry. <2> Enables the built-in integration with Micrometer. ==== The result in image::images/tcp-server-tracing.png[] === Access Current Observation
Project Micrometer provides The following example shows how to use this library in a custom ====
[source,java,indent=0]
.{examplesdir}/tracing/custom/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/tracing/custom/Application.java[lines=18..86]
----
<1> Initializes Brave, Zipkin, and the Observation registry.
<2> Enables the built-in integration with Micrometer.
<3> Custom NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the == Unix Domain Sockets
The The following example shows how to use UDS support: ====
[source,java,indent=0]
.{examplesdir}/uds/Application.java
----
Unresolved directive in tcp-server.adoc - include::{examplesdir}/uds/Application.java[lines=18..33]
----
<1> Specifies :leveloffset: 3 Suggest Edit to "[tcp-server]" :leveloffset: 1 :sourcedir: ./../../reactor-netty-core/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/tcp/client :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.tcp.TcpClient Reactor Netty provides the easy-to-use and easy-to-configure
{javadoc}/reactor/netty/tcp/TcpClient.html[ == Connect and Disconnect To connect the ====
[source,java,indent=0]
.{examplesdir}/create/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/create/Application.java[lines=18..31]
----
<1> Creates a {javadoc}/reactor/netty/tcp/TcpClient.html[ The returned {javadoc}/reactor/netty/Connection.html[ === Host and Port To connect to a specific ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/address/Application.java[lines=18..33]
----
<1> Configures the NOTE: The port can be specified also with PORT environment variable. == Eager Initialization By default, the initialization of the * the event loop group
* the host name resolver
* the native transport libraries (when native transport is used)
* the native libraries for the security (in case of When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/warmup/Application.java[lines=18..39] ---- <1> Initialize and load the event loop group, the host name resolver, the native transport libraries and the native libraries for the security <2> Host name resolution happens when connecting to the remote peer ==== == Writing Data To send data to a given endpoint, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/NettyOutbound.html[ ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/send/Application.java[lines=18..35]
----
<1> Sends When you need more control over the writing process, as an alternative for I/O handler you may use
{javadoc}/reactor/netty/Connection.html#outbound--[ ====
[source,java,indent=0]
.{examplesdir}/send/connection/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/send/connection/Application.java[lines=18..44]
----
<1> Sends == Consuming Data To receive data from a given endpoint, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/NettyInbound.html[ ==== [source,java,indent=0] .{examplesdir}/read/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/read/Application.java[lines=18..34] ---- <1> Receives data from a given endpoint ==== When you need more control over the reading process, as an alternative for I/O handler you may use
{javadoc}/reactor/netty/Connection.html#inbound--[ ==== [source,java,indent=0] .{examplesdir}/read/connection/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/read/connection/Application.java[lines=18..38] ---- <1> Receives data from a given endpoint. ==== == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked after the remote address has been resolved successfully. |
|
Invoked when initializing the channel. |
|
Invoked when the channel is about to connect. |
|
Invoked after the channel has been connected. |
|
Invoked after the channel has been disconnected. |
|
Invoked when the remote address is about to be resolved. |
|
Invoked in case the remote address hasn’t been resolved successfully. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..41]
----
<1> == TCP-level Configurations This section describes three kinds of configuration that you can use at the TCP level: * [client-tcp-level-configurations-channel-options] * [client-tcp-level-configurations-event-wire-logger] * [client-tcp-level-configurations-event-loop-group] By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/tcp/TcpClientConnect.java ---- Unresolved directive in tcp-client.adoc - include::{sourcedir}/reactor/netty/tcp/TcpClientConnect.java[lines=35..40] ---- ==== If additional options are necessary or changes to the current options are needed, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/channeloptions/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..35] ---- ==== You can find more about * {nettyjavadoc}/io/netty/channel/ChannelOption.html[Common ChannelOption] * {nettyjavadoc}/io/netty/channel/epoll/EpollChannelOption.html[Epoll ChannelOption] * {nettyjavadoc}/io/netty/channel/kqueue/KQueueChannelOption.html[KQueue ChannelOption] * Socket Options :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == Connection Pool
By default, * This means that the implementation creates a new channel if someone tries to acquire a channel
as long as less than NOTE: Connections used by the ==== [source,java,indent=0] ../../../reactor-netty-core/src/main/java/reactor/netty/ReactorNetty.java ---- / * Default max connections. Fallback to * 2 * available number of processors (but with a minimum value of 16) */ public static final String POOL_MAX_CONNECTIONS = "reactor.netty.pool.maxConnections"; / * Default acquisition timeout (milliseconds) before error. If -1 will never wait to * acquire before opening a new * connection in an unbounded fashion. Fallback 45 seconds */ public static final String POOL_ACQUIRE_TIMEOUT = "reactor.netty.pool.acquireTimeout"; ---- ==== When you need to change the default settings, you can configure the ==== [source,java,indent=0] .{examplesdir}/pool/config/Application.java ---- Unresolved directive in tcp-client-conn-provider.adoc - include::{examplesdir}/pool/config/Application.java[lines=18..41] ---- <1> Configures the maximum time for the pending acquire operation to 60 seconds. ==== The following listing shows the available configurations: [width="100%",options="header"] |
======= |
Configuration name |
Description |
|
When this option is enabled, connection pools are regularly checked in the background, and those that are empty and been inactive for a specified time become eligible for disposal. By default, this background disposal of inactive pools is disabled. |
|
When |
|
The maximum number of connections (per connection pool) before start pending. Default to 2 * available number of processors (but with a minimum value of 16). |
|
Enables/disables built-in integration with Micrometer. |
|
The maximum number of extra attempts at acquiring a connection to keep in a pending queue. If -1 is specified, the pending queue does not have upper limit. Default to 2 * max connections. |
|
The maximum time before which a pending acquire must complete, or a TimeoutException is thrown (resolution: ms). If -1 is specified, no such timeout is applied. Default: 45 seconds. |
======= If you need to disable the connection pool, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/pool/Application.java ---- Unresolved directive in tcp-client-conn-provider.adoc - include::{examplesdir}/pool/Application.java[lines=18..35] ---- ==== === Disposing Connection Pool - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom === Metrics
The pooled Pooled [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.total.connections |
Gauge |
The number of all connections, active or idle. See [observability-metrics-total-connections] |
reactor.netty.connection.provider.active.connections |
Gauge |
The number of the connections that have been successfully acquired and are in active use. See [observability-metrics-active-connections] |
reactor.netty.connection.provider.max.connections |
Gauge |
The maximum number of active connections that are allowed. See [observability-metrics-max-connections] |
reactor.netty.connection.provider.idle.connections |
Gauge |
The number of the idle connections. See [observability-metrics-idle-connections] |
reactor.netty.connection.provider.pending.connections |
Gauge |
The number of requests that are waiting for a connection. See [observability-metrics-pending-connections] |
reactor.netty.connection.provider.pending.connections.time |
Timer |
Time spent in pending acquire a connection from the connection pool. See [observability-metrics-pending-connections-time] |
reactor.netty.connection.provider.max.pending.connections |
Gauge |
The maximum number of requests that will be queued while waiting for a ready connection. See [observability-metrics-max-pending-connections] |
======= The following example enables that integration: ==== [source,java,indent=0] .{examplesdir}/pool/metrics/Application.java ---- Unresolved directive in tcp-client-conn-provider.adoc - include::{examplesdir}/pool/metrics/Application.java[lines=18..45] ---- <1> Enables the built-in integration with Micrometer ==== == SSL and TLS When you need SSL or TLS, you can apply the following configuration.
By default, if The following example uses ==== [source,java,indent=0] .{examplesdir}/security/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/security/Application.java[lines=18..37] ---- ==== === Server Name Indication
By default, the ==== [source,java,indent=0] .{examplesdir}/sni/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/sni/Application.java[lines=18..41] ---- ==== == Proxy Support Reactor Netty supports the proxy functionality provided by Netty and provides a way
to specify Netty’s HTTP proxy support always uses The following example uses ==== [source,java,indent=0] .{examplesdir}/proxy/Application.java ---- Unresolved directive in proxy.adoc - include::{examplesdir}/proxy/Application.java[lines=18..42] ---- <1> Configures the connection establishment timeout to 20 seconds. ==== == Metrics
The TCP client supports built-in integration with The following table provides information for the TCP client metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.tcp.client.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.tcp.client.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.tcp.client.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
reactor.netty.tcp.client.tls.handshake.time |
Timer |
Time spent for TLS handshake. See [observability-metrics-tls-handshake-time] |
reactor.netty.tcp.client.connect.time |
Timer |
Time spent for connecting to the remote address. See [observability-metrics-connect-time] |
reactor.netty.tcp.client.address.resolver |
Timer |
Time spent for resolving the address. See [observability-metrics-hostname-resolution-time] |
======= These additional metrics are also available: Pooled [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.total.connections |
Gauge |
The number of all connections, active or idle. See [observability-metrics-total-connections] |
reactor.netty.connection.provider.active.connections |
Gauge |
The number of the connections that have been successfully acquired and are in active use. See [observability-metrics-active-connections] |
reactor.netty.connection.provider.max.connections |
Gauge |
The maximum number of active connections that are allowed. See [observability-metrics-max-connections] |
reactor.netty.connection.provider.idle.connections |
Gauge |
The number of the idle connections. See [observability-metrics-idle-connections] |
reactor.netty.connection.provider.pending.connections |
Gauge |
The number of requests that are waiting for a connection. See [observability-metrics-pending-connections] |
reactor.netty.connection.provider.pending.connections.time |
Timer |
Time spent in pending acquire a connection from the connection pool. See [observability-metrics-pending-connections-time] |
reactor.netty.connection.provider.max.pending.connections |
Gauge |
The maximum number of requests that will be queued while waiting for a ready connection. See [observability-metrics-max-pending-connections] |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |
Gauge |
The number of tasks that are pending for processing on an event loop. See [observability-metrics-pending-tasks] |
======= The following example enables that integration: ==== [source,java,indent=0] .{examplesdir}/metrics/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/metrics/Application.java[lines=18..34] ---- <1> Enables the built-in integration with Micrometer ==== When TCP client metrics are needed for an integration with a system other than ====
[source,java,indent=0]
.{examplesdir}/metrics/custom/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/metrics/custom/Application.java[lines=18..37]
----
<1> Enables TCP client metrics and provides {javadoc}/reactor/netty/channel/ChannelMetricsRecorder.html[ == Tracing
The TCP client supports built-in integration with The following table provides information for the TCP client spans: [width="100%",options="header"] |
======= |
contextual name |
description |
hostname resolution |
Information and time spent for resolving the address. See [observability-spans-hostname-resolution-span]. |
connect |
Information and time spent for connecting to the remote address. See [observability-spans-connect-span]. |
tls handshake |
Information and time spent for TLS handshake. See [observability-spans-tls-handshake-span]. |
======= The following example enables that integration. This concrete example uses ==== [source,java,indent=0] .{examplesdir}/tracing/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/tracing/Application.java[lines=18..81] ---- <1> Initializes Brave, Zipkin, and the Observation registry. <2> Enables the built-in integration with Micrometer. ==== The result in image::images/tcp-client-tracing.png[] === Access Current Observation
Project Micrometer provides The following example shows how to use this library in a custom ====
[source,java,indent=0]
.{examplesdir}/tracing/custom/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/tracing/custom/Application.java[lines=18..80]
----
<1> Initializes Brave, Zipkin, and the Observation registry.
<2> Enables the built-in integration with Micrometer.
<3> Custom NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the == Unix Domain Sockets
The The following example shows how to use UDS support: ====
[source,java,indent=0]
.{examplesdir}/uds/Application.java
----
Unresolved directive in tcp-client.adoc - include::{examplesdir}/uds/Application.java[lines=18..33]
----
<1> Specifies == Host Name Resolution
By default, the When you need to change the default settings, you can configure the ==== [source,java,indent=0] .{examplesdir}/resolver/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/resolver/Application.java[lines=18..36] ---- <1> The timeout of each DNS query performed by this resolver will be 500ms. ==== The following listing shows the available configurations.
Additionally, [width="100%",options="header"] |
======= |
Configuration name |
Description |
|
The supplier of the local address to bind to. |
|
The max time to live of the cached DNS resource records (resolution: seconds).
If the time to live of the DNS resource record returned by the DNS server is greater
than this max time to live, this resolver ignores the time to live from
the DNS server and uses use this max time to live.
Default to |
|
The min time to live of the cached DNS resource records (resolution: seconds). If the time to live of the DNS resource record returned by the DNS server is less than this min time to live, this resolver ignores the time to live from the DNS server and uses this min time to live. Default: 0. |
|
The time to live of the cache for the failed DNS queries (resolution: seconds). Default: 0. |
|
When this setting is enabled, the resolver notifies as soon as all queries for the preferred address type are complete.
When this setting is disabled, the resolver notifies when all possible address types are complete.
This configuration is applicable for |
|
Disables the automatic inclusion of an optional record that tries to give a hint to the remote DNS server about how much data the resolver can read per response. By default, this setting is enabled. |
|
Specifies whether this resolver has to send a DNS query with the recursion desired (RD) flag set. By default, this setting is enabled. |
|
Sets a custom function to create a |
|
Sets a custom {nettyjavadoc}/io/netty/resolver/HostsFileEntriesResolver.html[ |
|
Sets the capacity of the datagram packet buffer (in bytes). Default: 4096. |
|
Sets the maximum allowed number of DNS queries to send when resolving a host name. Default: 16. |
|
Sets the number of dots that must appear in a name before an initial absolute query is made. Default: -1 (to determine the value from the OS on Unix or use a value of 1 otherwise). |
|
Sets the timeout of each DNS query performed by this resolver (resolution: milliseconds). Default: 5000. |
|
The cache to use to store resolved DNS entries. |
|
The list of the protocol families of the resolved address. |
|
Specifies whether this resolver will also fallback to TCP if a timeout is detected. By default, the resolver will only try to use TCP if the response is marked as truncated. |
|
Enables an
{nettyjavadoc}/io/netty/resolver/AddressResolverGroup.html[ |
|
Performs the communication with the DNS servers on the given
{javadoc}/reactor/netty/resources/LoopResources.html[ |
|
The list of search domains of the resolver. By default, the effective search domain list is populated by using the system DNS search domains. |
|
A specific logger and log level to be used by this resolver when generating detailed trace information in case of resolution failure. |
======= Sometimes, you may want to switch to the JVM built-in resolver. To do so, you can configure the ==== [source,java,indent=0] .{examplesdir}/resolver/custom/Application.java ---- Unresolved directive in tcp-client.adoc - include::{examplesdir}/resolver/custom/Application.java[lines=18..37] ---- <1> Sets the JVM built-in resolver. ==== :leveloffset: 3 Suggest Edit to "[tcp-client]" :leveloffset: 1 :sourcedir: ./../../reactor-netty-http/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/http/server :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.http.server.HttpServer
== Starting and Stopping To start an HTTP server, you must create and configure a
{javadoc}/reactor/netty/http/server/HttpServer.html[HttpServer] instance.
By default, the ==== [source,java,indent=0] .{examplesdir}/create/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/create/Application.java[lines=18..31] ---- <1> Creates an {javadoc}/reactor/netty/http/server/HttpServer.html[HttpServer] instance ready for configuring. <2> Starts the server in a blocking fashion and waits for it to finish initializing. ==== The returned {javadoc}/reactor/netty/DisposableServer.html[ === Host and Port To serve on a specific ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/address/Application.java[lines=18..33]
----
<1> Configures the To serve on multiple addresses, after having configured the ====
[source,java,indent=0]
.{examplesdir}/address/MultiAddressApplication.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/address/MultiAddressApplication.java[lines=18..41]
----
<1> Configures the first == Eager Initialization By default, the initialization of the * the event loop groups
* the native transport libraries (when native transport is used)
* the native libraries for the security (in case of When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/warmup/Application.java[lines=18..36] ---- <1> Initialize and load the event loop groups, the native transport libraries and the native libraries for the security ==== == Routing HTTP Defining routes for the ====
[source,java,indent=0]
.{examplesdir}/routing/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/routing/Application.java[lines=18..41]
----
<1> Serves a NOTE: The server routes are unique and only the first matching in order of declaration is invoked. === SSE The following code shows how you can configure the ==== [source,java,indent=0] .{examplesdir}/sse/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/sse/Application.java[lines=18..76] ---- ==== === Static Resources The following code shows how you can configure the ==== [source,java,indent=0] .{examplesdir}/staticresources/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/staticresources/Application.java[lines=18..37] ---- ==== == Writing Data To send data to a connected client, you must attach an I/O handler by using either
{javadoc}/reactor/netty/http/server/HttpServer.html#handle-java.util.function.BiFunction-[ ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/send/Application.java[lines=18..33]
----
<1> Sends === Adding Headers and Other Metadata When you send data to the connected clients, you may need to send additional headers,
cookies, status code, and other metadata.
You can provide this additional metadata by using
{javadoc}/reactor/netty/http/server/HttpServerResponse.html[ ==== [source,java,indent=0] .{examplesdir}/send/headers/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/send/headers/Application.java[lines=18..40] ---- ==== === Compression You can configure the
* The following example uses the ==== [source,java,indent=0] .{examplesdir}/compression/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/compression/Application.java[lines=18..38] ---- ==== == Consuming Data To receive data from a connected client, you must attach an I/O handler by using either
{javadoc}/reactor/netty/http/server/HttpServer.html#handle-java.util.function.BiFunction-[ The following example uses the ==== [source,java,indent=0] .{examplesdir}/read/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/read/Application.java[lines=18..32] ---- <1> Receives data from the connected clients ==== === Reading Headers, URI Params, and other Metadata When you receive data from the connected clients, you might need to check request headers,
parameters, and other metadata. You can obtain this additional metadata by using
{javadoc}/reactor/netty/http/server/HttpServerRequest.html[ ==== [source,java,indent=0] .{examplesdir}/read/headers/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/read/headers/Application.java[lines=18..40] ---- ==== === Reading Post Form or Multipart Data When you receive data from the connected clients, you might want to access ====
[source,java,indent=0]
.{examplesdir}/multipart/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/multipart/Application.java[lines=18..36]
----
<1> Receives When you need to change the default settings, you can configure the ====
[source,java,indent=0]
.{examplesdir}/multipart/custom/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/multipart/custom/Application.java[lines=18..37]
----
<1> Configuration on the The following listing shows the available configurations: [width="100%",options="header"] |
======= |
Configuration name |
Description |
|
Configures the directory where to store the data on the disk. Default to generated temp directory. |
|
Configures the |
|
Configures the maximum in-memory size per data i.e. the data is written
on disk if the size is greater than |
|
Configures the maximum size per data. When the limit is reached, an exception is raised.
If set to |
|
Configures the scheduler to be used for offloading disk operations in the decoding phase.
Default to |
|
When set to |
======= ==== Obtaining the Remote (Client) Address In addition to the metadata that you can obtain from the request, you can also receive the
====
[source,java,indent=0]
.{examplesdir}/clientaddress/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/clientaddress/Application.java[lines=18..38]
----
<1> Specifies that the information about the connection is to be obtained from the It is also possible to customize the behavior of the ==== [source,java,indent=0] .{examplesdir}/clientaddress/CustomForwardedHeaderHandlerApplication.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/clientaddress/CustomForwardedHeaderHandlerApplication.java[lines=18..52] ---- <1> Add a custom header handler. <2> Returns the address of the remote (client) peer. ==== === HTTP Request Decoder By default, * The maximum length of the initial line. * The maximum length of all headers. * The maximum length of the content or each chunk. For more information, see {nettyjavadoc}/io/netty/handler/codec/http/HttpRequestDecoder.html[ By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/HttpDecoderSpec.java ---- Unresolved directive in http-server.adoc - include::{sourcedir}/reactor/netty/http/HttpDecoderSpec.java[lines=28..40] ---- ==== ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/server/HttpRequestDecoderSpec.java ---- Unresolved directive in http-server.adoc - include::{sourcedir}/reactor/netty/http/server/HttpRequestDecoderSpec.java[lines=42..47] ---- ==== When you need to change these default settings, you can configure the ====
[source,java,indent=0]
.{examplesdir}/requestdecoder/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/requestdecoder/Application.java[lines=18..34]
----
<1> The maximum length of all headers will be == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked when the server channel is about to bind. |
|
Invoked when the server channel is bound. |
|
Invoked when initializing the channel. |
|
Invoked when a remote client is connected |
|
Invoked when the server channel is unbound. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..39]
----
<1> == TCP-level Configuration When you need to change configuration on the TCP level, you can use the following snippet
to extend the default ==== [source,java,indent=0] .{examplesdir}/channeloptions/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..33] ---- ==== See [tcp-server] for more detail about TCP-level configuration. :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == SSL and TLS When you need SSL or TLS, you can apply the configuration shown in the next example.
By default, if The following example uses ==== [source,java,indent=0] .{examplesdir}/security/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/security/Application.java[lines=18..39] ---- ==== === Server Name Indication
You can configure the The following example uses a domain name containing a wildcard: ==== [source,java,indent=0] .{examplesdir}/sni/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/sni/Application.java[lines=18..47] ---- ==== == HTTP Access Log You can enable the You can use You can use the following configuration (for Logback or similar logging frameworks) to have a separate
==== [source,xml] ---- <appender name="accessLog" class="ch.qos.logback.core.FileAppender"> <file>access_log.log</file> <encoder> <pattern>%msg%n</pattern> </encoder> </appender> <appender name="async" class="ch.qos.logback.classic.AsyncAppender"> <appender-ref ref="accessLog" /> </appender> <logger name="reactor.netty.http.server.AccessLog" level="INFO" additivity="false"> <appender-ref ref="async"/> </logger> ---- ==== The following example enables it programmatically: ==== [source,java,indent=0] .{examplesdir}/accessLog/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/accessLog/Application.java[lines=18..32] ---- ==== Calling this method takes precedence over the system property configuration. By default, the logging format is Common Log Format, but you can specify a custom one as a parameter, as in the following example: ==== [source,java,indent=0] .{examplesdir}/accessLog/CustomLogAccessFormatApplication.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/accessLog/CustomLogAccessFormatApplication.java[lines=18..33] ---- ==== You can also filter Note that this method can take a custom format parameter too, as in this example: ==== [source,java,indent=0] .{examplesdir}/accessLog/CustomFormatAndFilterAccessLogApplication.java.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/accessLog/CustomFormatAndFilterAccessLogApplication.java[lines=18..35] ---- <1> Specifies the filter predicate to use <2> Specifies the custom format to apply ==== == HTTP/2 By default, the NOTE: As Application-Layer Protocol Negotiation (ALPN) is not supported “out-of-the-box” by JDK8 (although some vendors backported ALPN to JDK8), you need an additional dependency to a native library that
supports it — for example, The following listing presents a simple ====
[source,java,indent=0]
.{examplesdir}/http2/H2Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/http2/H2Application.java[lines=18..44]
----
<1> Configures the server to support only The application should now behave as follows: ==== [source,bash] ---- $ curl --http2 https://localhost:8080 -i HTTP/2 200 hello ---- ==== The following listing presents a simple ==== [source,java,indent=0] .{examplesdir}/http2/H2CApplication.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/http2/H2CApplication.java[lines=18..41] ---- ==== The application should now behave as follows: ==== [source,bash] ---- $ curl --http2-prior-knowledge http://localhost:8080 -i HTTP/2 200 hello ---- ==== === Protocol Selection ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/HttpProtocol.java ---- Unresolved directive in http-server.adoc - include::{sourcedir}/reactor/netty/http/HttpProtocol.java[lines=24..52] ---- ==== == Metrics
The HTTP server supports built-in integration with The following table provides information for the HTTP server metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.http.server.streams.active |
Gauge |
The number of active HTTP/2 streams. See [observability-metrics-streams-active] |
reactor.netty.http.server.connections.active |
Gauge |
The number of http connections currently processing requests. See [observability-metrics-connections-active] |
reactor.netty.http.server.connections.total |
Gauge |
The number of all opened connections. See [observability-metrics-connections-total] |
reactor.netty.http.server.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.http.server.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.http.server.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
reactor.netty.http.server.data.received.time |
Timer |
Time spent in consuming incoming data. See [observability-metrics-http-server-data-received-time] |
reactor.netty.http.server.data.sent.time |
Timer |
Time spent in sending outgoing data. See [observability-metrics-http-server-data-sent-time] |
reactor.netty.http.server.response.time |
Timer |
Total time for the request/response See [observability-metrics-http-server-response-time] |
======= These additional metrics are also available:
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |
Gauge |
The number of tasks that are pending for processing on an event loop. See [observability-metrics-pending-tasks] |
======= The following example enables that integration: ====
[source,java,indent=0]
.{examplesdir}/metrics/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/metrics/Application.java[lines=18..52]
----
<1> Applies upper limit for the meters with NOTE: In order to avoid a memory and CPU overhead of the enabled metrics, it is important to convert the real URIs to templated URIs when possible. Without a conversion to a template-like form, each distinct URI leads to the creation of a distinct tag, which takes a lot of memory for the metrics. NOTE: Always apply an upper limit for the meters with URI tags. Configuring an upper limit on the number of meters can help in cases when the real URIs cannot be templated.
You can find more information at When HTTP server metrics are needed for an integration with a system other than ====
[source,java,indent=0]
.{examplesdir}/metrics/custom/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/metrics/custom/Application.java[lines=18..41]
----
<1> Enables HTTP server metrics and provides {javadoc}/reactor/netty/http/server/HttpServerMetricsRecorder.html[ == Tracing
The HTTP server supports built-in integration with The following table provides information for the HTTP server spans: [width="100%",options="header"] |
======= |
contextual name |
description |
<HTTP METHOD>_<URI> |
Information and total time for the request. See [observability-spans-http-server-response-span]. |
======= The following example enables that integration. This concrete example uses ==== [source,java,indent=0] .{examplesdir}/tracing/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/tracing/Application.java[lines=18..91] ---- <1> Initializes Brave, Zipkin, and the Observation registry. <2> Templated URIs are used as an URI tag value when possible. <3> Enables the built-in integration with Micrometer. ==== The result in image::images/http-server-tracing.png[] === Access Current Observation
Project Micrometer provides The following example shows how to use this library in a custom ====
[source,java,indent=0]
.{examplesdir}/tracing/custom/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/tracing/custom/Application.java[lines=18..85]
----
<1> Initializes Brave, Zipkin, and the Observation registry.
<2> Templated URIs are used as an URI tag value when possible.
<3> Enables the built-in integration with Micrometer.
<4> Custom NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the == Unix Domain Sockets
The The following example shows how to use UDS support: ====
[source,java,indent=0]
.{examplesdir}/uds/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/uds/Application.java[lines=18..33]
----
<1> Specifies
== Timeout Configuration
This section describes various timeout configuration options that can be used in * [http-server-request-timeout] * [http-server-connection-timeout] * [http-server-ssl-tls-timeout] === Request Timeout The following listing shows all available request timeout configuration options. * NOTE: It is always a good practice to configure a read/request timeout. To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/read/timeout/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/read/timeout/Application.java[lines=18..36] ---- <1> Configures the read timeout to 5 second. <2> Configures the request timeout to 30 second. ==== === Connection Timeout The following listing shows all available connection timeout configuration options. * NOTE: It is always a good practice to configure an idle timeout. To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/idle/timeout/Application.java ---- Unresolved directive in http-server.adoc - include::{examplesdir}/idle/timeout/Application.java[lines=18..35] ---- <1> Configures the default idle timeout to 1 second. ====
=== SSL/TLS Timeout
The following list describes the available timeout configuration options: * NOTE: You should consider increasing the SSL handshake timeout when expecting slow network connections. * To customize the default settings, you can configure ====
[source,java,indent=0]
.{examplesdir}/security/custom/Application.java
----
Unresolved directive in http-server.adoc - include::{examplesdir}/security/custom/Application.java[lines=18..44]
----
<1> Configures the SSL handshake timeout to 30 seconds.
<2> Configures the SSL :leveloffset: 3 Suggest Edit to "[http-server]" :leveloffset: 1 :sourcedir: ./../../reactor-netty-http/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/http/client :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.http.client.HttpClient Reactor Netty provides the easy-to-use and easy-to-configure
{javadoc}/reactor/netty/http/client/HttpClient.html[ == Connect To connect the ====
[source,java,indent=0]
.{examplesdir}/connect/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/connect/Application.java[lines=18..30]
----
<1> Creates a {javadoc}/reactor/netty/http/client/HttpClient.html[HttpClient]
instance ready for configuring.
<2> Specifies that The following example uses ==== [source,java,indent=0] .{examplesdir}/websocket/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/websocket/Application.java[lines=18..42] ---- ==== === Host and Port In order to connect to a specific host and port, you can apply the following configuration to the ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/address/Application.java[lines=18..33]
----
<1> Configures the NOTE: The port can be specified also with PORT environment variable. == Eager Initialization By default, the initialization of the * the event loop group
* the host name resolver
* the native transport libraries (when native transport is used)
* the native libraries for the security (in case of When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/warmup/Application.java[lines=18..36] ---- <1> Initialize and load the event loop group, the host name resolver, the native transport libraries and the native libraries for the security <2> Host name resolution happens with the first request. In this example, a connection pool is used, so with the first request the connection to the URL is established, the subsequent requests to the same URL reuse the connections from the pool. ==== == Writing Data To send data to a given ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/send/Application.java[lines=18..33]
----
<1> Sends a === Adding Headers and Other Metadata When sending data to a given ====
[source,java,indent=0]
.{examplesdir}/send/headers/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/send/headers/Application.java[lines=18..36]
----
<1> Disables ==== Compression You can enable compression on the ==== [source,java,indent=0] .{examplesdir}/compression/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/compression/Application.java[lines=18..32] ---- ==== ==== Auto-Redirect Support You can configure the Reactor Netty provides two different strategies for auto-redirect support: * |
302 |
303 |
307 |
308`.
When it is The following example uses ==== [source,java,indent=0] .{examplesdir}/redirect/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/redirect/Application.java[lines=18..32] ---- ==== == Consuming Data To receive data from a given ====
[source,java,indent=0]
.{examplesdir}/read/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/read/Application.java[lines=18..33]
----
<1> Receives data from a given === Reading Headers and Other Metadata When receiving data from a given ==== [source,java,indent=0] .{examplesdir}/read/status/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/read/status/Application.java[lines=18..34] ---- <1> Obtains the status code. ==== === HTTP Response Decoder By default, * The maximum length of the initial line. * The maximum length of all headers. * The maximum length of the content or each chunk. For more information, see {nettyjavadoc}/io/netty/handler/codec/http/HttpResponseDecoder.html[HttpResponseDecoder] By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/HttpDecoderSpec.java ---- Unresolved directive in http-client.adoc - include::{sourcedir}/reactor/netty/http/HttpDecoderSpec.java[lines=28..40] ---- ==== ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/client/HttpResponseDecoderSpec.java ---- Unresolved directive in http-client.adoc - include::{sourcedir}/reactor/netty/http/client/HttpResponseDecoderSpec.java[lines=42..50] ---- ==== When you need to change these default settings, you can configure the ====
[source,java,indent=0]
.{examplesdir}/responsedecoder/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/responsedecoder/Application.java[lines=18..35]
----
<1> The maximum length of all headers will be == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked when the request has been sent. |
|
Invoked after the remote address has been resolved successfully. |
|
Invoked after the response has been fully received. |
|
Invoked when initializing the channel. |
|
Invoked when the channel is about to connect. |
|
Invoked after the channel has been connected. |
|
Invoked after the channel has been disconnected. |
|
Invoked when the request has not been sent and when the response has not been fully received. |
|
Invoked when the response headers have been received, and the request is about to be redirected. |
|
Invoked when the request is about to be sent. |
|
Invoked when the request has not been sent. |
|
Invoked when the remote address is about to be resolved. |
|
Invoked in case the remote address hasn’t been resolved successfully. |
|
Invoked after the response headers have been received. |
|
Invoked when the response has not been fully received. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..39]
----
<1> == TCP-level Configuration When you need configurations on a TCP level, you can use the following snippet
to extend the default ====
[source,java,indent=0]
.{examplesdir}/channeloptions/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..54]
----
<1> Configures the connection establishment timeout to 10 seconds.
<2> Enables TCP See [tcp-client] for more about :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == Connection Pool
By default, * This means that the implementation creates a new channel if someone tries to acquire a channel
as long as less than ==== [source,java,indent=0] ../../../reactor-netty-core/src/main/java/reactor/netty/ReactorNetty.java ---- / * Default max connections. Fallback to * 2 * available number of processors (but with a minimum value of 16) / public static final String POOL_MAX_CONNECTIONS = "reactor.netty.pool.maxConnections"; / * Default acquisition timeout (milliseconds) before error. If -1 will never wait to * acquire before opening a new * connection in an unbounded fashion. Fallback 45 seconds */ public static final String POOL_ACQUIRE_TIMEOUT = "reactor.netty.pool.acquireTimeout"; / * Default max idle time, fallback - max idle time is not specified. * <p><strong>Note:</strong> This configuration is not applicable for {@link reactor.netty.tcp.TcpClient}. * A TCP connection is always closed and never returned to the pool. */ public static final String POOL_MAX_IDLE_TIME = "reactor.netty.pool.maxIdleTime"; / * Default max life time, fallback - max life time is not specified. * <p><strong>Note:</strong> This configuration is not applicable for {@link reactor.netty.tcp.TcpClient}. * A TCP connection is always closed and never returned to the pool. */ public static final String POOL_MAX_LIFE_TIME = "reactor.netty.pool.maxLifeTime"; / * Default leasing strategy (fifo, lifo), fallback to fifo. * <ul> * <li>fifo - The connection selection is first in, first out</li> * <li>lifo - The connection selection is last in, first out</li> * </ul> * <p><strong>Note:</strong> This configuration is not applicable for {@link reactor.netty.tcp.TcpClient}. * A TCP connection is always closed and never returned to the pool. */ public static final String POOL_LEASING_STRATEGY = "reactor.netty.pool.leasingStrategy"; / * Default {@code getPermitsSamplingRate} (between 0d and 1d (percentage)) * to be used with a {@link SamplingAllocationStrategy}. * This strategy wraps a {@link PoolBuilder#sizeBetween(int, int) sizeBetween} {@link AllocationStrategy} * and samples calls to {@link AllocationStrategy#getPermits(int)}. * Fallback - sampling is not enabled. */ public static final String POOL_GET_PERMITS_SAMPLING_RATE = "reactor.netty.pool.getPermitsSamplingRate"; /* * Default {@code returnPermitsSamplingRate} (between 0d and 1d (percentage)) * to be used with a {@link SamplingAllocationStrategy}. * This strategy wraps a {@link PoolBuilder#sizeBetween(int, int) sizeBetween} {@link AllocationStrategy} * and samples calls to {@link AllocationStrategy#returnPermits(int)}. * Fallback - sampling is not enabled. */ public static final String POOL_RETURN_PERMITS_SAMPLING_RATE = "reactor.netty.pool.returnPermitsSamplingRate"; ---- ==== When you need to change the default settings, you can configure the ==== [source,java,indent=0] .{examplesdir}/pool/config/Application.java ---- Unresolved directive in http-client-conn-provider.adoc - include::{examplesdir}/pool/config/Application.java[lines=18..50] ---- <1> Configures the maximum time for a connection to stay idle to 20 seconds. <2> Configures the maximum time for a connection to stay alive to 60 seconds. <3> Configures the maximum time for the pending acquire operation to 60 seconds. <4> Every two minutes, the connection pool is regularly checked for connections that are applicable for removal. ==== NOTE: Notice that only the default The following listing shows the available configurations: [width="100%",options="header"] |
======= |
Configuration name |
Description |
|
When this option is enabled, connection pools are regularly checked in the background, and those that are empty and been inactive for a specified time become eligible for disposal. Connection pool is considered empty when there are no active connections, idle connections and pending acquisitions. By default, this background disposal of inactive pools is disabled. |
|
When |
|
When this option is enabled, each connection pool regularly checks for connections that are
eligible for removal according to eviction criteria like |
|
Configure the connection pool so that if there are idle connections (i.e. pool is under-utilized),
the next acquire operation will get the |
|
Configure the connection pool so that if there are idle connections (i.e. pool is under-utilized),
the next acquire operation will get the |
|
The maximum number of connections (per connection pool) before start pending. Default to 2 * available number of processors (but with a minimum value of 16). |
|
The time after which the channel is eligible to be closed when idle (resolution: ms). Default: max idle time is not specified. |
|
The total life time after which the channel is eligible to be closed (resolution: ms). Default: max life time is not specified. |
|
Enables/disables built-in integration with Micrometer. |
|
The maximum number of extra attempts at acquiring a connection to keep in a pending queue. If -1 is specified, the pending queue does not have upper limit. Default to 2 * max connections. |
|
The maximum time before which a pending acquire must complete, or a TimeoutException is thrown (resolution: ms). If -1 is specified, no such timeout is applied. Default: 45 seconds. |
======= NOTE: When you expect a high load, be cautious with a connection pool with a very high value for maximum connections. You might experience
If you need to disable the connection pool, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/pool/Application.java ---- Unresolved directive in http-client-conn-provider.adoc - include::{examplesdir}/pool/Application.java[lines=18..49] ---- ==== === Disposing Connection Pool - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom === Metrics
The pooled Pooled [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.total.connections |
Gauge |
The number of all connections, active or idle. See [observability-metrics-total-connections] |
reactor.netty.connection.provider.active.connections |
Gauge |
The number of the connections that have been successfully acquired and are in active use. See [observability-metrics-active-connections] |
reactor.netty.connection.provider.max.connections |
Gauge |
The maximum number of active connections that are allowed. See [observability-metrics-max-connections] |
reactor.netty.connection.provider.idle.connections |
Gauge |
The number of the idle connections. See [observability-metrics-idle-connections] |
reactor.netty.connection.provider.pending.connections |
Gauge |
The number of requests that are waiting for a connection. See [observability-metrics-pending-connections] |
reactor.netty.connection.provider.pending.connections.time |
Timer |
Time spent in pending acquire a connection from the connection pool. See [observability-metrics-pending-connections-time] |
reactor.netty.connection.provider.max.pending.connections |
Gauge |
The maximum number of requests that will be queued while waiting for a ready connection. See [observability-metrics-max-pending-connections] |
======= The following table provides information for the HTTP client metrics when it is configured to serve [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.active.streams |
Gauge |
The number of the active HTTP/2 streams. See [observability-metrics-active-streams] |
reactor.netty.connection.provider.pending.streams |
Gauge |
The number of requests that are waiting for opening HTTP/2 stream. See [observability-metrics-pending-streams] |
======= The following example enables that integration: ==== [source,java,indent=0] .{examplesdir}/pool/metrics/Application.java ---- Unresolved directive in http-client-conn-provider.adoc - include::{examplesdir}/pool/metrics/Application.java[lines=18..45] ---- <1> Enables the built-in integration with Micrometer ==== == SSL and TLS
When you need SSL or TLS, you can apply the configuration shown in the next example.
By default, if ==== [source,java,indent=0] .{examplesdir}/security/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/security/Application.java[lines=18..35] ---- ==== === Server Name Indication
By default, the ==== [source,java,indent=0] .{examplesdir}/sni/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/sni/Application.java[lines=18..39] ---- ==== == Retry Strategies
By default, the == HTTP/2 By default, the NOTE: As Application-Layer Protocol Negotiation (ALPN) is not supported “out-of-the-box” by JDK8 (although some vendors backported ALPN to JDK8), you need an additional dependency to a native library that
supports it — for example, The following listing presents a simple ====
[source,java,indent=0]
.{examplesdir}/http2/H2Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/http2/H2Application.java[lines=18..42]
----
<1> Configures the client to support only The following listing presents a simple ==== [source,java,indent=0] .{examplesdir}/http2/H2CApplication.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/http2/H2CApplication.java[lines=18..41] ---- ==== === Protocol Selection ==== [source,java,indent=0] .{sourcedir}/reactor/netty/http/HttpProtocol.java ---- Unresolved directive in http-client.adoc - include::{sourcedir}/reactor/netty/http/HttpProtocol.java[lines=24..52] ---- ==== == Proxy Support Reactor Netty supports the proxy functionality provided by Netty and provides a way
to specify Netty’s HTTP proxy support always uses The following example uses ==== [source,java,indent=0] .{examplesdir}/proxy/Application.java ---- Unresolved directive in proxy.adoc - include::{examplesdir}/proxy/Application.java[lines=18..42] ---- <1> Configures the connection establishment timeout to 20 seconds. ==== == Metrics
The HTTP client supports built-in integration with The following table provides information for the HTTP client metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.http.client.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.http.client.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.http.client.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
reactor.netty.http.client.tls.handshake.time |
Timer |
Time spent for TLS handshake. See [observability-metrics-tls-handshake-time] |
reactor.netty.http.client.connect.time |
Timer |
Time spent for connecting to the remote address. See [observability-metrics-connect-time] |
reactor.netty.http.client.address.resolver |
Timer |
Time spent for resolving the address. See [observability-metrics-hostname-resolution-time] |
reactor.netty.http.client.data.received.time |
Timer |
Time spent in consuming incoming data. See [observability-metrics-http-client-data-received-time] |
reactor.netty.http.client.data.sent.time |
Timer |
Time spent in sending outgoing data. See [observability-metrics-http-client-data-sent-time] |
reactor.netty.http.client.response.time |
Timer |
Total time for the request/response See [observability-metrics-http-client-response-time] |
======= These additional metrics are also available: Pooled [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.total.connections |
Gauge |
The number of all connections, active or idle. See [observability-metrics-total-connections] |
reactor.netty.connection.provider.active.connections |
Gauge |
The number of the connections that have been successfully acquired and are in active use. See [observability-metrics-active-connections] |
reactor.netty.connection.provider.max.connections |
Gauge |
The maximum number of active connections that are allowed. See [observability-metrics-max-connections] |
reactor.netty.connection.provider.idle.connections |
Gauge |
The number of the idle connections. See [observability-metrics-idle-connections] |
reactor.netty.connection.provider.pending.connections |
Gauge |
The number of requests that are waiting for a connection. See [observability-metrics-pending-connections] |
reactor.netty.connection.provider.pending.connections.time |
Timer |
Time spent in pending acquire a connection from the connection pool. See [observability-metrics-pending-connections-time] |
reactor.netty.connection.provider.max.pending.connections |
Gauge |
The maximum number of requests that will be queued while waiting for a ready connection. See [observability-metrics-max-pending-connections] |
======= The following table provides information for the HTTP client metrics when it is configured to serve [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.connection.provider.active.streams |
Gauge |
The number of the active HTTP/2 streams. See [observability-metrics-active-streams] |
reactor.netty.connection.provider.pending.streams |
Gauge |
The number of requests that are waiting for opening HTTP/2 stream. See [observability-metrics-pending-streams] |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |
Gauge |
The number of tasks that are pending for processing on an event loop. See [observability-metrics-pending-tasks] |
======= The following example enables that integration: ====
[source,java,indent=0]
.{examplesdir}/metrics/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/metrics/Application.java[lines=18..51]
----
<1> Applies upper limit for the meters with NOTE: In order to avoid a memory and CPU overhead of the enabled metrics, it is important to convert the real URIs to templated URIs when possible. Without a conversion to a template-like form, each distinct URI leads to the creation of a distinct tag, which takes a lot of memory for the metrics. NOTE: Always apply an upper limit for the meters with URI tags. Configuring an upper limit on the number of meters can help in cases when the real URIs cannot be templated.
You can find more information at When HTTP client metrics are needed for an integration with a system other than ====
[source,java,indent=0]
.{examplesdir}/metrics/custom/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/metrics/custom/Application.java[lines=18..35]
----
<1> Enables HTTP client metrics and provides {javadoc}/reactor/netty/http/client/HttpClientMetricsRecorder.html[ == Tracing
The HTTP client supports built-in integration with The following table provides information for the HTTP client spans: [width="100%",options="header"] |
======= |
contextual name |
description |
HTTP <HTTP METHOD> |
Information and total time for the request. See [observability-spans-http-client-response-span]. |
hostname resolution |
Information and time spent for resolving the address. See [observability-spans-hostname-resolution-span]. |
connect |
Information and time spent for connecting to the remote address. See [observability-spans-connect-span]. |
tls handshake |
Information and time spent for TLS handshake. See [observability-spans-tls-handshake-span]. |
======= The following example enables that integration. This concrete example uses ==== [source,java,indent=0] .{examplesdir}/tracing/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/tracing/Application.java[lines=18..90] ---- <1> Initializes Brave, Zipkin, and the Observation registry. <2> Templated URIs are used as an URI tag value when possible. <3> Enables the built-in integration with Micrometer. ==== The result in image::images/http-client-tracing.png[] === Access Current Observation
Project Micrometer provides The following example shows how to use this library in a custom ====
[source,java,indent=0]
.{examplesdir}/tracing/custom/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/tracing/custom/Application.java[lines=18..85]
----
<1> Initializes Brave, Zipkin, and the Observation registry.
<2> Templated URIs are used as an URI tag value when possible.
<3> Enables the built-in integration with Micrometer.
<4> Custom NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the == Unix Domain Sockets
The The following example shows how to use UDS support: ====
[source,java,indent=0]
.{examplesdir}/uds/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/uds/Application.java[lines=18..33]
----
<1> Specifies == Host Name Resolution
By default, the When you need to change the default settings, you can configure the ==== [source,java,indent=0] .{examplesdir}/resolver/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/resolver/Application.java[lines=18..39] ---- <1> The timeout of each DNS query performed by this resolver will be 500ms. ==== The following listing shows the available configurations.
Additionally, [width="100%",options="header"] |
======= |
Configuration name |
Description |
|
The supplier of the local address to bind to. |
|
The max time to live of the cached DNS resource records (resolution: seconds).
If the time to live of the DNS resource record returned by the DNS server is greater
than this max time to live, this resolver ignores the time to live from
the DNS server and uses this max time to live.
Default to |
|
The min time to live of the cached DNS resource records (resolution: seconds). If the time to live of the DNS resource record returned by the DNS server is less than this min time to live, this resolver ignores the time to live from the DNS server and uses this min time to live. Default: 0. |
|
The time to live of the cache for the failed DNS queries (resolution: seconds). Default: 0. |
|
When this setting is enabled, the resolver notifies as soon as all queries for the preferred address type are complete.
When this setting is disabled, the resolver notifies when all possible address types are complete.
This configuration is applicable for |
|
Disables the automatic inclusion of an optional record that tries to give a hint to the remote DNS server about how much data the resolver can read per response. By default, this setting is enabled. |
|
Specifies whether this resolver has to send a DNS query with the recursion desired (RD) flag set. By default, this setting is enabled. |
|
Sets a custom function to create a |
|
Sets a custom {nettyjavadoc}/io/netty/resolver/HostsFileEntriesResolver.html[ |
|
Sets the capacity of the datagram packet buffer (in bytes). Default: 4096. |
|
Sets the maximum allowed number of DNS queries to send when resolving a host name. Default: 16. |
|
Sets the number of dots that must appear in a name before an initial absolute query is made. Default: -1 (to determine the value from the OS on Unix or use a value of 1 otherwise). |
|
Sets the timeout of each DNS query performed by this resolver (resolution: milliseconds). Default: 5000. |
|
The cache to use to store resolved DNS entries. |
|
The list of the protocol families of the resolved address. |
|
Specifies whether this resolver will also fallback to TCP if a timeout is detected. By default, the resolver will only try to use TCP if the response is marked as truncated. |
|
Enables an
{nettyjavadoc}/io/netty/resolver/AddressResolverGroup.html[ |
|
Performs the communication with the DNS servers on the given
{javadoc}/reactor/netty/resources/LoopResources.html[ |
|
The list of search domains of the resolver. By default, the effective search domain list is populated by using the system DNS search domains. |
|
A specific logger and log level to be used by this resolver when generating detailed trace information in case of resolution failure. |
======= Sometimes, you may want to switch to the JVM built-in resolver. To do so, you can configure the ==== [source,java,indent=0] .{examplesdir}/resolver/custom/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/resolver/custom/Application.java[lines=18..38] ---- <1> Sets the JVM built-in resolver. ====
== Timeout Configuration
This section describes various timeout configuration options that can be used in * [connection-pool-timeout] * [http-client-timeout] [response-timeout] [connection-timeout] [ssl-tls-timeout] [proxy-timeout] [dns-timeout]
=== Connection Pool Timeout
By default, The following list describes the available timeout configuration options: * NOTE: When you configure * By default, these timeouts are checked on connection To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/pool/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/pool/config/Application.java[lines=18..50] ---- <1> Configures the maximum time for a connection to stay idle to 20 seconds. <2> Configures the maximum time for a connection to stay alive to 60 seconds. <3> Configures the maximum time for the pending acquire operation to 60 seconds. <4> Every two minutes, the connection pool is regularly checked for connections that are applicable for removal. ====
=== HttpClient Timeout
This section provides information for the various timeout configuration options at the NOTE: Reactor Netty uses Reactor Core as its Reactive Streams implementation, and you may want to use the
==== Response Timeout
NOTE: It is always a good practice to configure a response timeout. To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/read/timeout/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/read/timeout/Application.java[lines=18..55] ---- <1> Configures the default response timeout to 1 second. <2> Configures a response timeout for a specific request to 2 seconds. ==== ==== Connection Timeout The following listing shows all available connection timeout configuration options, but some of them may apply only to a specific transport. * NOTE: Sometimes, between the client and the server, you may have a network component that silently drops the idle connections without sending a response.
From the Reactor Netty point of view, in this use case, the remote peer just does not respond.
To be able to handle such a use case you may consider configuring
To customize the default settings, you can configure ====
[source,java,indent=0]
.{examplesdir}/channeloptions/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..54]
----
<1> Configures the connection establishment timeout to 10 seconds.
<2> Enables TCP
==== SSL/TLS Timeout
The following list describes the available timeout configuration options: * NOTE: You should consider increasing the SSL handshake timeout when expecting slow network connections. * To customize the default settings, you can configure ====
[source,java,indent=0]
.{examplesdir}/security/custom/Application.java
----
Unresolved directive in http-client.adoc - include::{examplesdir}/security/custom/Application.java[lines=18..45]
----
<1> Configures the SSL handshake timeout to 30 seconds.
<2> Configures the SSL
==== Proxy Timeout
To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/proxy/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/proxy/Application.java[lines=18..42] ---- <1> Configures the connection establishment timeout to 20 seconds. ====
==== Host Name Resolution Timeout
By default, the The following list describes the available timeout configuration options: * To customize the default settings, you can configure ==== [source,java,indent=0] .{examplesdir}/resolver/Application.java ---- Unresolved directive in http-client.adoc - include::{examplesdir}/resolver/Application.java[lines=18..39] ---- <1> The timeout of each DNS query performed by this resolver will be 500ms. ==== :leveloffset: 3 Suggest Edit to "[http-client]" :leveloffset: 1 :sourcedir: ./../../reactor-netty-core/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/server :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.udp.UdpServer Reactor Netty provides the easy-to-use and easy-to-configure
{javadoc}/reactor/netty/udp/UdpServer.html[ == Starting and Stopping To start a UDP server, a {javadoc}/reactor/netty/udp/UdpServer.html[UdpServer]
instance has to be created and configured.
By default, the host is configured to be ====
[source,java,indent=0]
.{examplesdir}/create/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/create/Application.java[lines=18..32]
----
<1> Creates a {javadoc}/reactor/netty/udp/UdpServer.html[ The returned {javadoc}/reactor/netty/Connection.html[ === Host and Port In order to serve on a specific host and port, you can apply the following configuration to the ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/address/Application.java[lines=18..34]
----
<1> Configures the NOTE: The port can be specified also with PORT environment variable. == Eager Initialization By default, the initialization of the * the event loop group * the native transport libraries (when native transport is used) When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in udp-server.adoc - include::{examplesdir}/warmup/Application.java[lines=18..51] ---- <1> Initialize and load the event loop group and the native transport libraries ==== == Writing Data To send data to the remote peer, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/udp/UdpOutbound.html[ ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/send/Application.java[lines=18..51]
----
<1> Sends a == Consuming Data To receive data from a remote peer, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/udp/UdpInbound.html[ ==== [source,java,indent=0] .{examplesdir}/read/Application.java ---- Unresolved directive in udp-server.adoc - include::{examplesdir}/read/Application.java[lines=18..47] ---- <1> Receives data from the remote peer ==== == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked when the server channel is about to bind. |
|
Invoked when the server channel is bound. |
|
Invoked when initializing the channel. |
|
Invoked when the server channel is unbound. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..39]
----
<1> == Connection Configuration This section describes three kinds of configuration that you can use at the UDP level: * [server-udp-connection-configurations-channel-options] * [server-udp-connection-configurations-wire-logger] * [server-udp-connection-configurations-event-loop-group] By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/udp/UdpServerBind.java ---- Unresolved directive in udp-server.adoc - include::{sourcedir}/reactor/netty/udp/UdpServerBind.java[lines=40..44] ---- ==== If you need additional options or need to change the current options, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/channeloptions/Application.java ---- Unresolved directive in udp-server.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..34] ---- ==== For more information about Netty channel options, see the following links: * {nettyjavadoc}/io/netty/channel/ChannelOption.html[Common ChannelOption] * {nettyjavadoc}/io/netty/channel/epoll/EpollChannelOption.html[Epoll ChannelOption] * {nettyjavadoc}/io/netty/channel/kqueue/KQueueChannelOption.html[KQueue ChannelOption] * Socket Options :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == Metrics
The UDP server supports built-in integration with The following table provides information for the UDP server metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.udp.server.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.udp.server.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.udp.server.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
======= These additional metrics are also available:
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |
Gauge |
The number of tasks that are pending for processing on an event loop. See [observability-metrics-pending-tasks] |
======= The following example enables that integration: ==== [source,java,indent=0] .{examplesdir}/metrics/Application.java ---- Unresolved directive in udp-server.adoc - include::{examplesdir}/metrics/Application.java[lines=18..34] ---- <1> Enables the built-in integration with Micrometer ==== When UDP server metrics are needed for an integration with a system other than ====
[source,java,indent=0]
.{examplesdir}/metrics/custom/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/metrics/custom/Application.java[lines=18..35]
----
<1> Enables UDP server metrics and provides {javadoc}/reactor/netty/channel/ChannelMetricsRecorder.html[ == Unix Domain Sockets
The The following example shows how to use UDS support: ====
[source,java,indent=0]
.{examplesdir}/uds/Application.java
----
Unresolved directive in udp-server.adoc - include::{examplesdir}/uds/Application.java[lines=18..48]
----
<1> Specifies :leveloffset: 3 Suggest Edit to "[udp-server]" :leveloffset: 1 :sourcedir: ./../../reactor-netty-core/src/main/java :examplesdir: ./../../reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/udp/client :javadoc: https://projectreactor.io/docs/netty/1.1.25-SNAPSHOT/api :nettyjavadoc: https://netty.io/4.1/api :wirelogger: reactor.netty.udp.UdpClient Reactor Netty provides the easy-to-use and easy-to-configure
{javadoc}/reactor/netty/udp/UdpClient.html[ == Connecting and Disconnecting To connect the UDP client to a given endpoint, you must create and configure a
{javadoc}/reactor/netty/udp/UdpClient.html[UdpClient] instance.
By default, the host is configured for ====
[source,java,indent=0]
.{examplesdir}/create/Application.java
----
Unresolved directive in udp-client.adoc - include::{examplesdir}/create/Application.java[lines=18..32]
----
<1> Creates a {javadoc}/reactor/netty/udp/UdpClient.html[ The returned {javadoc}/reactor/netty/Connection.html[ === Host and Port To connect to a specific ====
[source,java,indent=0]
.{examplesdir}/address/Application.java
----
Unresolved directive in udp-client.adoc - include::{examplesdir}/address/Application.java[lines=18..34]
----
<1> Configures the NOTE: The port can be specified also with PORT environment variable. == Eager Initialization By default, the initialization of the * the event loop group * the host name resolver * the native transport libraries (when native transport is used) When you need to preload these resources, you can configure the ==== [source,java,indent=0] .{examplesdir}/warmup/Application.java ---- Unresolved directive in udp-client.adoc - include::{examplesdir}/warmup/Application.java[lines=18..40] ---- <1> Initialize and load the event loop group, the host name resolver, and the native transport libraries <2> Host name resolution happens when connecting to the remote peer ==== == Writing Data To send data to a given peer, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/udp/UdpOutbound.html[ The following example shows how to send ====
[source,java,indent=0]
.{examplesdir}/send/Application.java
----
Unresolved directive in udp-client.adoc - include::{examplesdir}/send/Application.java[lines=18..37]
----
<1> Sends == Consuming Data To receive data from a given peer, you must attach an I/O handler.
The I/O handler has access to {javadoc}/reactor/netty/udp/UdpInbound.html[ ==== [source,java,indent=0] .{examplesdir}/read/Application.java ---- Unresolved directive in udp-client.adoc - include::{examplesdir}/read/Application.java[lines=18..35] ---- <1> Receives data from a given peer ==== == Lifecycle Callbacks The following lifecycle callbacks are provided to let you extend the [width="100%",options="header"] |
======= |
Callback |
Description |
|
Invoked after the remote address has been resolved successfully. |
|
Invoked when initializing the channel. |
|
Invoked when the channel is about to connect. |
|
Invoked after the channel has been connected. |
|
Invoked after the channel has been disconnected. |
|
Invoked when the remote address is about to be resolved. |
|
Invoked in case the remote address hasn’t been resolved successfully. |
======= The following example uses the ====
[source,java,indent=0]
.{examplesdir}/lifecycle/Application.java
----
Unresolved directive in udp-client.adoc - include::{examplesdir}/lifecycle/Application.java[lines=18..40]
----
<1> == Connection Configuration This section describes three kinds of configuration that you can use at the UDP level: * [client-udp-connection-configurations-channel-options] * [client-udp-connection-configurations-wire-logger] * [client-udp-connection-configurations-event-loop-group] By default, the ==== [source,java,indent=0] .{sourcedir}/reactor/netty/udp/UdpClientConnect.java ---- Unresolved directive in udp-client.adoc - include::{sourcedir}/reactor/netty/udp/UdpClientConnect.java[lines=37..42] ---- ==== If you need additional options or need to change the current options, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/channeloptions/Application.java ---- Unresolved directive in udp-client.adoc - include::{examplesdir}/channeloptions/Application.java[lines=18..36] ---- ==== You can find more about Netty channel options at the following links: * {nettyjavadoc}/io/netty/channel/ChannelOption.html[Common ChannelOption] * {nettyjavadoc}/io/netty/channel/epoll/EpollChannelOption.html[Epoll ChannelOption] * {nettyjavadoc}/io/netty/channel/kqueue/KQueueChannelOption.html[KQueue ChannelOption] * Socket Options :formattersourcedir: ./../../reactor-netty-core/src/main/java === Wire Logger Reactor Netty provides wire logging for when the traffic between the peers needs to be inspected.
By default, wire logging is disabled.
To enable it, you must set the logger ==== [source,java,indent=0] .{examplesdir}/wiretap/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/Application.java[lines=18..35] ---- <1> Enables the wire logging ==== ==== Wire Logger formatters Reactor Netty supports 3 different formatters: - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#HEX_DUMP[AdvancedByteBufFormat#HEX_DUMP] - the default ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=47..75] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#SIMPLE[AdvancedByteBufFormat#SIMPLE] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=34..45] ---- ==== - {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] ==== [source,java,indent=0] .{sourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java ---- Unresolved directive in wire-logger.adoc - include::{formattersourcedir}/reactor/netty/transport/logging/AdvancedByteBufFormat.java[lines=77..93] ---- ==== When you need to change the default formatter you can configure it as follows: ==== [source,java,indent=0] .{examplesdir}/wiretap/custom/Application.java ---- Unresolved directive in wire-logger.adoc - include::{examplesdir}/wiretap/custom/Application.java[lines=18..38] ---- <1> Enables the wire logging, {javadoc}/reactor/netty/transport/logging/AdvancedByteBufFormat.html#TEXTUAL[AdvancedByteBufFormat#TEXTUAL] is used for printing the content. ==== :eventloopsourcedir: ./../../reactor-netty-core/src/main/java === Event Loop Group By default The following listing shows the default configuration for the Event Loop Group: ==== [source,java,indent=0] .{eventloopsourcedir}/reactor/netty/ReactorNetty.java ---- Unresolved directive in eventloop.adoc - include::{eventloopsourcedir}/reactor/netty/ReactorNetty.java[lines=87..121] ---- ==== If you need changes to these settings, you can apply the following configuration: ==== [source,java,indent=0] .{examplesdir}/eventloop/Application.java ---- Unresolved directive in eventloop.adoc - include::{examplesdir}/eventloop/Application.java[lines=18..38] ---- ==== ==== Disposing Event Loop Group - If you use the default NOTE: Disposing - If you use custom NOTE: Disposing the custom == Metrics
The UDP client supports built-in integration with The following table provides information for the UDP client metrics: [width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.udp.client.data.received |
DistributionSummary |
Amount of the data received, in bytes. See [observability-metrics-data-received] |
reactor.netty.udp.client.data.sent |
DistributionSummary |
Amount of the data sent, in bytes. See [observability-metrics-data-sent] |
reactor.netty.udp.client.errors |
Counter |
Number of errors that occurred. See [observability-metrics-errors-count] |
reactor.netty.udp.client.connect.time |
Timer |
Time spent for connecting to the remote address. See [observability-metrics-connect-time] |
reactor.netty.udp.client.address.resolver |
Timer |
Time spent for resolving the address. See [observability-metrics-hostname-resolution-time] |
======= These additional metrics are also available:
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.bytebuf.allocator.used.heap.memory |
Gauge |
The number of bytes reserved by heap buffer allocator. See [observability-metrics-used-heap-memory] |
reactor.netty.bytebuf.allocator.used.direct.memory |
Gauge |
The number of bytes reserved by direct buffer allocator. See [observability-metrics-used-direct-memory] |
reactor.netty.bytebuf.allocator.heap.arenas |
Gauge |
The number of heap arenas (when |
reactor.netty.bytebuf.allocator.direct.arenas |
Gauge |
The number of direct arenas (when |
reactor.netty.bytebuf.allocator.threadlocal.caches |
Gauge |
The number of thread local caches (when |
reactor.netty.bytebuf.allocator.small.cache.size |
Gauge |
The size of the small cache (when |
reactor.netty.bytebuf.allocator.normal.cache.size |
Gauge |
The size of the normal cache (when |
reactor.netty.bytebuf.allocator.chunk.size |
Gauge |
The chunk size for an arena (when |
reactor.netty.bytebuf.allocator.active.heap.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from heap buffer pools (when |
reactor.netty.bytebuf.allocator.active.direct.memory |
Gauge |
The actual bytes consumed by in-use buffers allocated from direct buffer pools (when |
=======
[width="100%",options="header"] |
======= |
metric name |
type |
description |
reactor.netty.eventloop.pending.tasks |