kryndex / finatra

Fast, testable, Scala services built on Twitter-Server and Finagle

Finatra

Status

This project is used in production at Twitter (and many other organizations), and is being actively developed and maintained.

Finatra is a lightweight framework for building fast, testable, scala applications on top of TwitterServer and Finagle. Finatra provides an easy-to-use API for creating and testing Finagle servers and apps as well as powerful JSON support, modern logging via SLF4J, Finagle client utilities, and more.

Getting involved

• Website: https://twitter.github.io/finatra/
• Latest news: Blog
• Github Source: https://github.com/twitter/finatra/
• Gitter: https://gitter.im/twitter/finatra
• Mailing List: [email protected]

Features

• Production use @Twitter.
• ~50 times faster than v1.6 in several benchmarks.
• Powerful Feature and Integration test support.
• Optional JSR-330 Dependency Injection using Google Guice.
• Jackson-based JSON parsing supporting required fields, default values, and validations.
• Logback MDC integration with com.twitter.util.Local for contextual logging across futures.

Documentation

To get started, see the Getting Started section of our User Guide to get up and running. Or check out the specific sections for building HTTP or Thrift servers.

Examples

An HTTP controller and server:

import com.twitter.finatra.http._

@Singleton
class ExampleController extends Controller {
  get("/") { request: Request =>
    "<h1>Hello, world!</h1>"
  }
}

import com.twitter.finatra.http._

class ExampleServer extends HttpServer {
  override def configureHttp(router: HttpRouter): Unit = {
    router
      .filter[CommonFilters]
      .add[ExampleController]
  }
}

A Thrift controller and server:

import com.twitter.finatra.thrift._

@Singleton
class ExampleThriftController 
  extends Controller
  with MyThriftService.BaseServiceIface {
  
  override val myFunction = handle(MyFunction) { args: MyFunction.Args =>
    ...
  }
}

import com.twitter.finatra.thrift._

class ExampleServer extends ThriftServer {
  override def configureThrift(router: ThriftRouter): Unit = {
    router
      .add[ExampleThriftController]
  }
}

Example Projects

Finatra includes working examples which highlight various features of the framework and include tests. In the develop branch these examples are included in the root sbt build and are thus buildable as part of the entire project. In the master branch (or a release branch) these examples can be built using their invididual sbt (or Maven) build files.

Please take a look through the examples for more detailed information on features, testing, and building with sbt (or Maven).

Latest version

The master branch in Github tracks the latest stable release, which is currently:

available on Maven Central. See the First Steps section in the User Guide for how to add dependencies.

Releases are done on an approximately monthly schedule. While semver is not followed, the changelogs are detailed and include sections on public API breaks and changes in runtime behavior.

Development version

The develop branch in Github tracks the latest code which is updated every week. If you want to contribute a patch or fix, please use this branch as the basis of your Pull Request.

For more information on providing contributions, please see our CONTRIBUTING.md documentation.

Presentations

Check out our list of presentations: Finatra Presentations.

Authors

• Steve Cosenza https://github.com/scosenza
• Christopher Coco https://github.com/cacoco

A full list of contributors can be found on GitHub.

Follow @finatra on Twitter for updates.

License

Copyright 2013-2017 Twitter, Inc.

Licensed under the Apache License, Version 2.0: https://www.apache.org/licenses/LICENSE-2.0