Repository files navigation

Finch is a thin layer of purely functional basic blocks atop ofFinagle forbuilding composable HTTP APIs. Its mission is to provide the developers simple and robust HTTP primitives being asclose as possible to the bare metal Finagle API.

Finch uses multi-project structure and contains of the followingmodules:

• finch-core - core classes/functions
• finch-generic - generic derivation for endpoints
• finch-argonaut -Argonaut + Finch
• finch-circe -Circe + Finch
• finch-iteratee -Iteratee + Finch
• finch-fs2 -FS2 + Finch
• finch-refined -Refined + Finch
• finch-test - the test support classes/functions

Finch's Github organization has even more modules (these are, however, not published regularly;reach out if you need published artifacts):

• finch-jackson -Jackson + Finch
• finch-json4s -JSON4s + Finch
• finch-playjson -PlayJson + Finch
• finch-sprayjson -SprayJson + Finch
• finch-oauth2 -Finagle OAuth2 + Finch

Every Finch module is published at Maven Central. Use the followingsbt snippet ...

libraryDependencies++=Seq("com.github.finagle"%%"[finch-module]"%"[version]")

This "Hello World!" example is built with justfinch-core:

importcats.effect.{IO,IOApp}importio.finch._objectMainextendsIOApp.SimplewithEndpoint.Module[IO] {overridedefrun:IO[Unit]= {valapi:Endpoint[IO,String]= get("hello") {Ok("Hello, World!") }Bootstrap[IO].serve[Text.Plain](api).listen(":8080").useForever  }}

Seeexamples sub-project for more complete examples.

Usefinch.g8 template to quickly bootstrap a minimal Finch project:

• sbt new finch/finch.g8
• cd helloworld
• sbt run
• curl http://localhost:8081/hello

We usewrk to load testFinch+Circe againstFinagle+Jacksonto get some insight on how much overhead, an idiomatic Finch application written in a purelyfunctional way, involves on top of Finagle/Jackson. The results are quite impressive (for a pre-1.0version): Finch performs on95% 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).

Finch is also load tested against a number of Scala HTTP frameworks and libraries as part of theTechEmpower benchmark. The most recent round showed that Finch performs really wellthere,scoring a second place across all the Scala libraries.

• The main documentation is hosted athttp://finagle.github.io/finch/
• The documentation source may be found in thedocs/ folder
• The latest Scaladoc is available athttp://finagle.github.io/finch/api/

• PITS Global Data Recovery Services
• Despegar
• Earnest
• Globo.com
• Glopart
• Hotel Urbano
• Konfettin
• JusBrasil
• Sabre Labs
• Spright
• SoFi
• Qubit
• QuizUp
• Lookout
• Project September
• Merit
• 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 Quickstart: A skeleton Finch project
• Finch OAuth2: the OAuth2 support backed by thefinagle-oauth2 library
• Finch Todo Backend: Finch implementation oftodobackend

There are plenty of ways to contribute into Finch:

• Give it a star
• Join theGitter 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 aFinch T-Shirt

The Finch project supports theTypelevelcode of conduct and wants all of its channels(Gitter, GitHub, etc.) to be welcoming environments for everyone.

Finch is currently maintained byVladimir Kostyukov,Travis Brown,Ryan Plessner, andSergey Kolbasov. After the 1.0 release, allpull requests will require two sign-offs by a maintainer to be merged.

Licensed under theApache 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, softwaredistributed 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 andlimitations under the License.