Client-Side HTTP/2 (Preview)

Create the client

There are three mechanisms for a client to establish an HTTP/2 connection. Akka HTTP supports:

• HTTP/2 over TLS
• HTTP/2 over a plain TCP connection (“h2c with prior knowledge”)

Akka HTTP doesn’t support:

• HTTP Upgrade mechanism

HTTP/2 over TLS

To create a client, use the Http() fluent API to connect and use the http2() creator:

Scala

copysourceimport akka.http.scaladsl.Http
Http().connectionTo("localhost").toPort(8443).http2()

Java

copysourceimport akka.http.javadsl.Http;

Http.get(system)
        .connectionTo("127.0.0.1")
        .toPort(8443)
        .http2();

HTTP/2 over TLS needs Application-Layer Protocol Negotiation (ALPN) to negotiate whether both client and server support HTTP/2. The JVM provides ALPN support starting from JDK 8u252. Make sure to use at least that version.

Akka HTTP does not currently support protocol negotiation to fall back to HTTP/1.1 for this API. When the server does not support HTTP/2, the stream will fail.

h2c with prior knowledge

The other option is to connect and start communicating in HTTP/2 immediately. You must know beforehand the target server supports HTTP/2 over a plain TCP connection. For this reason this approach is known as h2c with Prior Knowledge of HTTP/2 support.

To create a client, use the Http() fluent API to connect and use the http2WithPriorKnowledge() creator:

Scala

copysourceimport akka.http.scaladsl.Http
Http().connectionTo("localhost").toPort(8080).http2WithPriorKnowledge()

Java

copysourceimport akka.http.javadsl.Http;

Http.get(system)
        .connectionTo("127.0.0.1")
        .toPort(8080)
        .http2WithPriorKnowledge();

HTTP Upgrade mechanism

The Akka HTTP client doesn’t support HTTP/1 to HTTP/2 negotiation over plaintext using the Upgrade mechanism.

Request-response ordering

For HTTP/2 connections the responses are not guaranteed to arrive in the same order that the requests were emitted to the server, for example a request with a quickly available response may outrun a previous request that the server is slower to respond to. For HTTP/2 it is therefore important to have a way to correlate the response with the request it was made for. This can be achieved through a RequestResponseAssociationRequestResponseAssociation set on the request, Akka HTTP will pass such association objects on to the response.

In this sample the built-in akka.http.scaladsl.model.ResponsePromiseakka.http.javadsl.model.ResponseFuture RequestResponseAssociation is used to return a FutureCompletionStage for the response:

Scala

copysourceval dispatch = singleRequest(Http().connectionTo("doc.akka.io").http2())

dispatch(
  HttpRequest(
    uri = "https://doc.akka.io/api/akka-core/current/akka/actor/typed/scaladsl/index.html",
    headers = headers.`Accept-Encoding`(HttpEncodings.gzip) :: Nil)
).onComplete { res =>
    println(s"[1] Got index.html: $res")
    res.get.entity.dataBytes.runWith(Sink.ignore).onComplete(res => println(s"Finished reading [1] $res"))
  }

def singleRequest(connection: Flow[HttpRequest, HttpResponse, Any], bufferSize: Int = 100): HttpRequest => Future[HttpResponse] = {
  val queue =
    Source.queue(bufferSize, OverflowStrategy.dropNew)
      .via(connection)
      .to(Sink.foreach { response =>
        // complete the response promise with the response when it arrives
        val responseAssociation = response.attribute(ResponsePromise.Key).get
        responseAssociation.promise.trySuccess(response)
      })
      .run()

  req => {
    // create a promise of the response for each request and set it as an attribute on the request
    val p = Promise[HttpResponse]()
    queue.offer(req.addAttribute(ResponsePromise.Key, ResponsePromise(p)))
      // return the future response
      .flatMap(_ => p.future)
  }
}

Java

copysource  Function<HttpRequest, CompletionStage<HttpResponse>> dispatch =
      singleRequest(system, Http.get(system).connectionTo("doc.akka.io").http2());

  dispatch.apply(
      HttpRequest.create(
          "https://doc.akka.io/api/akka-core/current/akka/actor/typed/scaladsl/index.html").withHeaders(
          Arrays.asList(AcceptEncoding.create(HttpEncodings.GZIP))
      )
  ).thenAccept(res -> {
    System.out.println("[1] Got index.html: " + res);
    res.entity().getDataBytes().runWith(Sink.ignore(), mat)
        .thenAccept(consumedRes -> System.out.println("Finished reading [1] " + consumedRes));
  });

private static Function<HttpRequest, CompletionStage<HttpResponse>> singleRequest(ActorSystem system, Flow<HttpRequest, HttpResponse, ?> connection) {
  SourceQueueWithComplete<HttpRequest> queue =
      Source.<HttpRequest>queue(100, OverflowStrategy.dropNew())
          .via(connection)
          .to(Sink.foreach(res -> {
            try {
              // complete the future with the response when it arrives
              ResponseFuture responseFuture = res.getAttribute(ResponseFuture.KEY()).get();
              responseFuture.future().complete(res);
            } catch (Exception ex) {
              ex.printStackTrace();
            }
          }))
      .run(SystemMaterializer.get(system).materializer());

  return (HttpRequest req) -> {
    // create a future of the response for each request and set it as an attribute on the request
    CompletableFuture<HttpResponse> future = new CompletableFuture<>();
    ResponseFuture attribute = new ResponseFuture(future);
    return queue.offer(req.addAttribute(ResponseFuture.KEY(), attribute))
        // return the future response
        .thenCompose(__ -> attribute.future());
  };
}