Finch is a thin layer of purely functional basic blocks atop of Finagle for building composable HTTP APIs. Its mission is to provide the developers simple and robust HTTP primitives being as close as possible to the bare metal Finagle API.
Finch uses multi-project structure and contains of the following modules:
finch-core- the core classes/functionsfinch-generic- generic derivation for endpointsfinch-argonaut- the JSON API support for the Argonaut libraryfinch-jackson- the JSON API support for the Jackson libraryfinch-json4s- the JSON API support for the JSON4S libraryfinch-circe- the JSON API support for the Circe libraryfinch-playjson- The JSON API support for the PlayJson libraryfinch-sprayjson- The JSON API support for the SprayJson libraryfinch-test- the test support classes/functionsfinch-oauth2- the OAuth2 support backed by the finagle-oauth2 libraryfinch-sse- SSE (Server Sent Events) support in Finch
Every Finch module is published at Maven Central. Use the following sbt snippet ...
- for the stable release:
libraryDependencies ++= Seq(
"com.github.finagle" %% "[finch-module]" % "0.16.0-M6"
)- for the
SNAPSHOTversion:
resolvers += Resolver.sonatypeRepo("snapshots")
libraryDependencies ++= Seq(
"com.github.finagle" %% "[finch-module]" % "0.16.0-SNAPSHOT" changing()
)This "Hello World!" example is built with the 0.16.0 version of just finch-core.
import io.finch._
import io.finch.syntax._
import com.twitter.finagle.Http
val api: Endpoint[String] = get("hello") { Ok("Hello, World!") }
Http.server.serve(":8080", api.toServiceAs[Text.Plain])See examples sub-project for more complete examples.
We use wrk to load test Finch+Circe against Finagle+Jackson to get some insight on how much overhead, an idiomatic Finch application written in a purely functional way, involves on top of Finagle/Jackson. The results are quite impressive (for a pre-1.0 version): Finch performs on 95% of Finagle's throughput.
Here is the first three runs of the benchmark on 2013 MB Pro (2.8 GHz Intel Core i7 w/ 16G RAM).
| Benchmark | Run 1 | Run 2 | Run 3 |
|---|---|---|---|
| Finagle + Jackson | 29014.68 req/s | 36783.21 req/s | 39924.42 req/s |
| Finch + Circe | 28762.84 req/s | 36876.30 req/s | 37447.52 req/s |
Finch is also load tested against a number of Scala HTTP frameworks and libraries as part of the TechEmpower benchmark. The most recent round showed that Finch performs really well there, scoring a second place across all the Scala libraries.
- The main documentation is hosted at http://finagle.github.io/finch/
- The documentation source may be found in the
docs/folder - The latest Scaladoc is available at http://finagle.github.io/finch/api/
- Despegar
- Earnest
- Globo.com
- Glopart
- Hotel Urbano
- Konfettin
- JusBrasil
- Sabre Labs
- Spright
- SoFi
- Qubit
- QuizUp
- Lookout
- Project September
- Sigma
- D.A.Consortium
- Redbubble
- Zalando
- Rakuten
- Threat Stack
- RelinkLabs
- Submit a pull-request to include your company/project into the list
- Finch Template: A Redbubble approach to building services with Finch
- Finch Server: Finch's integration into TwitterServer
- Finch Sangria: Finch's GraphQL support
- Finch Demo: Community-maintained Finch user guide
- Finch Rich: Macro-based controllers for Finch
- Finch Quckstart: A skeleton Finch project
There are plenty of ways to contribute into Finch:
- Give it a star
- Join the Gitter room and leave a feedback or help with answering users' questions
- Submit a PR (there is an issue label "easy" for newcomers)
- Be cool and wear a Finch T-Shirt
The Finch project supports the Typelevel code of conduct and wants all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.
Finch is currently maintained by Vladimir Kostyukov, Travis Brown, and Ryan Plessner. After the 1.0 release, all pull requests will require two sign-offs by a maintainer to be merged.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.