Chaos

A lightweight framework for writing REST services in Scala.

Chaos (Greek χάος, khaos) refers to the formless or void state preceding the creation of the universe or cosmos in the Greek creation myths. Chaos (the framework) precedes creation of a universe of services.

Why yet another framework?

At Mesosphere we're building REST services in Scala, and we wanted a solid foundation. We had experience with Dropwizard and Twitter Commons, which are both great Java frameworks, but are a bit hard to use from Scala. We also experimented with Play!, but it does many things besides REST, which adds unnecessary baggage.

Design Goals

We wanted a framework that

is easy to use
does one thing really well (REST)
feels good in Scala
is built on battle-tested and well-supported libraries
doesn't try to reinvent the wheel

Building Blocks

There are great JVM libraries for every part of a REST stack. Chaos just glues these together.

Jersey for REST via annotations
Guava for lifecycle management and various utilities
Jetty as the web server and servlet container
Jackson for JSON support
Coda Hale's Metrics for JVM and application metrics

Getting Started

Requirements

JDK 1.8+
SBT 0.13.x+

Example App

There is an example app in [src/main/scala/mesosphere/chaos-examples/] (https://github.com/mesosphere/chaos/blob/master/chaos-examples/src/main/scala/mesosphere/chaos/examples/Main.scala). To run the example:

sbt run

Make requests to the example endpoints with HTTPie:

http localhost:8080/persons
http localhost:8080/persons name=Bunny age=42

Built in Endpoints

/ping - health check.
/metrics - metrics as JSON
/logging - configure log levels at runtime

Using Chaos in your Project

Chaos releases are available from Mesosphere's Maven repository.

Maven

To add Chaos to a Maven project, add this to your pom.xml:

<properties>
    <chaos.version>0.5.2</chaos.version>
</properties>

...

<repositories>
    <repository>
        <id>mesosphere-public-repo</id>
        <name>Mesosphere Public Repo</name>
        <url>http://downloads.mesosphere.io/maven</url>
    </repository>
</repositories>

...

<dependencies>
    <dependency>
        <groupId>mesosphere</groupId>
        <artifactId>chaos</artifactId>
        <version>${chaos.version}</version>
    </dependency>
</dependencies>

SBT

To add Chaos to an SBT project, add this to your build.sbt:

resolvers += "Mesosphere Public Repo" at "http://downloads.mesosphere.io/maven"

libraryDependencies ++= Seq(
  "mesosphere" % "chaos" % "0.5.2",
  "com.sun.jersey" % "jersey-bundle" % "1.17.1"
)

Getting Help

If you have questions, please post on the Chaos Users Group email list. The team at Mesosphere is also happy to answer any questions.

Authors

Current Users

Chronos, a fault tolerant job scheduler that handles dependencies and ISO8601 based schedules.

mesosphere / chaos

readme