Akka HTTP 10.2.0 Released

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 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.

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:MigrateToServerBuilder@com.typesafe.akka: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-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 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 = 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 HttpsConnectionContext with
the relevant configuration.

See Configuring HTTPS connections for more information.

Other changes

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

1 Like

It’s mentioned here that HTTPS configuration is no longer managed by ssl-config (and the migration guide doesn’t mention a means of restoring that behavior.)

The 10.2 Client Side HTTPS Support section of the manual however still talks as though ssl-config is exclusively in use, and provides no examples or links to information on how to override trust stores and other activities that ssl-config had made trivial, without ssl-config.

Yes, sorry about that. Not updating the documentation was an oversight we hope to improve on soon. For now ssl-config still works (though deprecated), the replacement for now is to create and configure an SSLContext manually (which is verbose but the same as with any other software using TLS on Java).