This is an automated email from the ASF dual-hosted git repository.
pjfanning pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko-http.git
The following commit(s) were added to refs/heads/main by this push:
new 44455d784 docs: add 1.x to 2.x migration guide listing configuration
changes (#1334)
44455d784 is described below
commit 44455d7844ecf9dbf0fb0531be6682b93f1c78b7
Author: PJ Fanning <[email protected]>
AuthorDate: Fri Oct 23 21:20:26 2026 +0100
docs: add 1.x to 2.x migration guide listing configuration changes (#1334)
* docs: add 1.x to 2.x migration guide listing configuration changes
Motivation:
There was no Pekko HTTP 1.x to 2.x migration guide, so users had no
single place to review new settings and changed defaults in the
reference.conf files when upgrading.
Modification:
Add migration-guide-1.x-2.x.md with a Configuration Changes section
covering changed default values, removed settings and new settings,
grouped by module, with links to the originating PRs and the relevant
docs pages. Link it from the migration guide index.
Result:
Users migrating from Pekko HTTP 1.x to 2.x can review the
configuration changes in one place.
Tests:
- sbt docs/paradox
References:
None - sourced from diffing reference.conf files between the 1.4.x
and main branches
* docs: show jackson, jackson3 and testkit reference.conf in configuration
page
Motivation:
The configuration page said modules other than core, routing, caching
and cors have no configuration, but pekko-http-jackson,
pekko-http-jackson3 and pekko-http-testkit all ship a reference.conf.
Modification:
Add snippets of those reference.conf files to configuration.md.
Result:
The configuration reference covers every module with settings.
Tests:
- sbt docs/paradox
References:
None
* docs: fix inaccuracies and gaps found reviewing the 2.x migration guide
Motivation:
A review of the 1.x to 2.x migration guide and the pages it links to
found inaccuracies, missing migration notes and broken links.
Modification:
- Add a General changes section to the migration guide (minimum Pekko,
Java and Scala versions, removed deprecated code, Java DSL Duration
return types, Jackson 3 module).
- Correct how pekko.http.server.preview.enable-http2 interacts with
pekko.http.server.enable-http2, and note that the RST_STREAM throttle
fails connections that exceed the limit.
- Note that browser WebSocket connections are compressed by default and
that the new chunk and part count limits may need raising.
- Note that pekko.http.testkit.routes.timeout applies to the Scala
testkit, link it from the testkit page and fix a typo there.
- Fix testkit example links that pointed at non-existent akka paths.
- Remove a leftover TODO from the Java marshalling docs that linked to a
non-existent pekko-http issue (it referred to akka/akka-http#1367).
- Document max-chunk-count in reference.conf.
Result:
The migration guide and the linked pages are accurate and the source
links resolve.
Tests:
- sbt docs/paradox
- docs/paradoxValidateInternalLinks reports the same 19 errors as main,
none in changed files
References:
None
* docs: add API and behavior changes merged since to the 2.x migration guide
Motivation:
PRs merged to main after the migration guide was written changed API
stability, binary signatures and runtime behavior in ways that users
upgrading from 1.x should know about.
Modification:
- General changes: APIs no longer marked @ApiMayChange (#1364), and the
removed implicit JavaMapping parameter on HttpMessage.attribute and
ResponseEntity.fromJava (#1340).
- New Behavior changes section: the client pool closing the connection
after an early response (#1350), stricter HTTP/1.1 and HTTP/2 request
parsing (#1341, #1343), NUL in chunk extensions dropped (#1344), Link
parameter values with ':' quoted (#1365), and escaped parse error
details (#1294).
Result:
The migration guide covers the changes merged up to #1370.
Tests:
- Not run locally - doc-only change, CI builds the docs
References:
None - sourced from the commits merged to main since #1333
* docs: include 1.4.x behavior changes in the 2.x migration guide
Motivation:
Users may upgrade to 2.x from a Pekko HTTP release older than 1.4, so
the behavior changes made in 1.4.x releases also apply to them.
Modification:
Add the behavior changes from the 1.4.0, 1.4.1 and 1.4.2 release notes
(Content-Length rendering and parsing, header and chunk validation,
HTTP/2 field checks, CORS origins, file directives and SSE parsing),
each noting the release that introduced it, and group the section by
area.
Result:
Users upgrading from any 1.x release can find the behavior changes
that affect them in one place.
Tests:
- Not run locally - doc-only change, CI builds the docs
References:
None - sourced from the 1.4.x release notes and the linked PRs
---
docs/src/main/paradox/common/marshalling.md | 2 -
docs/src/main/paradox/configuration.md | 9 +
docs/src/main/paradox/migration-guide/index.md | 6 +
.../migration-guide/migration-guide-1.x-2.x.md | 187 +++++++++++++++++++++
docs/src/main/paradox/routing-dsl/testkit.md | 6 +-
http-core/src/main/resources/reference.conf | 4 +
6 files changed, 209 insertions(+), 5 deletions(-)
diff --git a/docs/src/main/paradox/common/marshalling.md
b/docs/src/main/paradox/common/marshalling.md
index ef77ce347..37d595546 100644
--- a/docs/src/main/paradox/common/marshalling.md
+++ b/docs/src/main/paradox/common/marshalling.md
@@ -1,7 +1,5 @@
# Marshalling
-@java[TODO @github[overhaul for Java](#1367)]
-
Marshalling is the process of converting a higher-level (object) structure
into some kind of lower-level
representation, often a "wire format". Other popular names for marshalling are
"serialization" or "pickling".
diff --git a/docs/src/main/paradox/configuration.md
b/docs/src/main/paradox/configuration.md
index 6c39ca496..952cfd761 100644
--- a/docs/src/main/paradox/configuration.md
+++ b/docs/src/main/paradox/configuration.md
@@ -18,4 +18,13 @@ pekko-http-caching
pekko-http-cors
: @@snip [reference.conf](/http-cors/src/main/resources/reference.conf)
+pekko-http-jackson
+: @@snip
[reference.conf](/http-marshallers-java/http-jackson/src/main/resources/reference.conf)
+
+pekko-http-jackson3
+: @@snip
[reference.conf](/http-marshallers-java/http-jackson3/src/main/resources/reference.conf)
+
+pekko-http-testkit
+: @@snip [reference.conf](/http-testkit/src/main/resources/reference.conf)
+
The other Apache Pekko HTTP modules do not offer any configuration via
[Typesafe Config](https://github.com/lightbend/config).
diff --git a/docs/src/main/paradox/migration-guide/index.md
b/docs/src/main/paradox/migration-guide/index.md
index 2cd78f2a0..6fa4a887e 100644
--- a/docs/src/main/paradox/migration-guide/index.md
+++ b/docs/src/main/paradox/migration-guide/index.md
@@ -2,6 +2,12 @@
@@toc { depth=3 }
+@@@ index
+
+* [migration-guide-1.x-2.x](migration-guide-1.x-2.x.md)
+
+@@@
+
* If you are currently using an old version of Akka HTTP or Spray, you should
first follow the [Akka HTTP migration
guide](https://doc.akka.io/docs/akka-http/10.2/migration-guide/index.html)
* The @extref:[migration guide](pekko-docs:migration/index.html) for the core
Apache Pekko libs is a useful guideline.
* for Pekko jar dependencies, the groupId is "org.apache.pekko" instead of
"com.typesafe.akka"
diff --git a/docs/src/main/paradox/migration-guide/migration-guide-1.x-2.x.md
b/docs/src/main/paradox/migration-guide/migration-guide-1.x-2.x.md
new file mode 100644
index 000000000..486d5a852
--- /dev/null
+++ b/docs/src/main/paradox/migration-guide/migration-guide-1.x-2.x.md
@@ -0,0 +1,187 @@
+# Migration from Apache Pekko HTTP 1.x to 2.x
+
+Apache Pekko HTTP 2.x requires Apache Pekko 2.x. See the
+@extref:[Pekko 1.x to 2.x migration
guide](pekko-docs:migration/migration-guide-1.x-2.x.html) for the changes in
the core
+Pekko libraries.
+
+## General changes
+
+* Apache Pekko 2.x is the new minimum Pekko version.
+* Java 17 is the new minimum Java version.
+* Scala 2.12 is no longer supported.
+* Deprecated code has been removed, including a number of util classes that
existed for compatibility across
+Scala versions. Before upgrading, build against the latest Pekko HTTP 1.x
release and fix any deprecation warnings.
+* Java DSL methods that returned a Scala `Duration` now return a
`java.time.Duration`.
+([PR788](https://github.com/apache/pekko-http/pull/788))
+* The new `pekko-http-jackson3` module supports Jackson 3. See the
configuration change below.
+* `ClientTransport`, `RequestResponseAssociation`,
`SimpleRequestResponseAttribute`, the Java DSL `anyOf`/`allOf`
+directive combinators and the `storeUploadedFile`, `storeUploadedFiles` and
`fileUploadAll` directives are no longer
+marked `@ApiMayChange` and are now stable APIs.
([PR1364](https://github.com/apache/pekko-http/pull/1364))
+* `HttpMessage.attribute` and the `ResponseEntity.fromJava` implicit
conversion no longer take an implicit
+`JavaMapping` parameter, so they can be used from Scala 3.10. This is source
compatible but changes their binary
+signatures. ([PR1340](https://github.com/apache/pekko-http/pull/1340))
+
+## Behavior changes
+
+Some of the changes listed below were made in Pekko HTTP 1.4.x releases. They
are included here for users upgrading
+from older 1.x versions, with a note of the release that introduced them.
+
+### HTTP/1.1 parsing and rendering
+
+* Whether a response renders `Content-Length` now depends on the request
method as well as the status code, following
+RFC 9110: a `2xx` response to `CONNECT` no longer renders it, and a `205 Reset
Content` response now does.
+`HttpMethod.custom` has a new overload with a `contentLengthAllowed`
parameter; the old overload is deprecated.
+Added in Pekko HTTP 1.4.0
([PR968](https://github.com/apache/pekko-http/pull/968)).
+A `HEAD` response renders `Content-Length` only when its entity declares a
length greater than zero. Added in Pekko
+HTTP 1.4.1 ([PR1244](https://github.com/apache/pekko-http/pull/1244))
+* A `Content-Length` value with whitespace between its digits, or without any
digit, is rejected; it was previously
+read as the concatenated digits, or as `0`. Added in Pekko HTTP 1.4.1
([PR1243](https://github.com/apache/pekko-http/pull/1243))
+* Repeated `Connection` headers count towards
`pekko.http.parsing.max-header-count`. Added in Pekko HTTP 1.4.1
+([PR1268](https://github.com/apache/pekko-http/pull/1268))
+* A message whose `Transfer-Encoding` value cannot be parsed is rejected.
Added in Pekko HTTP 1.4.2
+([PR1267](https://github.com/apache/pekko-http/pull/1267))
+* Whitespace between or before chunk-size digits is rejected; trailing
whitespace is still tolerated. Added in Pekko
+HTTP 1.4.2 ([PR1257](https://github.com/apache/pekko-http/pull/1257))
+* A request line where a CR or LF ends the request target is rejected with
`505 HTTP Version Not Supported`.
+([PR1341](https://github.com/apache/pekko-http/pull/1341))
+* Headers whose rendered name or value contains CR, LF or NUL are dropped
instead of being sent. This covers trailer
+headers and chunk extensions as well as the main header block.
+Added in Pekko HTTP 1.4.1 for CR and LF in trailers and chunk extensions
([PR1270](https://github.com/apache/pekko-http/pull/1270))
+and NUL in headers ([PR1272](https://github.com/apache/pekko-http/pull/1272));
chunk extensions containing NUL are
+dropped from Pekko HTTP 2.0.0
([PR1344](https://github.com/apache/pekko-http/pull/1344)).
+* `Link` header parameter values that contain a `:`, such as URI relation
types, are now rendered quoted
+(`rel="http://example.net/foo"`), as RFC 8288 requires. The unquoted form is
still accepted when parsing.
+([PR1365](https://github.com/apache/pekko-http/pull/1365))
+* Parse error details logged with `pekko.http.parsing.error-logging-verbosity
= full` (the default), and the
+`toString` of `IllegalRequestContext` passed to a custom
`ParsingErrorHandler`, now escape control characters in the
+raw request target or header value.
([PR1294](https://github.com/apache/pekko-http/pull/1294))
+
+### HTTP/2
+
+* Outgoing header fields whose name or value contains CR, LF or NUL are
dropped. Added in Pekko HTTP 1.4.1
+([PR1271](https://github.com/apache/pekko-http/pull/1271))
+* An incoming request with a header field containing CR, LF or NUL is
rejected. In Pekko HTTP 1.4.2 the connection is
+closed with `GOAWAY(PROTOCOL_ERROR)`; from Pekko HTTP 2.0.0 the stream is
answered with `400 Bad Request` and the
+connection is kept. ([PR1297](https://github.com/apache/pekko-http/pull/1297))
+* A request with an invalid `:scheme` pseudo-header, or with a regular field
name containing `:`, is rejected with a
+`400 Bad Request` for that stream; an invalid `:scheme` no longer fails the
whole connection.
+([PR1341](https://github.com/apache/pekko-http/pull/1341))
+* A field name containing an uppercase letter or another character that RFC
9113 excludes, or a field value with
+leading or trailing whitespace, makes the request (`400 Bad Request` for that
stream) or response (protocol error)
+malformed instead of being silently normalized. Pekko HTTP's own client and
server always send lowercase field names.
+([PR1343](https://github.com/apache/pekko-http/pull/1343))
+
+### Client
+
+* After an early response (a response that completes before the streamed
request entity has been fully sent), the
+client connection pool no longer reuses the connection. If the response is an
error (4xx or 5xx) or carries
+`Connection: close`, the pool stops sending the request entity and closes the
connection immediately; otherwise it
+finishes sending the request entity and then closes the connection.
([PR1350](https://github.com/apache/pekko-http/pull/1350))
+
+### Routing DSL
+
+* The CORS directives accept an actual request only when every origin in its
`Origin` header is allowed, instead of
+when any one of them is. Added in Pekko HTTP 1.4.2
([PR1262](https://github.com/apache/pekko-http/pull/1262))
+* `FileAndResourceDirectives` compare path elements, rather than string
prefixes, when checking that a served file
+is below the base directory, so a symbolic link to a sibling directory such as
`/var/www-private` is no longer served
+from `/var/www`. Added in Pekko HTTP 1.4.1
([PR1269](https://github.com/apache/pekko-http/pull/1269))
+* Directory listings rendered by `listDirectoryContents` and
`getFromBrowseableDirectory` escape HTML in file names.
+Added in Pekko HTTP 1.4.2
([PR1191](https://github.com/apache/pekko-http/pull/1191))
+* Server-Sent Events fields whose values contain Unicode line separators, such
as U+2028, are parsed instead of being
+ignored. Added in Pekko HTTP 1.4.1
([PR1186](https://github.com/apache/pekko-http/pull/1186))
+
+## Configuration Changes in Pekko HTTP 2.x
+
+The `reference.conf` defaults have changed in a number of places. If you
override any of the settings
+below in your `application.conf`, or rely on their Pekko HTTP 1.x defaults,
review this list.
+
+Some of the settings listed below were added in recent Pekko HTTP 1.x
releases. They are included here for users
+upgrading from older 1.x versions, with a note of the release that introduced
them.
+
+### Changed default values
+
+* `pekko.http.server.enable-http2` changed from `off` to `on`. The setting was
added in Pekko HTTP 1.3.0
+to replace `pekko.http.server.preview.enable-http2`
([PR818](https://github.com/apache/pekko-http/pull/818)).
+Servers bound with `Http().newServerAt(...).bind(...)` now accept HTTP/2
connections (via ALPN for HTTPS, or
+prior knowledge and the `h2c` upgrade for plain HTTP). `bindFlow` and
`connectionSource()` do not support HTTP/2.
+Set it to `off`, and leave `pekko.http.server.preview.enable-http2` unset or
`off`, to restore the Pekko HTTP 1.x
+behavior. See @ref:[Server-Side HTTP/2](../server-side/http2.md).
([PR928](https://github.com/apache/pekko-http/pull/928))
+* `pekko.http.server.preview.enable-http2` changed to `null` (it was `off` up
to Pekko HTTP 1.2.x and
+`${pekko.http.server.enable-http2}` in 1.3.x and 1.4.x). The setting is still
supported for compatibility:
+HTTP/2 is enabled if either setting is `on`.
([PR928](https://github.com/apache/pekko-http/pull/928))
+* `pekko.http.server.http2.frame-type-throttle.frame-types` changed from `[]`
to `["reset"]`, so the rate of
+incoming `RST_STREAM` frames on a server connection is limited by default to
mitigate HTTP/2 Rapid Reset attacks
+(CVE-2023-44487). With the default `cost`, `burst` and `interval` settings, a
client that sends more than about
+100 `RST_STREAM` frames per second has its connection failed. Clients that
legitimately cancel many streams, such
+as some gRPC clients, may need a higher limit. Set it to `[]` to disable
throttling. ([PR1193](https://github.com/apache/pekko-http/pull/1193))
+
+### Removed configuration
+
+* `pekko.http.server.remote-address-header` was removed (deprecated since Akka
HTTP 10.2.0); use
+`pekko.http.server.remote-address-attribute` instead.
([PR757](https://github.com/apache/pekko-http/pull/757))
+
+### New configuration
+
+The full `reference.conf` for each module, with descriptions of every setting,
is listed in the
+@ref:[configuration reference](../configuration.md).
+
+pekko-http-core server settings:
+
+* `pekko.http.server.http2.max-header-list-size` (default `64 KiB`) bounds the
decompressed size of an incoming
+HTTP/2 header block, and the accumulated HEADERS and CONTINUATION fragments of
a header block; a larger header block
+is rejected with a `GOAWAY(ENHANCE_YOUR_CALM)` frame. The same setting was
added for the client as
+`pekko.http.client.http2.max-header-list-size`. These settings were added in
Pekko HTTP 1.4.1.
+([PR1216](https://github.com/apache/pekko-http/pull/1216))
+* `pekko.http.server.http2.max-frame-size` (default `512kB`) bounds the
largest incoming HTTP/2 frame payload;
+a larger frame is rejected with a `FRAME_SIZE_ERROR`. The same setting was
added for the client as
+`pekko.http.client.http2.max-frame-size`.
([PR1264](https://github.com/apache/pekko-http/pull/1264))
+* `pekko.http.server.http2.max-connection-age`,
`pekko.http.server.http2.max-connection-age-grace` and
+`pekko.http.server.http2.max-connection-age-jitter` limit the lifetime of
HTTP/2 server connections, which helps
+to rebalance long-lived connections across server instances. The feature is
disabled by default.
+See @ref:[Limiting the lifetime of
connections](../server-side/http2.md#limiting-the-lifetime-of-connections).
+([PR1316](https://github.com/apache/pekko-http/pull/1316),
[PR1323](https://github.com/apache/pekko-http/pull/1323))
+* `pekko.http.server.websocket.compression` is a new section configuring
server-side WebSocket compression
+(the RFC 7692 `permessage-deflate` extension). It is `enabled` by default and
used only when the client requests it
+during the handshake. Most browsers request it, so WebSocket connections from
browsers are compressed by default
+after upgrading; set `pekko.http.server.websocket.compression.enabled = false`
to turn it off. `max-allocation` (default `256k`) bounds the size of a
decompressed message.
+See @ref:[WebSocket
compression](../server-side/websocket-support.md#websocket-compression).
+([PR1114](https://github.com/apache/pekko-http/pull/1114),
[PR1173](https://github.com/apache/pekko-http/pull/1173))
+
+pekko-http-core client settings:
+
+* `pekko.http.client.http2.persistent-connection-max-age` and
+`pekko.http.client.http2.persistent-connection-max-age-jitter` limit the
lifetime of connections created by
+`managedPersistentHttp2` and `managedPersistentHttp2WithPriorKnowledge`. The
feature is disabled by default.
+See @ref:[Limiting managed persistent connection
lifetime](../client-side/http2.md#limiting-managed-persistent-connection-lifetime).
+([PR1320](https://github.com/apache/pekko-http/pull/1320))
+
+pekko-http-core parsing settings:
+
+* `pekko.http.parsing.max-chunk-count` (default `100000`) bounds the number of
chunks in a chunked entity;
+a larger entity fails the entity stream.
+([PR1195](https://github.com/apache/pekko-http/pull/1195))
+* `pekko.http.parsing.max-part-count` (default `10000`) bounds the number of
body parts in a multipart entity.
+Applications that receive large multipart uploads may need to raise these
limits.
+([PR1266](https://github.com/apache/pekko-http/pull/1266))
+
+pekko-http settings:
+
+* `pekko.http.sse.oversized-line-handling` and
`pekko.http.sse.oversized-event-handling` (default `"fail-stream"`)
+control how Server-Sent Events lines and events that exceed `max-line-size`
and `max-event-size` are handled.
+The other options are `"log-and-skip"`, `"truncate"` and `"dead-letter"`.
These settings were added in
+Pekko HTTP 1.3.0. See @ref:[Oversized Message
Handling](../common/sse-support.md#oversized-message-handling).
+([PR744](https://github.com/apache/pekko-http/pull/744))
+* `pekko.http.routing.use-jar-file-cache` (default `on`) controls whether
`FileAndResourceDirectives` use the JDK's
+jar file cache when serving resources from jar files. Turn it off if those jar
files have to be replaceable while
+the server is running.
([PR1217](https://github.com/apache/pekko-http/pull/1217))
+
+pekko-http-testkit settings:
+
+* `pekko.http.testkit.routes.timeout` (default `1 s`) sets the default
`RouteTestTimeout` used by the
+Scala testkit. See @ref:[Increase
Timeout](../routing-dsl/testkit.md#increase-timeout).
+([PR1016](https://github.com/apache/pekko-http/pull/1016))
+
+pekko-http-jackson3 settings:
+
+* The new `pekko-http-jackson3` module (based on Jackson 3) is configured
under `pekko.http.marshallers.jackson3`,
+mirroring the `pekko.http.marshallers.jackson` settings.
([PR837](https://github.com/apache/pekko-http/pull/837))
diff --git a/docs/src/main/paradox/routing-dsl/testkit.md
b/docs/src/main/paradox/routing-dsl/testkit.md
index 916d4a85d..eb7bf92ae 100644
--- a/docs/src/main/paradox/routing-dsl/testkit.md
+++ b/docs/src/main/paradox/routing-dsl/testkit.md
@@ -212,8 +212,8 @@ for further information.
## Increase Timeout
-The default timeout when testing your routes using the testkit is @scala[1
second]@java[3 seconds] second. Sometimes, though, this might not be enough.
-In order to extend this default timeout, to say 5 seconds, just add the
following implicit in scope:
+The default timeout when testing your routes using the testkit is @scala[1
second]@java[3 seconds]. Sometimes, though, this might not be enough.
+@scala[The default can be changed with the `pekko.http.testkit.routes.timeout`
setting. ]In order to extend the timeout, to say 5 seconds, just add the
following implicit in scope:
Scala
: @@snip
[TestKitFragmentSpec.scala](/docs/src/test/scala/docs/http/scaladsl/server/TestKitFragmentSpec.scala)
{ #timeout-setting }
@@ -254,4 +254,4 @@ a server and bind to a port so use it only when necessary.
## Examples
A great pool of examples are the tests for all the predefined directives in
Apache Pekko HTTP.
-They can be found
@scala[@github[here](/http-tests/src/test/scala/akka/http/scaladsl/server/directives/)]@java[@github[here](/http-tests/src/test/java/akka/http/javadsl/server/directives/)].
+They can be found
@scala[@github[here](/http-tests/src/test/scala/org/apache/pekko/http/scaladsl/server/directives/)]@java[@github[here](/http-tests/src/test/java/org/apache/pekko/http/javadsl/server/directives/)].
diff --git a/http-core/src/main/resources/reference.conf
b/http-core/src/main/resources/reference.conf
index 2af4320f5..d48bc6c9b 100644
--- a/http-core/src/main/resources/reference.conf
+++ b/http-core/src/main/resources/reference.conf
@@ -863,6 +863,10 @@ pekko.http {
max-header-count = 64
max-chunk-ext-length = 256
max-chunk-size = 1m
+
+ # The maximum number of chunks a chunked entity may consist of. A chunked
entity with more chunks fails the
+ # entity stream. Like max-part-count below, this bounds the per-chunk
overhead of an entity made of many small
+ # chunks, which max-content-length alone does not.
max-chunk-count = 100000
# The maximum number of body parts a multipart entity may consist of. Each
part costs a set of parsed headers and
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
