Finatra

Build Status Test Coverage Project status Maven Central Gitter

Finatra builds on TwitterServer and uses Finagle, therefore it is highly recommended that you familiarize yourself with those frameworks before getting started.

The version of Finatra documented here is version 2.x. Version 2.x is a complete rewrite over v1.x and as such many things are different.

For high-level information about the changes from v1.x see the blog post here.

Finatra at its core is agnostic to the type of service or application being created. It can be used to build anything based on TwitterUtil: c.t.app.App.

For servers, Finatra builds on top of the features of TwitterServer (and Finagle) by allowing you to easily define a Server and controllers (a Service-like abstraction) which define and handle endpoints of the Server. You can also compose Filters either per controller, per route in a controller, or across all controllers.

Getting Started

To get started, add a dependency on either finatra-http or finatra-thrift depending if you are building an HTTP or Thrift server.

E.g., with sbt:

"com.twitter" %% "finatra-http" % "17.11.0"

or

"com.twitter" %% "finatra-thrift" % "17.11.0"

Or similarily with Maven:

<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>finatra-http_2.12</artifactId>
  <version>17.11.0</version>
</dependency>

or

<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>finatra-thrift_2.12</artifactId>
  <version>17.11.0</version>
</dependency>

Note: with Maven, you must append the appropriate scala version to the artifact name (e.g., _2.12).

See the Finatra hello-world example for a more in-depth example.

Test Dependencies

Finatra publishes test-jars for most modules. The test-jars include re-usable utilities for use in testing (e.g., the EmbeddedTwitterServer).

To add a test-jar dependency, depend on the appropriate module with the tests classifier. Additionally, these dependencies are typically only needed in the test scope for your project. E.g., with sbt:

"com.twitter" %% "finatra-http" % "17.11.0" % "test" classifier "tests"

or

"com.twitter" %% "finatra-thrift" % "17.11.0" % "test" classifier "tests"

See the sbt documentation for more information on using ivy configurations and classifiers.

And with Maven:

<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>finatra-http_2.12</artifactId>
  <scope>test</scope>
  <type>test-jar</type>
  <version>17.11.0</version>
</dependency>

or

<dependency>
  <groupId>com.twitter</groupId>
  <artifactId>finatra-thrift_2.12</artifactId>
  <scope>test</scope>
  <type>test-jar</type>
  <version>17.11.0</version>
</dependency>

There is a downside to publishing test-jars in this manner: transitive test-scoped dependencies are not resolved. Maven and sbt only resolve compile-time dependencies transitively, so you will need to specify all other required test-scoped dependencies manually.

For example, the finatra-http test-jar depends on the inject-app test-jar (among others). You will have to manually add a dependency on the inject-app test-jar when using the finatra-http test-jar since the inject-app test-jar will not be resolvedtransitively.

Using the sbt-dependency-graph plugin, you can list the dependencies of the finatra-http test configuration for the packageBin task:

$ ./sbt -Dsbt.log.noformat=true http/test:packageBin::dependencyList 2>&1 | grep 'com\.twitter:finatra\|com\.twitter:inject'
[info] com.twitter:finatra-http_2.12:...
[info] com.twitter:finatra-httpclient_2.12:...
[info] com.twitter:finatra-jackson_2.12:...
[info] com.twitter:finatra-slf4j_2.12:...
[info] com.twitter:finatra-utils_2.12:...
[info] com.twitter:inject-app_2.12:...
[info] com.twitter:inject-core_2.12:...
[info] com.twitter:inject-modules_2.12:...
[info] com.twitter:inject-request-scope_2.12:...
[info] com.twitter:inject-server_2.12:...
[info] com.twitter:inject-slf4j_2.12:...
[info] com.twitter:inject-utils_2.12:...

In this case, when executing the packageBin task for finatra-http in the test configuration these dependencies are necessary. Unfortunately, this listing does not explicity state if it’s the compile-time or the test-jar version of the dependency that is necessary. However, it is safe to assume that if you want a dependency on the finatra-http test-jar you will also need to add dependencies on any test-jar from the listed dependencies as well.

To continue getting started, please see the Finatra User’s Guide.

Contributing

Finatra is an open source project that welcomes contributions from the greater community. We’re thankful for the many people who have already contributed and if you’re interested, please read the contributing guidelines.

For support feel free to follow and/or tweet at the @finatra Twitter account, post questions to the Gitter chat room, or email the finatra-users Google group: finatra-users@googlegroups.com.