Connection-level API

The connection-level API is the lowest-level client-side API spray-can provides. It gives you full control over when HTTP connections are opened and closed and when requests are to be send across which connection. As such it offers the highest flexibility at the cost of providing the least convenience.

Opening HTTP Connections

With the connection-level API you open a new HTTP connection to a given host by sending an Http.Connect command message to the Http extensions as such:

IO(Http) ! Http.Connect("", port = 8080)

Apart from the host name and port the Http.Connect message also allows you to specify socket options and a larger number of configuration settings for the connection.

Upon receipt of an Http.Connect message spray-can internally spawns a new HttpClientConnection actor that manages a single HTTP connection across all of its lifetime. Your code never deals with the HttpClientConnection actor class directly, in fact it is marked private to the spray-can package. All communication with a connection actor happens purely via actor messages, the majority of which are defined in the spray.can.Http object.

After a new connection actor has been started it tries to open a new TCP connection to the given endpoint and responds with an Http.Connected event message to the sender of the Http.Connect command as soon as the connection has been successfully established. If the connection could not be opened for whatever reason an Http.CommandFailed event is being dispatched instead and the connection actor is stopped.

Request-Response Cycle

Once the connection actor has responded with an Http.Connected event you can send it one or more spray-http HttpRequestPart messages. The connection actor will serialize them across the connection and wait for responses. As soon as a response for a request has been received it is dispatched as a HttpResponsePart instance to the sender of the respective request.

After having received a response for a request the application can decide to send another request across the same connection (i.e. to the same connection actor) or close the connection and (potentially) open a new one.

Closing Connections

Unless some kind of error (or timeout) occurs the connection actor will never actively close an established connection, even if the response contains a Connection: close header. The application can decide to actively close a connection by sending the connection actor one of the Http.CloseCommand messages described in the chapter about Common Behavior.

Close notification events are dispatched to the senders of all requests that still have unfinished responses pending as well as all actors that might have already sent Http.CloseCommand messages.


If no response to a request is received within the configured request-timeout period the connection actor closes the connection and dispatches an Http.Closed event message to the senders of all requests that are currently open.

If the connection is closed after the configured idle-timeout has expired the connection actor simply closes the connection and stops itself. If the application would like to be notified of such events it should “watch” the connection actor and react to the respective Terminated events (which is a good idea in any case).

In order to change the respective config setting for this connection only the application can send the following messages to the connection actor:

  • spray.http.SetRequestTimeout