Design Philosophy

The spray-can HttpServer is scoped with a clear focus on the essential functionality of an HTTP/1.1 server:

• Connection management
• Message parsing and header separation
• 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 next-higher layer in the application stack, they are not implemented by spray-can itself. Apart from general focus this design keeps the server small and light-weight as well as easy to understand and maintain. It also makes a spray-can HTTP server a perfect “container” for a spray-routing application, since spray-can and spray-routing nicely complement and interface into each other.

Basic Architecture

The spray-can HTTP server is implemented by two types of Akka actors, which sit on top of Akka IO. When you tell spray-can to start a new server instance on a given port an HttpListener actor is started, which accepts incoming connections and for each one spawns a new HttpServerConnection actor, which then manages the connection for the rest of its lifetime. These connection actors process the requests coming in across their connection and dispatch them as immutable spray-http HttpRequest instances to a “handler” actor provided by your application. The handler can complete a request by simply replying with an HttpResponse instance:

def receive = {
  case HttpRequest(GET, Uri.Path("/ping"), _, _, _) =>
    sender ! HttpResponse(entity = "PONG")
}

Your code never deals with the HttpListener and HttpServerConnection actor classes directly, in fact they are marked private to the spray-can package. All communication with these actors happens purely via actor messages, the majority of which are defined in the spray.can.Http object.

Starting

A spray-can HTTP server is started by sending an Http.Bind command to the Http extension:

import akka.io.IO
import spray.can.Http

implicit val system = ActorSystem()

val myListener: ActorRef = // ...

IO(Http) ! Http.Bind(myListener, interface = "localhost", port = 8080)

With the Http.Bind command you register an application-level “listener” actor and specify the interface and port to bind to. Additionally the Http.Bind command also allows you to define socket options as well as a larger number of settings for configuring the server according to your needs.

The sender of the Http.Bind command (e.g. an actor you have written) will receive an Http.Bound reply after the HTTP layer has successfully started the server at the respective endpoint. In case the bind fails (e.g. because the port is already busy) an Http.CommandFailed message is dispatched instead.

The sender of the Http.Bound confirmation event is spray-can‘s HttpListener instance. You will need this ActorRef if you want to stop the server later.

Stopping

To explicitly stop the server, send an Http.Unbind command to the HttpListener instance (the ActorRef for this instance is available as the sender of the Http.Bound confirmation event from when the server was started).

The listener will reply with an Http.Unbound event after successfully unbinding from the port (or with an Http.CommandFailed in the case of error). At that point no further requests will be accepted by the server.

Any requests which were in progress at the time will proceed to completion. When the last request has terminated, the HttpListener instance will exit. You can monitor for this (e.g. so that you can shutdown the ActorSystem) by watching the listener actor and awaiting a Terminated message.

Message Protocol

After having successfully bound an HttpListener your application communicates with the spray-can-level connection actors via a number of actor messages that are explained in this section.

case class Stats(
  uptime: FiniteDuration,
  totalRequests: Long,
  openRequests: Long,
  maxOpenRequests: Long,
  totalConnections: Long,
  openConnections: Long,
  maxOpenConnections: Long,
  requestTimeouts: Long)

HTTP Headers

When a spray-can connection actor receives an HTTP request it tries to parse all its headers into their respective spray-http model classes. No matter whether this succeeds or not, the connection actor will always pass on all received headers to the application. Unknown headers as well as ones with invalid syntax (according to spray‘s header parser) will be made available as RawHeader instances. For the ones exhibiting parsing errors a warning message is logged depending on the value of the illegal-header-warnings config setting.

When sending out responses the connection actor watches for a Connection header set by the application and acts accordingly, i.e. you can force the connection actor to close the connection after having sent the response by including a Connection("close") header. To unconditionally force a connection keep-alive you can explicitly set a Connection("Keep-Alive") header. If you don’t set an explicit Connection header the connection actor will keep the connection alive if the client supports this (i.e. it either sent a Connection: Keep-Alive header or advertised HTTP/1.1 capabilities without sending a Connection: close header).

The following response headers are managed by the spray-can layer itself and as such are ignored if you “manually” add them to the response (you’ll see a warning in your logs):

• Content-Type
• Content-Length
• Transfer-Encoding
• Date
• Server

There are three exceptions:

1. Responses to HEAD requests that have an empty entity are allowed to contain a user-specified Content-Type header.
2. Responses in ChunkedResponseStart messages that have an empty entity are allowed to contain a user-specified Content-Type header.
3. Responses in ChunkedResponseStart messages are allowed to contain a user-specified Content-Length header if spray.can.server.chunkless-streaming is enabled.

HTTP Pipelining

spray-can fully supports HTTP pipelining. If the configured pipelining-limit is greater than one a connection actor will accept several requests in a row (coming in across a single connection) and dispatch them to the application even before the first one has been responded to. This means that several requests will potentially be handled by the application at the same time.

Since in many asynchronous applications request handling times can be somewhat undeterministic spray-can takes care of properly ordering all responses coming in from your application before sending them out to “the wire”. I.e. your application will “see” requests in the order they are coming in but is not required to itself uphold this order when generating responses.

SSL Support

If enabled via the ssl-encryption config setting the spray-can connection actors pipe all IO traffic through an SslTlsSupport module, which can perform transparent SSL/TLS encryption. This module is configured via the implicit ServerSSLEngineProvider member on the Http.Bind command message. An ServerSSLEngineProvider is essentially a function PipelineContext ⇒ Option[SSLEngine], which determines whether encryption is to be performed and, if so, which javax.net.ssl.SSLEngine instance is to be used.

If you’d like to apply some custom configuration to your SSLEngine instances an easy way would be to bring a custom engine provider into scope, e.g. like this:

import spray.io.ServerSSLEngineProvider

implicit val myEngineProvider = ServerSSLEngineProvider { engine =>
  engine.setEnabledCipherSuites(Array("TLS_RSA_WITH_AES_256_CBC_SHA"))
  engine.setEnabledProtocols(Array("SSLv3", "TLSv1"))
  engine
}

EngineProvider creation also relies on an implicitly available SSLContextProvider, which is defined like this:

trait SSLContextProvider extends (PipelineContext ⇒ Option[SSLContext])

The default SSLContextProvider simply provides an implicitly available “constant” SSLContext, by default the SSLContext.getDefault is used. This means that the easiest way to have the server use a custom SSLContext is to simply bring one into scope implicitly:

import javax.net.ssl.SSLContext

implicit val mySSLContext: SSLContext = {
  val context = SSLContext.getInstance("TLS")
  // context.init(...)
  context
}

Basic API Structure

Depending on the specific needs of your use case you should pick the

Connection-level API

for full-control over when HTTP connections are opened/closed and how requests are scheduled across them.

Host-level API

for letting spray-can manage a connection-pool for one specific host.

Request-level API

for letting spray-can take over all connection management.

You can interact with spray-can on different levels at the same time and, independently of which API level you choose, spray-can will happily handle many thousand concurrent connections to a single or many different hosts.

Chunked Requests

While the host- and request-level APIs do not currently support chunked (streaming) HTTP requests the connection-level API does. Alternatively to a single HttpRequest the application can choose to send this sequence of individual messages:

• One ChunkedRequestStart
• Zero or more MessageChunks
• One ChunkedMessageEnd

The connection actor will render these as one logical HTTP request with Transfer-Encoding: chunked. The timer for checking request timeouts (if configured to non-zero) only starts running when the final ChunkedMessageEnd message was sent out.

Chunked Responses

Chunked (streaming) responses are supported by all three API levels. If the response-chunk-aggregation-limit connection config setting is set to zero the individual response parts of chunked requests are dispatched to the application as they come in. In these cases a full response consists of the following messages:

• One ChunkedResponseStart
• Zero or more MessageChunks
• One ChunkedMessageEnd

The timer for checking request timeouts (if configured to non-zero) will stop running as soon as the initial ChunkedResponseStart message has been received, i.e. there is currently no timeout checking for and in between individual response chunks.

HTTP Headers

When a spray-can connection actor receives an HTTP response it tries to parse all its headers into their respective spray-http model classes. No matter whether this succeeds or not, the connection actor will always pass on all received headers to the application. Unknown headers as well as ones with invalid syntax (according to spray‘s header parser) will be made available as RawHeader instances. For the ones exhibiting parsing errors a warning message is logged depending on the value of the illegal-header-warnings config setting.

The following message headers are managed by the spray-can layer itself and as such are ignored if you “manually” add them to an outgoing request:

• Content-Type
• Content-Length
• Transfer-Encoding

There are two exceptions for requests in ChunkedRequestStart messages:

1. They are allowed to contain a user-specified Content-Type header if their entity is empty.
2. They must contain a user-specified Content-Length header if spray.can.client.chunkless-streaming is enabled. This Content-Length header must fit the total length of all requests chunks.

Additionally spray-can will render a

• Host request header if none is explicitly added.
• User-Agent default request header if none is explicitly defined. The default value can be configured with the spray.can.client.user-agent-header configuration setting.

SSL Support

SSL support is enabled

• for the connection-level API by setting Http.Connect(sslEncryption = true) when connecting to a server
• for the host-level API by setting Http.HostConnectorSetup(sslEncryption = true) when creating a host connector
• for the request-level API by using an https URL in the request

Particular SSL settings can be configured via the implicit ClientSSLEngineProvider member on the Http.Connect and Http.HostConnectorSetup command messages. An ClientSSLEngineProvider is essentially a function PipelineContext ⇒ Option[SSLEngine] which determines whether encryption is to be performed and, if so, which javax.net.ssl.SSLEngine instance is to be used. By returning None the ClientSSLEngineProvider can decide to disable SSL support even if SSL support was requested by the means described above.

If you’d like to apply some custom configuration to your SSLEngine instances an easy way would be to bring a custom engine provider into scope, e.g. like this:

import spray.io.ClientSSLEngineProvider

implicit val myEngineProvider = ClientSSLEngineProvider { engine =>
  engine.setEnabledCipherSuites(Array("TLS_RSA_WITH_AES_256_CBC_SHA"))
  engine.setEnabledProtocols(Array("SSLv3", "TLSv1"))
  engine
}

EngineProvider creation also relies on an implicitly available SSLContextProvider, which is defined like this:

trait SSLContextProvider extends (PipelineContext ⇒ Option[SSLContext])

The default SSLContextProvider simply provides an implicitly available “constant” SSLContext, by default the SSLContext.getDefault is used. This means that the easiest way to have the server use a custom SSLContext is to simply bring one into scope implicitly:

import javax.net.ssl.SSLContext

implicit val mySSLContext: SSLContext = {
  val context = SSLContext.getInstance("TLS")
  // context.init(...)
  context
}

Redirection Following

Automatic redirection following for 3xx responses is supported by setting configuring the spray.can.host-connector.max-redirects setting. This is the logic that is then applied:

• If set to zero redirection responses will not be followed, i.e. they’ll be returned to the user as is.
• If set to a value > zero redirection responses will be followed up to the given number of times.
• If the redirection chain is longer than the configured value the first redirection response that is is not followed anymore is returned to the user as is.

By default max-redirects is set to 0.

Since this setting is at the host level, it is possible to configure a different number of max-redirects for different hosts (see Request-level API). In this situation the max-redirects configured for the host of the initial request is respected for the entire redirection chain. This is true even if redirection means changing to another host.

Closing Connections

Server- and client-side connection actors can be sent one of three defined Http.CloseCommand messages in order to trigger the closing of an HTTP connection. They mirror the TCP-level commands and events from Akka IO and have the following semantics:

Http.Close

A “regular” close. Potentially pending unsent data are flushed to the connection before a TCP FIN is sent. The peers FIN ACK is not awaited. If the close is successful the sender will be notified with an Http.Closed event message.

Http.ConfirmedClose

The closing of the connection is intially started by flushing pending writes and sending a TCP FIN to the peer. Data will continue to be received until the peer closes the connection too with its own FIN. If the close is successful the sender will be notified with an Http.ConfirmedClosed event message.

Http.Abort

Immediately terminates the connection by sending a RST message to the peer. Pending writes are not flushed. If the close is successful the sender will be notified with an Http.Aborted event message.

In addition to the confirmation events mentioned above the connection actor will dispatch two other events derived from the Http.ConnectionClosed trait in certain cases:

Http.PeerClosed

Dispatched when the remote peer has closed the connection without “our” side having initiated the close first.

Http.ErrorClosed

Dispatched whenever an error occurred that forced the connection to be closed.

ACKed Sends

If required the server- and client-side connection actors can confirm the successful delivery of an HTTP message (part) to the OS network layer by replying with a “send ACK” message. The application can request a send ACK by modifying a message part with the withAck method. For example, the following handler logic receives the String “ok” as an actor message after the response has been successfully written to the connections socket:

def receive = {
  case HttpRequest(GET, Uri.Path("/ping"), _, _, _) =>
    sender ! HttpResponse(entity = "PONG").withAck("ok")

  case "ok" => println("Response was sent successfully")
}

Such ACK messages are especially helpful for triggering the sending of the next message part in a request- or response streaming scenario since with such a design the application will never produce more data than the network can handle.

Send ACKs are always dispatched to the actor which sent the respective message (part). They are only supported on the server-side as well as on the client-side connection-level API (i.e. not currently on the client-side host- and request-level APIs).

simple-http-client

This example demonstrates how you can use the three different client-side API levels for performing a simple request/response cycle.

Follow these steps to run it on your machine:

1. Clone the spray repository:

   git clone git://github.com/spray/spray.git
   

2. Change into the base directory:

   cd spray
   

3. Run SBT:

   sbt "project simple-http-client" run
   

   (If this doesn’t work for you your SBT runner cannot deal with grouped arguments. In this case you’ll have to run the commands project simple-http-client and run sequentially “inside” of SBT.)

simple-http-server

This examples implements a very simple web-site built with the spray-can HTTP Server. It shows off various features like streaming, stats support and timeout handling.

Follow these steps to run it on your machine:

1. Clone the spray repository:

   git clone git://github.com/spray/spray.git
   

2. Change into the base directory:

   cd spray
   

3. Run SBT:

   sbt "project simple-http-server" run
   

   (If this doesn’t work for you your SBT runner cannot deal with grouped arguments. In this case you’ll have to run the commands project simple-http-server and run sequentially “inside” of SBT.)

4. Browse to http://127.0.0.1:8080/

5. Alternatively you can access the service with curl:

   curl -v 127.0.0.1:8080/ping
   

6. Stop the service with:

   curl -v 127.0.0.1:8080/stop
   

server-benchmark

This example implements a very simple “ping/pong” server for benchmarking purposes, that mirrors the “JSON serialization” test setup from the techempower benchmark.

Follow these steps to run it on your machine:

1. Clone the spray repository:

   git clone git://github.com/spray/spray.git
   

2. Change into the base directory:

   cd spray
   

3. Run SBT:

   sbt "project server-benchmark" run
   

   (If this doesn’t work for you your SBT runner cannot deal with grouped arguments. In this case you’ll have to run the commands project server-benchmark and run sequentially “inside” of SBT.)

4. Use a load-generation tool like ab, weighttp, wrk or the like to fire test requests, e.g.:

   wrk -t4 -c100 -d10 http://127.0.0.1:8080/ping
   

If you start the server with re-start rather than run it will run in a forked JVM that has -verbose:gc and -XX:+PrintCompilation flags set, so you can see how often GC is performed and whether the JIT compiler is “done” with compiling all the hot spots.

Default Marshallers

spray-httpx comes with pre-defined Marshallers for the following types:

• BasicMarshallers
  • Array[Byte]
  • Array[Char]
  • String
  • NodeSeq
  • Throwable
  • spray.http.FormData
  • spray.http.HttpEntity
• MetaMarshallers
  • Option[T]
  • Either[A, B]
  • Try[T]
  • Future[T]
  • Stream[T]
• MultipartMarshallers
  • spray.http.MultipartContent
  • spray.http.MultipartFormData

Implicit Resolution

Since the marshalling infrastructure uses a type class based approach Marshaller instances for a type T have to be available implicitly. The implicits for all the default Marshallers defined by spray-httpx are provided through the companion object of the Marshaller trait. This means that they are always available and never need to be explicitly imported. Additionally, you can simply “override” them by bringing your own custom version into local scope.

Custom Marshallers

spray-httpx gives you a few convenience tools for constructing Marshallers for your own types. One is the Marshaller.of helper, which is defined as such:

def of[T](marshalTo: ContentType*)
         (f: (T, ContentType, MarshallingContext) => Unit): Marshaller[T]

The default StringMarshaller for example is defined with it:

// prefer UTF-8 encoding, but also render with other encodings if the client requests them
implicit val StringMarshaller = stringMarshaller(ContentTypes.`text/plain(UTF-8)`, ContentTypes.`text/plain`)

def stringMarshaller(contentType: ContentType, more: ContentType*): Marshaller[String] =
  Marshaller.of[String](contentType +: more: _*) { (value, contentType, ctx) ⇒
    ctx.marshalTo(HttpEntity(contentType, value))
  }

As another example, here is a Marshaller definition for a custom type Person:

import spray.http._
import spray.httpx.marshalling._

val `application/vnd.acme.person` =
  MediaTypes.register(MediaType.custom("application/vnd.acme.person"))

case class Person(name: String, firstName: String, age: Int)

object Person {
  implicit val PersonMarshaller =
    Marshaller.of[Person](`application/vnd.acme.person`) { (value, contentType, ctx) =>
      val Person(name, first, age) = value
      val string = "Person: %s, %s, %s".format(name, first, age)
      ctx.marshalTo(HttpEntity(contentType, string))
    }
}

marshal(Person("Bob", "Parr", 32)) ===
  Right(HttpEntity(`application/vnd.acme.person`, "Person: Bob, Parr, 32"))

As can be seen in this example you best define the Marshaller for T in the companion object of T. This way your marshaller is always in-scope, without any import tax.

Deriving Marshallers

Sometimes you can save yourself some work by reusing existing Marshallers for your custom ones. The idea is to “wrap” an existing Marshaller with some logic to “re-target” it to your type.

In this regard wrapping a Marshaller can mean one or both of the following two things:

• Transform the input before it reaches the wrapped Marshaller
• Transform the output of the wrapped Marshaller

You can do both, but the existing support infrastructure favors the first over the second. The Marshaller.delegate helper allows you to turn a Marshaller[B] into a Marshaller[A] by providing a function A => B:

def delegate[A, B](marshalTo: ContentType*)
                  (f: A => B)
                  (implicit mb: Marshaller[B]): Marshaller[A]

This is used, for example, by the NodeSeqMarshaller, which delegates to the StringMarshaller like this:

implicit val NodeSeqMarshaller =
  Marshaller.delegate[NodeSeq, String](`text/xml`, `application/xml`,
    `text/html`, `application/xhtml+xml`)(_.toString)

There is also a second overload of the delegate helper that takes a function (A, ContentType) => B rather than a function A => B. It’s helpful if your input conversion requires access to the ContentType that is marshalled to.

If you want the second wrapping type, transformation of the output, things are a bit harder (and less efficient), since Marshallers produce HttpEntities rather than Strings. An HttpEntity contains the serialized result, which is essentially an Array[Byte] and a ContentType. So, for example, prepending a string to the output of the underlying Marshaller would entail deserializing the bytes into a string, prepending your prefix and reserializing into a byte array.... not pretty and quite inefficient. Nevertheless, you can do it. Just produce a custom MarshallingContext, which wraps the original one with custom logic, and pass it to the inner Marshaller. However, a general solution would also require you to think about the handling of chunked responses, errors, etc.

Because the second form of wrapping is less attractive there is no real helper infrastructure for it. We generally do not want to encourage such type of design. (With one exception: Simply overriding the Content-Type of another Marshaller can be done efficiently. This is why the MarshallingContext already comes with a withContentTypeOverriding copy helper.)

ToResponseMarshaller

The plain Marshaller[T] is agnostic to whether it is used on the server- or on the client-side. This means that it can be used to produce the entities (and additional headers) for responses as well as requests.

Sometimes, however, this is not enough. If you know that you need to only marshal to HttpResponse instances (e.g. because you only use spray on the server-side) you can also write a ToResponseMarshaller[T] for your type. This more specialized marshaller allows you to produce the complete HttpResponse instance rather than only its entity. As such the marshaller can also set the status code of the response (which doesn’t exist on the request side).

When looking for a way to marshal a custom type T spray (or rather the Scala compiler) first looks for a ToResponseMarshaller[T] for the type. Only if none is found will an in-scope Marshaller[T] be used.

Default Unmarshallers

spray-httpx comes with pre-defined Unmarshallers for the following types:

• Array[Byte]
• Array[Char]
• String
• NodeSeq
• Option[T]
• spray.http.FormData
• spray.http.HttpForm
• spray.http.MultipartContent
• spray.http.MultipartFormData

The relevant sources are:

• Deserializer
• BasicUnmarshallers
• MetaUnmarshallers
• FormDataUnmarshallers

Implicit Resolution

Since the unmarshalling infrastructure uses a type class based approach Unmarshaller instances for a type T have to be available implicitly. The implicits for all the default Unmarshallers defined by spray-httpx are provided through the companion object of the Deserializer trait (since Unmarshaller[T] is just an alias for a Deserializer[HttpEntity, T]). This means that they are always available and never need to be explicitly imported. Additionally, you can simply “override” them by bringing your own custom version into local scope.

Custom Unmarshallers

spray-httpx gives you a few convenience tools for constructing Unmarshallers for your own types. One is the Unmarshaller.apply helper, which is defined as such:

def apply[T](unmarshalFrom: ContentTypeRange*)
            (f: PartialFunction[HttpEntity, T]): Unmarshaller[T]

The default NodeSeqUnmarshaller for example is defined with it:

implicit val NodeSeqUnmarshaller =
  Unmarshaller[NodeSeq](`text/xml`, `application/xml`, `text/html`, `application/xhtml+xml`) {
    case HttpEntity.NonEmpty(contentType, data) ⇒
      XML.withSAXParser(createSAXParser())
        .load(new InputStreamReader(new ByteArrayInputStream(data.toByteArray), contentType.charset.nioCharset))
    case HttpEntity.Empty ⇒ NodeSeq.Empty
  }

As another example, here is an Unmarshaller definition for a custom type Person:

import spray.httpx.unmarshalling._
import spray.util._
import spray.http._

val `application/vnd.acme.person` =
  MediaTypes.register(MediaType.custom("application/vnd.acme.person"))

case class Person(name: String, firstName: String, age: Int)

object Person {
  implicit val PersonUnmarshaller =
    Unmarshaller[Person](`application/vnd.acme.person`) {
      case HttpEntity.NonEmpty(contentType, data) =>
        // unmarshal from the string format used in the marshaller example
        val Array(_, name, first, age) =
          data.asString.split(":,".toCharArray).map(_.trim)
        Person(name, first, age.toInt)

      // if we had meaningful semantics for the HttpEntity.Empty
      // we could add a case for the HttpEntity.Empty:
      // case HttpEntity.Empty => ...
    }
}

val body = HttpEntity(`application/vnd.acme.person`, "Person: Bob, Parr, 32")
body.as[Person] === Right(Person("Bob", "Parr", 32))

As can be seen in this example you best define the Unmarshaller for T in the companion object of T. This way your unmarshaller is always in-scope, without any import tax.

Deriving Unmarshallers

def delegate[A, B](unmarshalFrom: ContentTypeRange*)
                  (f: A => B)
                  (implicit mb: Unmarshaller[A]): Unmarshaller[B]

implicit val SimplerPersonUnmarshaller =
  Unmarshaller.delegate[String, Person](`application/vnd.acme.person`) { string =>
    val Array(_, name, first, age) = string.split(":,".toCharArray).map(_.trim)
    Person(name, first, age.toInt)
  }

implicit val myNodeSeqUnmarshaller = Unmarshaller.forNonEmpty[NodeSeq]

HttpEntity(MediaTypes.`text/xml`, "<xml>yeah</xml>").as[NodeSeq] === Right(<xml>yeah</xml>)
HttpEntity.Empty.as[NodeSeq] === Left(ContentExpected)

More specific Unmarshallers

The plain Unmarshaller[T] is agnostic to whether it is used on the server- or on the client-side. This means that it can be used to deserialize the entities from requests as well as responses. Also, the only information that an Unmarshaller[T] has access to for its job is the message entity. Sometimes this is not enough.

type FromMessageUnmarshaller[T] = Deserializer[HttpMessage, T]

type FromRequestUnmarshaller[T] = Deserializer[HttpRequest, T]

type FromResponseUnmarshaller[T] = Deserializer[HttpResponse, T]

Compression of Chunk Streams

Properly combining HTTP compression with the chunked HTTP/1.1 Transfer-Encoding can be a little tricky. For optimal results the peer sending the message (i.e. the client or the server) should use a single compression context across all chunks, so that common patterns shared by several chunks contribute to a high compression ratio. At the same time the decompressor at the other end must be able to properly decompress each chunk as it arrives.

In order to achieve this the compressor must properly flush its compression stream after each chunk, something that the GZIP- and DeflaterOutputStream implementations of the Java 6 JDK unfortunately do not support correctly (see this JDK bug, fixed only in Java 7). sprays compression implementation jumps through a few hoops to achieve the desired behavior also under Java 6, with no cost to you as the user.

Predefined Response Transformers

decode(decoder: Decoder): HttpResponse ⇒ HttpResponse

Decodes a response using the given Decoder (Gzip or Deflate).

unmarshal[T: Unmarshaller]: HttpResponse ⇒ T

Unmarshalls the response to a custom type using the in-scope Unmarshaller[T].

logResponse(...): HttpResponse ⇒ HttpResponse

Doesn’t actually change the response but simply logs it.

SimpleRoutingApp

spray-routing also comes with the SimpleRoutingApp trait, which you can use as a basis for your first spray endeavours. It reduces the boilerplate to a minimum and allows you to focus entirely on your route structure.

Just use this minimal example application as a starting point:

import spray.routing.SimpleRoutingApp

object Main extends App with SimpleRoutingApp {
  implicit val system = ActorSystem("my-system")

  startServer(interface = "localhost", port = 8080) {
    path("hello") {
      get {
        complete {
          <h1>Say hello to spray</h1>
        }
      }
    }
  }
}

This very concise way of bootstrapping a spray-routing application works nicely as long as you don’t have any special requirements with regard to the actor which is running your route structure. Once you need more control over it, e.g. because you want to be able to use it as the receiver (or sender) of custom messages, you’ll have to fall back to creating your service actor “manually”. The Complete Examples demonstrate how to do that.