spray Release V ERSION March 01, 2016 Contents 1 What is spray? 1 1.1 Principles.................................................1 1.2 Modules.................................................1 1.3 Philosophy................................................2 2 Getting Started 3 3 spray for Web Development 5 3.1 This Site.................................................6 4 Other Resources 7 5 Documentation 9 5.1 spray-caching...............................................9 5.2 spray-can................................................. 11 5.3 spray-client................................................ 33 5.4 spray-http................................................. 36 5.5 spray-httpx................................................ 37 5.6 spray-io.................................................. 48 5.7 spray-routing............................................... 49 5.8 spray-servlet............................................... 157 5.9 spray-testkit............................................... 163 5.10 spray-util................................................. 167 6 Project Info 169 6.1 Current Versions............................................. 169 6.2 Migration from M8............................................ 170 6.3 Maven Repository............................................ 175 6.4 Contributing............................................... 175 6.5 Changelog................................................ 178 6.6 Credits.................................................. 193 6.7 References................................................ 194 6.8 Sponsors................................................. 195 6.9 License.................................................. 195 6.10 Community Projects........................................... 195 7 Blog 197 7.1 spray on the Raspberry Pi........................................ 197 7.2 spray 1.0-M8 / 1.1-M8 / 1.2-M8 released................................ 199 i 7.3 Benchmarking spray........................................... 200 7.4 The Magnet Pattern........................................... 203 7.5 Welcome to the spray Blog....................................... 214 8 Contact 215 8.1 Mailing List............................................... 215 8.2 Twitter.................................................. 215 8.3 Email................................................... 215 8.4 Commercial Support........................................... 215 Bibliography 217 ii CHAPTER 1 What is spray? spray is a suite of lightweight Scala libraries providing client- and server-side REST/HTTP support on top Akka. We believe that, having chosen Scala (and possibly Akka) as primary tools for building software, you’ll want to rely on their power not only in your application layer but throughout the full (JVM-level) network stack. spray provides just that: a set of integrated components for all your REST/HTTP needs that let you work with idiomatic Scala (and Akka) APIs at the stack level of your choice, all implemented without any wrapping layers around “legacy” Java libraries. 1.1 Principles sprays development is guided by the following principles: Fully asynchronous, non-blocking All APIs are fully asynchronous, blocking code is avoided wherever at all possi- ble. Actor- and Future-based spray fully embraces the programming model of the platform it is built upon. Akka Actors and Futures are key constructs of its APIs. High-performance Especially sprays low-level components are carefully crafted for excellent performance in high- load environments. Lightweight All dependencies are very carefully managed, sprays codebase itself is kept as lean as possible. Modular Being structured into a set of integrated but loosely coupled components your application only needs to depend onto the parts that are actually used. Testable All spray components are structured in a way that allows for easy and convenient testing. 1.2 Modules Currently the spray suite consists of these modules: spray-caching Fast and lightweight in-memory caching built upon concurrentlinkedhashmap and Akka Futures. spray-can A low-level, low-overhead, high-performance HTTP server and client built on top of spray-io. spray-client Provides client-side HTTP support at a higher level than the low-level spray-can HTTP Client APIs, which it builds on. spray-http An immutable model of HTTP requests, responses and common headers. This module is completely stand-alone, it neither depends on Akka nor on any other part of spray. 1 spray, Release V ERSION spray-httpx Higher-level tools for working with HTTP messages (mainly marshalling, unmarshalling and (de)compression) that are used by both spray-client as well as spray-routing. spray-io A low-level network IO layer for directly connecting Akka actors to asynchronous Java NIO sockets. We like to think of it a basic version of Netty for Scala. As of 1.0-M8/1.1-M8 it contains a backport of the new Akka IO layer coming with Akka 2.2. In 1.2-M8 it merely contains a few spray-specific “left-overs” that will likely go away completely in the future. spray-servlet An adapter layer providing (a subset of) the spray-can HTTP Server interface on top of the Servlet API. Enables the use of spray-routing in a servlet container. spray-routing A high-level routing DSL for elegantly defining RESTful web services. spray-testkit A DSL for easily testing spray-routing services. Supports both ScalaTest as well as Specs2. spray-util Small utility module used by all other modules except spray-http. spray-json A lightweight, clean and simple JSON implementation in Scala. Because it neither depends on any other part of spray nor on Akka and is only an optional dependency of spray-client and spray-httpx it doesn’t live in the main spray repository, but rather in its own github repository Note that you can easily use spray with whatever JSON library you like best, spray-json is just one of several alternatives. 1.3 Philosophy Since its inception in early 2011 sprays development has been driven with a clear focus on providing tools for building integration layers rather than application cores. As such it regards itself as a suite of libraries rather than a framework. A framework, as we’d like to think of the term, gives you a “frame”, in which you build your application. It comes with a lot of decisions already pre-made and provides a foundation including support structures that lets you get started and deliver results quickly. In a way a framework is like a skeleton onto which you put the “flesh” of your application in order to have it come alive. As such frameworks work best if you choose them before you start application development and try to stick to the frameworks “way of doing things” as you go along. For example, if you are building a browser-facing web application it makes sense to choose a web framework and build your application on top of it because the “core” of the application is the interaction of a browser with your code on the web-server. The framework makers have chosen one “proven” way of designing such applications and let you “fill in the blanks” of a more or less flexible “application-template”. Being able to rely on best-practice architecture like this can be a great asset for getting things done quickly. However, if your application is not primarily a web application because its core is not browser-interaction but some specialized maybe complex business service and you are merely trying to connect it to the world via a REST/HTTP interface a web-framework might not be what you need. In this case the application architecture should be dic- tated by what makes sense for the core not the interface layer. Also, you probably won’t benefit from the possibly existing browser-specific framework components like view templating, asset management, JavaScript- and CSS gen- eration/manipulation/minification, localization support, AJAX support, etc. spray was designed specifically as “not-a-framework”, not because we don’t like frameworks, but for use cases where a framework is not the right choice. spray is made for building integration layers based on HTTP and as such tries to “stay on the sidelines”. Therefore you normally don’t build your application “on top of” spray, but you build your application on top of whatever makes sense and use spray merely for the HTTP integration needs. 2 Chapter 1. What is spray? CHAPTER 2 Getting Started To help you get going we created the spray-template project on GitHub. This provides everything you need to get a spray HTTP server application up-and-running in under 5 minutes and view the result in your browser. Try running one of these examples: • spray as a standalone service - this uses the spray-routing and spray-can modules • spray inside a servlet container - uses spray-routing and spray-servlet inside a Jetty server Note: each example lives in its own Git branch of the spray-template project. 3 spray, Release V ERSION 4 Chapter 2. Getting Started CHAPTER 3 spray for Web Development Even though sprays development focus so far has not been web applications but HTTP-based integration layers, you can of course use it for powering browser-based GUIs as well. The recent trend of moving web application logic more and more away from the server and into the (JS-based) browser client as well as the increasing availability of good SBT-plugins for things spray itself does not provide (like view-templating or LESS- and CoffeeScript-Support) might even make such an approach gain attractiveness. Currently a spray-based web development stack might consist of (a subset of) these