Apart from theHTTP ClientAkka HTTP also provides an embedded,Reactive-Streams-based, fully asynchronous HTTP/1.1 server implemented on top ofAkka Stream.
It sports the following features:
• Full support forHTTP persistent connections
• Full support forHTTP pipelining
• Full support for asynchronous HTTP streaming including “chunked” transfer encoding accessible through an idiomatic API
• Optional SSL/TLS encryption
• WebSocket support
The server-side components of Akka HTTP are split into two layers:
1. The basic low-level server implementation in theakka-http-coremodule 2. Higher-level functionality in theakka-httpmodule
The low-level server (1) is scoped with a clear focus on the essential functionality of an HTTP/1.1 server:
• Connection management
• Parsing and rendering of messages and headers
• Timeout management (for requests and connections)
• Response ordering (for transparent pipelining support)
All non-core features of typical HTTP servers (like request routing, file serving, compression, etc.) are left to the higher layers, they are not implemented by theakka-http-core-level server itself. Apart from general focus this design keeps the server core small and light-weight as well as easy to understand and maintain.
8.5. Low-Level Server-Side API 550
Depending on your needs you can either use the low-level API directly or rely on the high-levelRouting DSL which can make the definition of more complex service logic much easier.
Note: It is recommended to read theImplications of the streaming nature of Request/Response Entities sec- tion, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-“streaming first” HTTP Servers.
8.5.1 Streams and HTTP
The Akka HTTP server is implemented on top ofAkka Streamand makes heavy use of it - in its implementation as well as on all levels of its API.
On the connection level Akka HTTP offers basically the same kind of interface asAkka Stream IO: A socket binding is represented as a stream of incoming connections. The application pulls connections from this stream source and, for each of them, provides aFlow[HttpRequest,HttpResponse,_]to “translate” requests into responses.
Apart from regarding a socket bound on the server-side as a Source[IncomingConnection] and each connection as a Source[HttpRequest] with a Sink[HttpResponse] the stream abstraction is also present inside a single HTTP message: The entities of HTTP requests and responses are generally modeled as aSource[ByteString]. See also theHTTP Modelfor more information on how HTTP messages are repre- sented in Akka HTTP.
8.5.2 Starting and Stopping
On the most basic level an Akka HTTP server is bound by invoking thebindmethod of theakka.http.scaladsl.Http extension:
import akka.actor.ActorSystem import akka.http.scaladsl.Http import akka.stream.ActorMaterializer import akka.stream.scaladsl._
implicit val system = ActorSystem()
implicit val materializer = ActorMaterializer() implicit val executionContext = system.dispatcher
val serverSource: Source[Http.IncomingConnection, Future[Http.ServerBinding]] = Http().bind(interface = "localhost", port = 8080)
val bindingFuture: Future[Http.ServerBinding] =
serverSource.to(Sink.foreach { connection => // foreach materializes the source println("Accepted new connection from " + connection.remoteAddress)
// ... and then actually handle the connection }).run()
Arguments to theHttp().bindmethod specify the interface and port to bind to and register interest in handling incoming HTTP connections. Additionally, the method also allows for the definition of socket options as well as a larger number of settings for configuring the server according to your needs.
The result of thebindmethod is aSource[Http.IncomingConnection]which must be drained by the application in order to accept incoming connections. The actual binding is not performed before this source is materialized as part of a processing pipeline. In case the bind fails (e.g. because the port is already busy) the materialized stream will immediately be terminated with a respective exception. The binding is released (i.e. the underlying socket unbound) when the subscriber of the incoming connection source has cancelled its subscription.
Alternatively one can use theunbind()method of theHttp.ServerBindinginstance that is created as part of the connection source’s materialization process. TheHttp.ServerBindingalso provides a way to get a hold of the actual local address of the bound socket, which is useful for example when binding to port zero (and thus letting the OS pick an available port).
8.5. Low-Level Server-Side API 551
8.5.3 Request-Response Cycle
When a new connection has been accepted it will be published as anHttp.IncomingConnectionwhich consists of the remote address and methods to provide aFlow[HttpRequest,HttpResponse,_]to handle requests coming in over this connection.
Requests are handled by calling one of thehandleWithXXXmethods with a handler, which can either be
• aFlow[HttpRequest,HttpResponse,_]forhandleWith,
• a functionHttpRequest => HttpResponseforhandleWithSyncHandler,
• a functionHttpRequest => Future[HttpResponse]forhandleWithAsyncHandler.
Here is a complete example:
import akka.actor.ActorSystem import akka.http.scaladsl.Http
import akka.http.scaladsl.model.HttpMethods._
import akka.http.scaladsl.model._
import akka.stream.ActorMaterializer import akka.stream.scaladsl.Sink implicit val system = ActorSystem()
implicit val materializer = ActorMaterializer() implicit val executionContext = system.dispatcher
val serverSource = Http().bind(interface = "localhost", port = 8080) val requestHandler: HttpRequest => HttpResponse = {
case HttpRequest(GET, Uri.Path("/"), _, _, _) =>
HttpResponse(entity = HttpEntity(
ContentTypes.`text/html(UTF-8)`,
"<html><body>Hello world!</body></html>"))
case HttpRequest(GET, Uri.Path("/ping"), _, _, _) =>
HttpResponse(entity = "PONG!")
case HttpRequest(GET, Uri.Path("/crash"), _, _, _) =>
sys.error("BOOM!") case r: HttpRequest =>
r.discardEntityBytes() // important to drain incoming HTTP Entity stream HttpResponse(404, entity = "Unknown resource!")
}
val bindingFuture: Future[Http.ServerBinding] = serverSource.to(Sink.foreach { connection =>
println("Accepted new connection from " + connection.remoteAddress) connection handleWithSyncHandler requestHandler
// this is equivalent to
// connection handleWith { Flow[HttpRequest] map requestHandler } }).run()
In this example, a request is handled by transforming the request stream with a functionHttpRequest =>
HttpResponseusinghandleWithSyncHandler(or equivalently, Akka Stream’smapoperator). Depend- ing on the use case many other ways of providing a request handler are conceivable using Akka Stream’s combi- nators.
If the application provides aFlowit is also the responsibility of the application to generate exactly one response for every request and that the ordering of responses matches the ordering of the associated requests (which is relevant if HTTP pipelining is enabled where processing of multiple incoming requests may overlap). When relying onhandleWithSyncHandlerorhandleWithAsyncHandler, or themapormapAsyncstream
8.5. Low-Level Server-Side API 552
operators, this requirement will be automatically fulfilled.
Streaming Request/Response Entities
Streaming of HTTP message entities is supported through subclasses ofHttpEntity. The application needs to be able to deal with streamed entities when receiving a request as well as, in many cases, when constructing responses. SeeHttpEntityfor a description of the alternatives.
If you rely on theMarshallingand/orUnmarshallingfacilities provided by Akka HTTP then the conversion of custom types to and from streamed entities can be quite convenient.
Closing a connection
The HTTP connection will be closed when the handlingFlowcancels its upstream subscription or the peer closes the connection. An often times more convenient alternative is to explicitly add aConnection: closeheader to anHttpResponse. This response will then be the last one on the connection and the server will actively close the connection when it has been sent out.
Connection will also be closed if request entity has been cancelled (e.g. by attaching it toSink.cancelled) or consumed only partially (e.g. by usingtakecombinator). In order to prevent this behaviour entity should be explicitly drained by attaching it toSink.ignore.
8.5.4 Configuring Server-side HTTPS
For detailed documentation about configuring and using HTTPS on the server-side refer toServer-Side HTTPS Support.
8.5.5 Stand-Alone HTTP Layer Usage
Due to its Reactive-Streams-based nature the Akka HTTP layer is fully detachable from the underlying TCP interface. While in most applications this “feature” will not be crucial it can be useful in certain cases to be able to “run” the HTTP layer (and, potentially, higher-layers) against data that do not come from the network but rather some other source. Potential scenarios where this might be useful include tests, debugging or low-level event-sourcing (e.g by replaying network traffic).
On the server-side the stand-alone HTTP layer forms aBidiFlowthat is defined like this:
/**
* The type of the server-side HTTP layer as a stand-alone BidiFlow
* that can be put atop the TCP layer to form an HTTP server.
*
* {{{
* +---+
* HttpResponse ~>| |~> SslTlsOutbound
* | bidi |
* HttpRequest <~| |<~ SslTlsInbound
* +---+
* }}}
*/
type ServerLayer = BidiFlow[HttpResponse, SslTlsOutbound, SslTlsInbound,
˓→HttpRequest, NotUsed]
You create an instance of Http.ServerLayer by calling one of the two overloads of the Http().serverLayermethod, which also allows for varying degrees of configuration.
8.5. Low-Level Server-Side API 553
8.5.6 Controlling server parallelism
Request handling can be parallelized on two axes, by handling several connections in parallel and by relying on HTTP pipelining to send several requests on one connection without waiting for a response first. In both cases the client controls the number of ongoing requests. To prevent being overloaded by too many requests, Akka HTTP can limit the number of requests it handles in parallel.
To limit the number of simultaneously open connections, use theakka.http.server.max-connections setting. This setting applies to all ofHttp.bindAndHandle* methods. If you useHttp.bind, incoming connections are represented by aSource[IncomingConnection,...]. Use Akka Stream’s combinators to apply backpressure to control the flow of incoming connections, e.g. by usingthrottleormapAsync.
HTTP pipelining is generally discouraged (anddisabled by most browsers) but is nevertheless fully supported in Akka HTTP. The limit is applied on two levels. First, there’s theakka.http.server.pipeline-limit config setting which prevents that more than the given number of outstanding requests is ever given to the user- supplied handler-flow. On the other hand, the handler flow itself can apply any kind of throttling itself. If you use one of theHttp.bindAndHandleSyncor Http.bindAndHandleAsyncentry-points, you can specify theparallelismargument (default = 1, i.e. pipelining disabled) to control the number of concurrent requests per connection. If you useHttp.bindAndHandleorHttp.bind, the user-supplied handler flow has full control over how many request it accepts simultaneously by applying backpressure. In this case, you can e.g.
use Akka Stream’smapAsynccombinator with a given parallelism to limit the number of concurrently handled requests. Effectively, the more constraining one of these two measures, config setting and manual flow shaping, will determine how parallel requests on one connection are handled.
8.5.7 Handling HTTP Server failures in the Low-Level API
There are various situations when failure may occur while initialising or running an Akka HTTP server. Akka by default will log all these failures, however sometimes one may want to react to failures in addition to them just being logged, for example by shutting down the actor system, or notifying some external monitoring end-point explicitly.
There are multiple things that can fail when creating and materializing an HTTP Server (similarily, the same applied to a plain streamingTcp()server). The types of failures that can happen on different layers of the stack, starting from being unable to start the server, and ending with failing to unmarshal an HttpRequest, examples of failures include (from outer-most, to inner-most):
• Failure tobindto the specified address/port,
• Failure while accepting newIncommingConnection s, for example when the OS has run out of file descriptors or memory,
• Failure while handling a connection, for example if the incomingHttpRequestis malformed.
This section describes how to handle each failure situation, and in which situations these failures may occur.
The first type of failure is when the server is unable to bind to the given port. For example when the port is already taken by another application, or if the port is privileged (i.e. only usable byroot). In this case the “binding future” will fail immediatly, and we can react to if by listening on the Future’s completion:
import akka.actor.ActorSystem import akka.http.scaladsl.Http
import akka.http.scaladsl.Http.ServerBinding import akka.stream.ActorMaterializer
import scala.concurrent.Future implicit val system = ActorSystem()
implicit val materializer = ActorMaterializer() // needed for the future onFailure in the end implicit val executionContext = system.dispatcher // let's say the OS won't allow us to bind to 80.
8.5. Low-Level Server-Side API 554
val (host, port) = ("localhost", 80) val serverSource = Http().bind(host, port)
val bindingFuture: Future[ServerBinding] = serverSource .to(handleConnections) // Sink[Http.IncomingConnection, _]
.run()
bindingFuture.onFailure { case ex: Exception =>
log.error(ex, "Failed to bind to {}:{}!", host, port) }
Once the server has successfully bound to a port, theSource[IncomingConnection,_]starts running and emiting new incoming connections. This source technically can signal a failure as well, however this should only happen in very dramantic situations such as running out of file descriptors or memory available to the system, such that it’s not able to accept a new incoming connection. Handling failures in Akka Streams is pretty stright forward, as failures are signaled through the stream starting from the stage which failed, all the way downstream to the final stages.
In the example below we add a customGraphStage(seeCustom stream processing) in order to react to the stream’s failure. We signal afailureMonitoractor with the cause why the stream is going down, and let the Actor handle the rest – maybe it’ll decide to restart the server or shutdown the ActorSystem, that however is not our concern anymore.
import akka.actor.ActorSystem import akka.actor.ActorRef import akka.http.scaladsl.Http import akka.stream.ActorMaterializer import akka.stream.scaladsl.Flow implicit val system = ActorSystem()
implicit val materializer = ActorMaterializer() implicit val executionContext = system.dispatcher import Http._
val (host, port) = ("localhost", 8080) val serverSource = Http().bind(host, port)
val failureMonitor: ActorRef = system.actorOf(MyExampleMonitoringActor.props) val reactToTopLevelFailures = Flow[IncomingConnection]
.watchTermination()((_, termination) => termination.onFailure { case cause => failureMonitor ! cause
})
serverSource
.via(reactToTopLevelFailures)
.to(handleConnections) // Sink[Http.IncomingConnection, _]
.run()
The third type of failure that can occur is when the connection has been properly established, however afterwards is terminated abruptly – for example by the client aborting the underlying TCP connection. To handle this failure we can use the same pattern as in the previous snippet, however apply it to the connection’s Flow:
import akka.actor.ActorSystem import akka.http.scaladsl.Http import akka.http.scaladsl.model._
import akka.stream.ActorMaterializer import akka.stream.scaladsl.Flow implicit val system = ActorSystem()
implicit val materializer = ActorMaterializer()
8.5. Low-Level Server-Side API 555
implicit val executionContext = system.dispatcher val (host, port) = ("localhost", 8080)
val serverSource = Http().bind(host, port) val reactToConnectionFailure = Flow[HttpRequest]
.recover[HttpRequest] { case ex =>
// handle the failure somehow throw ex
}
val httpEcho = Flow[HttpRequest]
.via(reactToConnectionFailure) .map { request =>
// simple streaming (!) "echo" response:
HttpResponse(entity = HttpEntity(ContentTypes.`text/plain(UTF-8)`, request.
˓→entity.dataBytes)) }
serverSource
.runForeach { con =>
con.handleWith(httpEcho) }
These failures can be described more or less infrastructure related, they are failing bindings or connections. Most of the time you won’t need to dive into those very deeply, as Akka will simply log errors of this kind anyway, which is a reasonable default for such problems.
In order to learn more about handling exceptions in the actual routing layer, which is where your application code comes into the picture, refer toException Handlingwhich focuses explicitly on explaining how exceptions thrown in routes can be handled and transformed intoHttpResponses with apropriate error codes and human-readable failure descriptions.