pvillega / finch-template

A template project for Finch-based services.

Finch HTTP Service Template

This is a template for a simple, stateless HTTP API built on top of Finch. It aims to provide a simple, consistent, beginner- to intermediate-level stack, aimed at getting a small HTTP-based service up & running quickly with some things we care about in a production system.

It aims to provide:

• A HTTP stack, using Finch;
• Authentication support using Hawk, a HMAC-style protocol;
• JSON encoding & decoding, using Circe, including reasonable error handling;
• Clients for talking to downstream services using Featherbed;
• Logging to syslog;
• Metrics support using ...;
• Monitoring via New Relic;
• Error reporting to Rollbar
• Tracing with Zipkin;
• Testing using specs2 & ScalaCheck;
• Packaging using SBT Native Packager.

Further Reading

Here's some further reading on how this hangs together, and how to do more/extend.

• Finch best practices
• Finagle 101
• Finch 101
• Getting started with Finagle
• An introduction to Finagle
• Cats documentation
• Herding Cats - an introduction/tutorial on Cats

TODO List

• Deployment
• Syslog logging
• Metrics
  • Bridging Finagle metrics to Dropwizard Metrics - https://github.com/rlazoti/finagle-metrics & http://rodrigolazoti.com.br/2015/01/08/send-finagle-stats-to-codahale-metrics-library
  • Dropwizard metrics in scala - https://github.com/erikvanoosten/metrics-scala
  • Keen - https://github.com/keenlabs/KeenClient-Scala/
• Authentication
  • Server-Authorization header on responses.
• Downstream client calls to: https://developer.github.com/v3/
• Zipkin

Customising

1. Take a clone.

2. Customise Config:

3. Put your keys (or a reference to how they're found, e.g. via environment variables) in.

4. Modify any of the values you wish, such as the port or system name.

5. Go nuts.

API

There is simple API documentation.

Setup

Development Setup

1. Install Java 1.8 from Oracle. You will need a JDK (not a JRE), as of the time of writing this is "Java SE Development Kit 8u92". There is also documentation available (handy for linking into your IDE).

2. Run sbt::

   $ ./sbt
   > update
   

   Note. You could also brew install sbt if you'd prefer a system version.

3. etc/dot-env contains a template .env file that you can use to configure your environment variables locally:

   $ cp etc/dot-env .env

See sbt-dotenv for more information. Do not check .env into source control!.

Note that if you change this while an sbt session is running, you will need to reload sbt for the new settings to take effect (as it's an sbt plugin).

Deployment Setup

TODO

Running

To run using sbt:

$ ./sbt run

You can also use Revolver for restarts when code changes:

$ ./sbt ~re-start

Testing

$ ./sbt test

This will start the sbt REPL, from where you can issue commands.

• test - Runs all tests, use this to check your exercises;
• test-only workshop.exercises.scalatest.Exercise01 - Runs a single test;
• test-only workshop.exercises.* - Runs all tests in the workshop.exercises package;
• test:compile - Compiles your test code.

Appending a ~ to the start of any command will run it continuously; for example to run tests continuously:

> ~test

Deployment

$ sbt stage

TODO

Uninstall

You can uninstall everything you installed for this project by:

$ rm -rf ~/.sbt
$ rm -rf ~/.ivy2

Then, if you want, you can uninstall Java by following the instructions here: https://docs.oracle.com/javase/8/docs/technotes/guides/install/mac_jdk.html#A1096903