10.2.x Release Notes

10.2.4

This release fixes CVE-2021-23339, a vulnerability regarding interpretation of Transfer-Encoding headers. See Incorrect Handling Of Transfer-Encoding Header.

The vulnerability cannot be exploited using just Akka HTTP itself. Instead, Akka HTTP must be use as a proxy and the downstream server must be vulnerable itself, so that the proxy and the downstream server disagree on how to interpret a malformed request containing both Transfer-Encoding and Content-Length headers potentially leading to a “Request Smuggling” vulnerability. If you are using Akka HTTP as a reverse proxy, make sure to upgrade to the latest version.

Starting from this version, only a single Transfer-Encoding: chunked header is allowed. HTTP/1.1 specifies other encodings, however, those are not supported or implemented in Akka HTTP. Formerly, Akka HTTP would just pass on unsupported Transfer-Encoding headers to the user which lead to the above security issue. Since Akka HTTP implements the “Transfer” part of the protocol, it seems reasonable to lock down allowed values for Transfer-Encoding to prevent security issues like this. Please let us know if this leads to compatibility problems with your software.

The release contains one other notable change:

New option for handling conflicting Content-Type headers #3727

10.2.3

This release includes a working preview HTTP/2 client. Please consider using this preview to provide early feedback in case you find issues in your use-case. The HTTP/2 client will soon be included as an opt-in backend for the Akka gRPC client.

Native HTTP/2 support in Akka gRPC reduces the number of upstream dependencies and enables more deeply integrated tooling for Akka gRPC in the future.

For now, a connection-level and a “persistent connection” API is provided. The entry points are very similar to the existing flow-based HTTP/1 client APIs (responses are provided out-of-order, though, see the docs). The persistent connection API provides functionality similar to the newHostConnectionPool API.

Higher-level APIs for HTTP/2 like the superPool or singleRequest APIs (or a potential automatic integration into the existing APIs) are still discussed.

Please see the documentation for more information and usage examples.

Other notable changes:

akka-http-core

Better support for filename in Content-Disposition #3705
Warn if trying to bind flow/source with HTTP2 (which is not supported) #3678

akka-http-testkit

Fetch chunks in the testkit without waiting for the whole response to finish #3724

docs

Show examples of using the Akka HTTP BOM (bill of materials) in dependency blocks

10.2.2

This release includes a number of improvements to the HTTP/2 server support, while we continue to prepare for providing HTTP/2 support at the client as well.

As of this version, it is no longer strictly necessary to depend no a separate ‘akka-http2-support’ artifact to get HTTP/2 support in Akka HTTP. We will continue to publish an empty artifact with that name to make it easy to upgrade, however.

Changes since 10.2.1

akka-http-core

Allow illegal header keys to be ignored #3133
HttpCookie.copy was calling itself recursively #3670
Don’t dispatch onResponseEntity… events for entities that don’t have to be subscribed #3574
Add modeled ‘TE’ header #3616, #3618
Add parens to deprecation messages for bind-methods #3547
Use official version of SocketUtil in tests #3558
Link to https rather than http #3663
Avoid temporaryServerHostnameAndPort #3691

akka-http

Optimize header directives by avoiding HttpHeader.unapply #3591

akka-http-marshallers

Update jackson-dataformat-xml from 2.10.5 to 2.10.5.1 #3695

akka-http-testkit

Fall through on AssertionErrors in testkit #3512
Fail noisily if trying to use ~> together with transparent-head-requests #3569

docs

Add example for Get request with query parameters #3624
Add akka-actor-typed dependency to introduction.md #3565
Typo fix: “the onne” –> “the one” #3521
Some docs gardening #3544
Link project info to snapshots #3681
Release notes for 10.1.13 #3635
Add section about how to configure snapshots #3642
Add example for Get request with query parameters #3624
Update formFields example #3650
Verify signatures from the markdown actually exist #3654
Add link from formFields to parameters directive docs #3655
Use explicit paths to snippets #3653
Fix the Bid class. #3661

akka-http2-support

Extract common rendering + add userAgent on requests #3657
Continue accepting window updates even when done sending #3619
Support custom HTTP methods for HTTP/2 #3622
More robust handling of IncomingStreamBuffer.onPull #3621
Simplify Http2Substream hierarchy trading a bit of type-safety for simplicity #3605
More useful event info for stream state changes #3643
Add some more basic HTTP/2 client tests #3644
Configurable ping support through demuxer #3617
Close the substreams earlier from the demuxer #3647
HTTP/2 client test coverage (and support for) TLS session info #3668
Handle RST while sending data + more tests #3671
Fix lost ‘pull’ when closing while waiting for window #3672
Send and enforce max concurrent streams setting #3529
Unify incoming and outgoing state machine #3552
Disable Push (send SETTING) #3555
Fix Scala 2.12 compilation error #3582
Remove explicit parallelism parameter in HTTP/2 #3545
Respect remote max concurrent streams (reprise) #3581
Also go through state machine for resetStream #3584
Fix leakage of incoming substreams in edge cases #3233
Run handler code in its own task on the server #3593
Check HTTP2 headers for correctness #3603
HTTP/2 connection level API #3511
Accepting trailing headers in the HTTP/2 client #3602
Protocol-level client specs #3532
Move some public API bits to its final places and mark them as @ApiMayChange#3526
Use LogHelper in demux classes #3506
Remove some minor repetition in HTTP/2 rendering #3229
Test server responses to invalid ping frames #3523
Use scheme portion of target URI in :scheme pseudo-header #3535
Add test for receiving WINDOW_UPDATE in HalfClosedRemoteWaitingForOutgoingStream state #3554
Make ‘network’ and ‘user’ sides more explicit #3638
streamId attribute is not needed / supported on client side #3652

build

Akka HTTP BOM #3665
Add 10.2.1 to MiMa #3499
Increase paradox parsing timeout #3508
Also aggregate akka-http-bench-jmh, to fail if benchs fail to compile #3561
Exclude akka-http-bench-jmh from whitesource #3562
Disable whitesource for submodules which are not to be published #3564
Remove sbt-javaagent #3598
Include stack traces in scalatest failures #3612
Add 10.1.13 to mima #3641

And various updates:

Update akka to 2.5.32 #3558
Update caffeine from 2.8.5 to 2.8.7 #3515
Update junit from 4.12 to 4.13.1 #3517
Update paradox-theme-akka, … from 0.35 to 0.36#3697
Update sbt-bintray from 0.5.6 to 0.6.1 #3572, #3596
Update sbt-mima-plugin from 0.8.0 to 0.8.1 #3548
Update sbt-scalafix, scalafix-core, … from 0.9.21 to 0.9.23 #3614
Update specs2-core from 4.10.3 to 4.10.5 #3518, #3550
Update spray-json from 1.3.5 to 1.3.6 #3629

10.2.1

This release includes:

Improved source-compatibility with Akka HTTP 10.1.x #3489
Re-introduction of the lingerTimeout option #3456

Changes since 10.2.0

akka-http-core

Reenable lingerTimeout #3456
Make entities of HEAD requests discard #3440
Fix HTTPS proxy CONNECT request #3434
Expose the SslSession via an attribute #3472
Add debug logging when Websocket impl closes connections after timeout #3431
Spelling in reference.conf #3425
Remove unused import in Handshake class #3464
Tests: use copy of SocketUtil that does not use 127.x.y.255 addresses #3460

akka-http

Provide implicit conversion from route and materializer to flow #3489
Fail storeUploadedFile(s) directive when IO operation fails #3437
Fix Route.handlerFlow deprecation message #3465
Fix a couple of warnings #3482
Clean up some imports #3457

docs

Docs for getting data from a strict entity in a client #3446
Fix links to httpsServer / httpsClient #3453
Fix typo in deprecation message #3424
Update Scala style guide example to match the Java one (remove duplicated “customer” path) #3448
Document how to disable hostname verification without ssl-config #3483
Fix introduction markup #3476
Update head documentation about default behavior #3480
Document requiring client authentication #3492
Update websocket docs to describe attribute #3488

akka-http2-support

Ignore unexpected DATA frames in state closed #3462
Improve HTTP2 debug logging #3467

build

Set up mima for 10.2 #3408
Simplify http-core test against akka master scenario #3402
Increase paradox parsing timeout #3430
Update to Scala 2.12.12 #3420
Update github-api from 1.115 to 1.116 #3443
Update sbt-jmh from 0.3.7 to 0.4.0 #3471
Update sbt-mima-plugin from 0.7.0 to 0.8.0 #3475
Update sbt-scalafix, scalafix-core, … from 0.9.20 to 0.9.21 #3479
Update scalatest from 3.1.3 to 3.1.4 #3454
Update silencer-lib, silencer-plugin from 1.7.0 to 1.7.1 #3397
Update specs2-core from 4.10.2 to 4.10.3 #3445

10.2.0

Akka Http 10.2 is a modernization release to improve the integration with the latest Akka versions, streamline APIs, and improve performance.

Since the original release of 10.1, the Akka project has introduced a few important features:

Akka 2.6 offers typed actors and ActorSystems
Akka Stream APIs were improved to work without requiring a Materializer in most cases
Akka gRPC 1.0 has been released which is built on top of Akka HTTP

Akka Http 10.2.0 supports these changes in the following ways:

Http APIs now work the same whether a classic or a typed ActorSystem is provided
A new concise API for binding servers has been introduced
A new set of directives handle, and handleSync provide more options to seamlessly mix Akka gRPC generated service handlers with Akka Http routes. HTTP/2 support has been improved based on Akka gRPC usage.
Akka HTTP now supports Akka Coordinated Shutdown for server bindings.

Seamless integration with Akka 2.6 and new server API entrypoints

Making changes to support Akka 2.6 better, we realized that the existing server API is sometimes awkward to use and to evolve. Therefore, we took the opportunity to come up with a new ServerBuilder API that provides a way to bind servers more concisely, especially from Java.

Code like:

Scala

source// only worked with classic actor system
implicit val system = akka.actor.ActorSystem("TheSystem")
implicit val mat: Materializer = ActorMaterializer()
val route: Route =
  get {
    complete("Hello world")
  }
Http().bindAndHandle(route, "localhost", 8080)

Java

source// only worked with classic actor system
akka.actor.ActorSystem system = akka.actor.ActorSystem.create("TheSystem");
Materializer mat = ActorMaterializer.create(system);
Route route = get(() -> complete("Hello World!"));
Http.get(system).bindAndHandle(route.flow(system), ConnectHttp.toHost("localhost", 8080), mat);

can now be written as:

Scala

source// works with both classic and typed ActorSystem
implicit val system = akka.actor.typed.ActorSystem(Behaviors.empty, "TheSystem")
// or
// implicit val system = akka.actor.ActorSystem("TheSystem")

// materializer not needed any more

val route: Route =
  get {
    complete("Hello world")
  }
Http().newServerAt("localhost", 8080).bind(route)

Java

source// works with classic or typed actor system
akka.actor.typed.ActorSystem system = akka.actor.typed.ActorSystem.create(Behaviors.empty(), "TheSystem");
// or
// akka.actor.ActorSystem system = akka.actor.ActorSystem.create("TheSystem");

// materializer not needed any more

Route route = get(() -> complete("Hello World!"));
Http.get(system).newServerAt("localhost", 8080).bind(route);

Notably, server written with the routing DSL will now be automatically converted to an asynchronous handler (using the new pendant of bindAndHandleAsync) instead of being provided as a Flow (using bindAndHandle before). This has the benefit that it fits the style of the routing DSL better which really represents an asynchronous handler function and, more importantly, will enable routes to work automatically with HTTP/2 (when enabled).

The old APIs have been deprecated but will be kept for binary and source compatibility at least until 10.3 but maybe even longer (because they have been such a central part).

We made an effort to keep supporting Akka 2.5.x (>= 2.5.31) for this release to ease the migration burden. It required backporting some features from Akka 2.6 so that seamless APIs would work the same with Akka 2.6 and Akka 2.5. The 10.2.x release line will be the last supporting Akka 2.5.

To do the migration you can run the following task in sbt if you have scalafix enabled in your project:

scalafixAll dependency:[email protected]:akka-http-scalafix-rules:10.2.0

See the migration notes for more information about how to setup and use scalafix to do the migration.

Routing DSL guidelines

Akka HTTP’s routing DSL comes with great power once you have mastered it. However, the flexibility it provides can be hard to tame for new users or when projects grow. We acknowledge these difficulties and want to conquer them with giving more guidelines to get started with building routes more easily. For that reason, we created two new documentation pages to give advice about how routes can be organized for scale:

The new styleguide gives general recommendations about how to structure route source code.
A comparison with Play routes gives a side-by-side overview of how routing features of Play and Akka HTTP compare to each other.

Attributes for HttpRequest and HttpResponse

In many cases metadata needs to be attached to a HTTP message. Previously, this was accomplished by introducing synthetic headers to add to requests and responses. However, this was more of a workaround that could lead to confusion about which headers should be rendered and where they originated. Akka Http 10.2 introduces attributes to HTTP messages. These allow attaching and querying typed metadata values to messages.

See Attributes for more information.

Default configuration improvements

Seldom used features have now been turned off by default:

Transparent HEAD support was disabled, see #2088 and the migration notes for information about the rationale.
Server-side HTTP pipelining was disabled by default. Common HTTP clients do not support it by default or have it disabled, so to reduce complexity in the common code paths the default akka.http.server.pipelining-limit was changed to 1. See the migration notes for more information.

Better support for upcoming Scala versions

Scala 2.13 deprecated “adapted arguments” which were heavily used in the routing DSL with the magnet pattern. It allowed that a single method with a single argument could take any number of arguments in a typesafe fashion by relying on the Scala compiler to convert those arguments to a tuple of arguments. Since a while we generally try to reduce our usage of implicits and the magnet pattern to avoid complex compile error messages, long compile times, and complexity. With Akka Http 10.2 we made another effort to reduce our dependency on that language feature by providing a set of code-generated overloads for the methods in question to pave our way for upcoming Scala versions.

See the migration guide for more information.

Client: configurable setting overrides per target host

It is now possible to set overrides for client settings per target host via configuration. For example, if you use Akka HTTP client to access different services, it is now possible to tweak pool and connection parameters like the maximum number of concurrent connections (max-connections) on a per-target-host-basis. Thanks to David Knapp / @Falmarri for providing an initial implementation of that feature a long time ago.

Client: custom client DNS resolution transport

By default, host name resolution is done in the IO layer when a connection attempt is made. In some cases, it can make sense to be able to customize the resolution, for example if there are multiple ip addresses returned for a DNS query, this could be used to implement custom DNS load balancing schemes. For that purpose, a new ClientTransport.withCustomResolver was introduced that allows providing custom resolution for each connection attempt.

See the section about custom client DNS resolution schemes for more information.

Performance improvements

Better performance for big client pools: Big client pools with more than 500 connections (max-connections = 500 or more) suffered from a bad choice of datastructure with O(n²) access times, so bigger pools spent too much time just sifting through the internal data structures instead of doing useful work. This has been fixed and a nightly benchmark has been set up to track performance going forward.
Cheaper logging in client pools helps pools of all sizes by avoiding logging when DEBUG logging is disabled.
discardEntityBytes for strict entities is now a no-op while before streams were materialized.

Streamlined HTTPS configuration

Akka HTTP no longer uses the HTTPS configuration configured with ssl-config by default. Instead, it will use the JRE defaults for client connections. For server connections you should create a HttpsConnectionContextHttpsConnectionContext with the relevant configuration.

See Configuring HTTPS connections for more information.

Other changes

Various bug fixes, such as around percent-encoding URI queries and parsing headers with unicode characters.
RouteTest can now run integration tests with ~!> through full client/server infrastructure #3014
Various improvements to HTTP/2 support, driven by Akka gRPC.
Remove legacy host connection pool including settings and tests #3188

Migration notes

Support for Scala 2.11 has been dropped in this release. See the Migration guide for more information about other changes which might need migration.

Changes since 10.1.11

akka-http-core

Fix cancellation race conditions on the client-side #2965
Silence outgoing request stream error #2905
Add SameSite attribute to Cookies #2928
Only catch NonFatal Exceptions #2853
Add coordinated shutdown support #3142
Percent-encode illegal chars when creating URI query #3003
Add the remote address in parse errors when possible #2899
Remove UseHttp2 #2896
Hide body and headers by default in HttpRequest#toString and HttpResponse#toString #2560
Fix headers javadsl scaladoc #2932
Allow client setting overrides for target hosts in config #2574
Fix EOL detection for body part parsing #2581
Update javadsl bindAndHandle to take a Java function and System #3223
Identify Content-Type charset parameter even if not lower case #2926
Prevent initialization NPE which might fail all retries quickly #2958
Add exclusion for Extension issues when building against Akka 2.6 #2945
Nest correctly in NewHostConnectionPool #2964
Support for request/response message attributes #2938
Don’t fail slot after previous connection failed in special condition #3021
Simplify route2HandlerFlow #2893
Better support for the new Actors API #3036
Parse empty query ? to Query.empty #3042
Make sure to cancel response entity on failure #3046
Add akka.http.server.remote-address-attribute #2924
Make transparent-head-requests opt-in #3063
Continue more gracefully when encountering multiple Host headers in a response #3158
Allow customizing parsing errors #3049
Don’t extend from Char => Boolean for CharPredicate #3107
Add server-side streamCancellationDelay to mitigate cancellation race conditions #2116
Improve error message about unconsumed entity #3109
Header rendering with less indirection #3106
Remove deprecated methods taking implicit materializers #3119
Simplify superPool and clientFlow #3156
Deprecate Remote-Address header #3174
Move max-content-length definition from top to server/client #3098
Add test for failure propagation into websocket flows #3276
Deprecate UpgradeToWebSocket #3278, #3296
Disable server-side HTTP pipelining by default#
Make HttpEntity.Strict.discardBytes a no-op #3329
Make sure to reset all UriParser fields before reusing#
Track idle slots explicitly to avoid O(n^2) work for big pools#
Keep request/response copy method public #3347
Introduce javadsl discardEntityBytes that takes a ClassicActorSystemProvider#
Provide toStrict overloads with ClassicActorSystemProvider parameter#
Introduce custom hostname resolution client transport #3202
Avoid expensive logging in NewHostConnectionPool #3356
Introduce Http().newServerAt server builder API#
Make HttpRequest/HttpResponse.hashCode depend on attributes #3351
Allow customization of materializer with new ServerBuider API#3414

akka-http

Names as alternative to symbolic directive combiners #3085
Names for symbolic enhancements #3082
Allow names to match paths #3089
Remove deprecated FormFieldDirectives methods #3120
Remove magnets usage from formField directives #3289
Provide Route.toFunction as alternative to Route.asyncHandler #3115
New handle directive to create Route from function #3239
Allow ‘bindAndHandleAsync’ to take a ‘Route’ #3237
Make X-Real-IP take precedence over Remote-Address #3173
Allow passing a companion object to headerValueByType #3279
Replace magnetic parameter overloads by boilerplate-generated overloads #2971
Deprecate directives taking Symbol as argument #3291
Remove uploadedFile (deprecated in 10.0.11) #3118
Deprecate internal parts of coding infrastructure #3262
Deprecate HttpApp #3162
Allow ‘complete’ directive with status without adapted arguments #3307
Fix remaining internal adapted arguments warnings #3337
Create Unmarshaller.unmarshal overloads taking in ClassActorSystemProvider#
Add directives for extracting attributes #3355
Document and dogfood using the attribute for websockets #3358
Add handlePF directive #3367

akka-http-marshallers

Only show unmarshalling error details when ‘verbose-error-messages’ is on #3265
Jackson: Better JSON validation error when unmarshalling #2901

akka-http-testkit

Allow RouteTest to run integration tests via ~!> operator #3014
Update to Scalatest 3.1.0 #2851
Handle test exceptions separately from regular exceptions #2949
Simplify implicits for RouteTest #3060
Fix more Scala 2.13 warnings #3130

docs

Use typed ActorSystem in examples #3242
Routing DSL style guide #3099
Routing DSL compared with Play routes #3079
Small typo in docs/src/main/paradox/common/marshalling.md #2864
Add warning on usage on extractClientIP #2922
Show RequestBuilding in client examples #2968
Don’t claim that SNI is a security feature #3257
Update documentation and examples to Akka 2.6 #2996
Link to major/minor Akka docs #3048
Actor interop Java example #3078
Make Case class extraction example work with 2.13 #3092
Fix more Scala 2.13 warnings #3130
Update extractClientIP.md wrt remote-address-attribute #3083
Make HttpServerWithActorsSample more 2.6-style #3077
Show symbolic Akka version for dependencies #3121
Support native ALPN in JDK >=8u251 #3117
Use automatic root dir resolution for snip and signature #3339
Page about client-side configuration + per-host-overrides #3338
Document and dogfood using the attribute for websockets #3358
Add ‘troubleshooting’ page, populate with ‘PRI’ error message #3384

akka-http2-support

Initial HTTP/2 client implementation bits #3166
Potential fix for idle timeouts in HTTP/2 #2776
Frame parsing: improve handling of unknown values #3101
Support native ALPN in JDK >=8u251 #3117
Fix HeaderCompression updating table size without giving notice to peer #2891
Reduce HTTP/2 buffer debug logging #3025
Accept RST on an already-half-closed HTTP/2 stream #2976
Gracefully discard unsupported h2 SETTINGS #3053
Make the HTTP/2 Stream ID an attribute #3224

akka-http-caching

Harden ExpiringLfuCacheSpec #2960

build

Fix project-info links to API docs #2857
Drop Scala 2.11 #2589
Build with Scala 2.13 by default #3126
Better diagnostics when validatePullRequest fails weirdly #2904
Test against published snapshots instead of source deps #3055
Enable some fatal warnings for docs #3114
Add sbt-reproducible-builds #3165
Publish docs from travis #3328
Scalafix rules to rewrite to new ServerBuilder API automatically #3407