Migration from Apache Pekko HTTP 1.x to 2.x
Apache Pekko HTTP 2.x requires Apache Pekko 2.x. See the Pekko 1.x to 2.x migration guide 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
Durationnow return ajava.time.Duration. (PR788) - The new
pekko-http-jackson3module supports Jackson 3. See the configuration change below. ClientTransport,RequestResponseAssociation,SimpleRequestResponseAttribute, the Java DSLanyOf/allOfdirective combinators and thestoreUploadedFile,storeUploadedFilesandfileUploadAlldirectives are no longer marked@ApiMayChangeand are now stable APIs. (PR1364)HttpMessage.attributeand theResponseEntity.fromJavaimplicit conversion no longer take an implicitJavaMappingparameter, so they can be used from Scala 3.10. This is source compatible but changes their binary signatures. (PR1340)- The Java DSL
ConnectionPoolSettings.withHostOverridestakes ajava.util.List<Pair<String, ConnectionPoolSettings>>(usingorg.apache.pekko.japi.Pair) instead of a list ofscala.Tuple2. Java code that builds the overrides withTuple2has to be changed to usePair.create(pattern, settings). (PR1377) - Many Java DSL methods accept wildcard generic types, such as
Iterable<? extends HttpHeader>instead ofIterable<HttpHeader>, so collections of subtypes can be passed. The erased signatures are unchanged. (PR1379, PR1380, PR1381, PR1382, PR1384) - Java DSL alternatives to Scala types have been added:
java.time.Durationaccessors forServerSettingstimeouts (PR1373),onCompleteoverloads that take aCompletionStage.handlestyle callback instead of ascala.util.Try(PR1375) and connection pool flows that emit anHttpResponseResultinstead of ascala.util.Try(PR1376).
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-Lengthnow depends on the request method as well as the status code, following RFC 9110: a2xxresponse toCONNECTno longer renders it, and a205 Reset Contentresponse now does.HttpMethod.customhas a new overload with acontentLengthAllowedparameter; the old overload is deprecated. Added in Pekko HTTP 1.4.0 (PR968). AHEADresponse rendersContent-Lengthonly when its entity declares a length greater than zero. Added in Pekko HTTP 1.4.1 (PR1244) - A
Content-Lengthvalue with whitespace between its digits, or without any digit, is rejected; it was previously read as the concatenated digits, or as0. Added in Pekko HTTP 1.4.1 (PR1243) - Repeated
Connectionheaders count towardspekko.http.parsing.max-header-count. Added in Pekko HTTP 1.4.1 (PR1268) - A message whose
Transfer-Encodingvalue cannot be parsed is rejected. Added in Pekko HTTP 1.4.2 (PR1267) - Whitespace between or before chunk-size digits is rejected; trailing whitespace is still tolerated. Added in Pekko HTTP 1.4.2 (PR1257)
- A request line where a CR or LF ends the request target is rejected with
505 HTTP Version Not Supported. (PR1341) - 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) and NUL in headers (PR1272); chunk extensions containing NUL are dropped from Pekko HTTP 2.0.0 (PR1344).
Linkheader 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)- Comma-separated list headers, such as
Cache-Control,Connection,AcceptorIf-None-Match, accept and ignore empty list elements (no-store,, public,, no-storeorno-store,) as RFC 9110 section 5.6.1 requires, instead of staying aRawHeader. A list that must have at least one element and contains only empty elements, such asCache-Control: ,, is still not parsed. (#1396) Whitespace before a list separator (no-store , public) is also accepted. (PR1395) - Parse error details logged with
pekko.http.parsing.error-logging-verbosity = full(the default), and thetoStringofIllegalRequestContextpassed to a customParsingErrorHandler, now escape control characters in the raw request target or header value. (PR1294)
HTTP/2
- Outgoing header fields whose name or value contains CR, LF or NUL are dropped. Added in Pekko HTTP 1.4.1 (PR1271)
- 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 with400 Bad Requestand the connection is kept. (PR1297) - A request with an invalid
:schemepseudo-header, or with a regular field name containing:, is rejected with a400 Bad Requestfor that stream; an invalid:schemeno longer fails the whole connection. (PR1341) - 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 Requestfor 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) -
The HTTP/2 client sends the connection’s scheme and authority in the
:schemeand:authoritypseudo-headers for a request with a relative URI, instead of leaving them empty. A non-emptyHostheader supplies the authority first. A Pekko HTTP server now sees the full request URI for such requests. (PR1342) - When an HTTP/2 managed persistent connection gives up after its last connection attempt fails, the request that triggered the attempts is answered with a
503 Service Unavailableresponse, which carries the request’s attributes, before the stream fails. (PR1368)
Server
- During graceful termination, a response for a request that is already being handled is delivered (with
Connection: close) instead of being lost when the request side completes or the network side pulls late. (PR1398, PR1400)
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)
Routing DSL
- The CORS directives accept an actual request only when every origin in its
Originheader is allowed, instead of when any one of them is. Added in Pekko HTTP 1.4.2 (PR1262) FileAndResourceDirectivescompare 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-privateis no longer served from/var/www. Added in Pekko HTTP 1.4.1 (PR1269)getFromResourcerejects a resource name that contains a..segment, a backslash or a NUL character, instead of passing it to the class loader. Such names only ever resolved against directory-backed class loaders, not against resources inside jar files. Setpekko.http.routing.reject-unsafe-resource-names = offto restore the previous behavior. (PR1406)- Directory listings rendered by
listDirectoryContentsandgetFromBrowseableDirectoryescape HTML in file names. Added in Pekko HTTP 1.4.2 (PR1191) - 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)
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-http2changed fromofftoon. The setting was added in Pekko HTTP 1.3.0 to replacepekko.http.server.preview.enable-http2(PR818). Servers bound withHttp().newServerAt(...).bind(...)now accept HTTP/2 connections (via ALPN for HTTPS, or prior knowledge and theh2cupgrade for plain HTTP).bindFlowandconnectionSource()do not support HTTP/2. Set it tooff, and leavepekko.http.server.preview.enable-http2unset oroff, to restore the Pekko HTTP 1.x behavior. See Server-Side HTTP/2. (PR928)pekko.http.server.preview.enable-http2changed tonull(it wasoffup 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 ison. (PR928)pekko.http.server.http2.frame-type-throttle.frame-typeschanged from[]to["reset", "empty-data-no-end-stream"], so the rate of incomingRST_STREAMframes on a server connection is limited by default to mitigate HTTP/2 Rapid Reset attacks (CVE-2023-44487), as is the rate of incoming DATA frames that carry no payload and do not end their stream, which consume no flow-control window (Empty Frames Flood, CVE-2019-9518). All throttled frames share one budget: with the defaultcost,burstandintervalsettings, a client that sends more than about 100 of them per second has its connection closed withGOAWAY(ENHANCE_YOUR_CALM)(PR1413). Clients that legitimately cancel many streams, such as some gRPC clients, may need a higher limit. The empty DATA frame with END_STREAM that closes a request body is not charged unlessempty-datais added. Set it to[]to disable throttling. (PR1193, PR1265)
Removed configuration
pekko.http.server.remote-address-headerwas removed (deprecated since Akka HTTP 10.2.0); usepekko.http.server.remote-address-attributeinstead. (PR757)
New configuration
The full reference.conf for each module, with descriptions of every setting, is listed in the configuration reference.
pekko-http-core server settings:
pekko.http.server.http2.max-header-list-size(default64 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 aGOAWAY(ENHANCE_YOUR_CALM)frame. The same setting was added for the client aspekko.http.client.http2.max-header-list-size. These settings were added in Pekko HTTP 1.4.1. (PR1216)pekko.http.server.http2.max-frame-size(default512kB) bounds the largest incoming HTTP/2 frame payload; a larger frame is rejected with aFRAME_SIZE_ERROR. The same setting was added for the client aspekko.http.client.http2.max-frame-size. (PR1264)pekko.http.server.http2.max-connection-age,pekko.http.server.http2.max-connection-age-graceandpekko.http.server.http2.max-connection-age-jitterlimit the lifetime of HTTP/2 server connections, which helps to rebalance long-lived connections across server instances. The feature is disabled by default. See Limiting the lifetime of connections. (PR1316, PR1323)pekko.http.server.websocket.compressionis a new section configuring server-side WebSocket compression (the RFC 7692permessage-deflateextension). It isenabledby 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; setpekko.http.server.websocket.compression.enabled = falseto turn it off.max-allocation(default256k) bounds the size of a decompressed message. See WebSocket compression. (PR1114, PR1173)pekko.http.server.websocket.receive-idle-timeoutandpekko.http.server.websocket.send-idle-timeout(defaultinfinite, which disables them) fail a WebSocket connection with aWebSocketIdleTimeoutExceptionwhen no frame is received or sent within the timeout. Ping and Pong frames count as activity. The same settings were added for the client underpekko.http.client.websocket. (PR1369)
pekko-http-core client settings:
pekko.http.client.http2.persistent-connection-max-ageandpekko.http.client.http2.persistent-connection-max-age-jitterlimit the lifetime of connections created bymanagedPersistentHttp2andmanagedPersistentHttp2WithPriorKnowledge. The feature is disabled by default. See Limiting managed persistent connection lifetime. (PR1320)pekko.http.client.http2.frame-type-throttlelimits the rate of incoming frames of the configured types on an HTTP/2 client connection, likepekko.http.server.http2.frame-type-throttledoes for the server and with the same settings. By default,frame-types = ["reset", "empty-data-no-end-stream"]: a server that sends more than about 100RST_STREAMframes, or DATA frames that carry no payload and do not end their stream, per second has the connection closed withGOAWAY(ENHANCE_YOUR_CALM). A client with many requests in flight on one connection may need a higher limit. Setframe-typesto[]to disable throttling. (#1393)
pekko-http-core parsing settings:
pekko.http.parsing.max-chunk-count(default100000) bounds the number of chunks in a chunked entity; a larger entity fails the entity stream. (PR1195)pekko.http.parsing.max-part-count(default10000) bounds the number of body parts in a multipart entity. Applications that receive large multipart uploads may need to raise these limits. (PR1266)
pekko-http settings:
pekko.http.sse.oversized-line-handlingandpekko.http.sse.oversized-event-handling(default"fail-stream") control how Server-Sent Events lines and events that exceedmax-line-sizeandmax-event-sizeare handled. The other options are"log-and-skip","truncate"and"dead-letter". These settings were added in Pekko HTTP 1.3.0. See Oversized Message Handling. (PR744)pekko.http.routing.use-jar-file-cache(defaulton) controls whetherFileAndResourceDirectivesuse 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)pekko.http.routing.reject-unsafe-resource-names(defaulton) controls whethergetFromResourcerejects resource names that contain a..segment, a backslash or a NUL character. See Routing DSL.
pekko-http-testkit settings:
pekko.http.testkit.routes.timeout(default1 s) sets the defaultRouteTestTimeoutused by the Scala testkit. See Increase Timeout. (PR1016)
pekko-http-jackson3 settings:
- The new
pekko-http-jackson3module (based on Jackson 3) is configured underpekko.http.marshallers.jackson3, mirroring thepekko.http.marshallers.jacksonsettings. (PR837)