Dear hakkers,
We are happy to announce the 10.2.0 release of Akka HTTP.
Akka HTTP 10.2 is a modernization release to improve the integration with the latest Akka versions, streamline APIs, and improve performance.
Since the release of the former minor version of Akka HTTP 10.1.0, 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
Materializerin 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.
Existing Java code for binding a server like this:
// 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:
// 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);
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.
The migration to the new ServerBuilder API can be automated using scalafix. 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.
New 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-limitwas changed to1. 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 you could have a method with a single argument to 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 = 500or 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 HttpsConnectionContext 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.
- Various improvements to HTTP/2 support, driven by Akka gRPC.
- Remove legacy host connection pool including settings and tests #3188
Migration notes and full release notes
See the Migration Guide and the Release Notes for more details about this release.
Credits
For this release we had the help of 21 contributors – thank you all very much!
Changes since 10.1.11:
commits added removed
147 6233 4586 Johannes Rudolph
80 4497 2308 Arnout Engelen
33 2207 1280 Enno
8 938 915 Ignasi Marimon-Clos
4 67 7 Johan Andrén
2 273 21 pfcoperez
2 76 40 Brice Jaglin
2 100 12 changvvb
1 342 29 Marcos Pereira
1 143 75 Jonas Fonseca
1 64 1 Eduard Dubrovskiy
1 46 9 Collin Burger
1 29 2 Rodrigo Fernandes
1 11 3 Viktor Klang
1 5 1 Yingyu Cheng
1 3 3 Robert Stoll
1 2 2 Rahil Bohra
1 1 1 Porter Darby
1 1 1 belenot
1 1 1 Age Mooij
1 0 0 Victor Hugo Borja
The Akka core team is employed by Lightbend. If you’re looking to take your Akka systems to the next level, let’s set up a time to discuss our enterprise-grade expert support, self-paced education courses, and technology enhancements that help you manage, monitor and secure your Akka system from development to production.
Happy hakking!
– The Akka Team