finagle/finch

Scala combinator library for building Finagle HTTP services

Source code at GitHub https://finagle.github.io/finch

{
  "createdAt": "2014-04-15T12:17:44Z",
  "defaultBranch": "master",
  "description": "Scala combinator library for building Finagle HTTP services",
  "fullName": "finagle/finch",
  "homepage": "https://finagle.github.io/finch",
  "language": "Scala",
  "name": "finch",
  "pushedAt": "2025-09-14T13:16:16Z",
  "stargazersCount": 1605,
  "topics": [
    "circe",
    "finagle",
    "finch",
    "http",
    "json",
    "rest",
    "scala",
    "web"
  ],
  "updatedAt": "2025-10-13T05:26:02Z",
  "url": "https://github.com/finagle/finch"
}

Finch is a thin layer of purely functional basic blocks atop of [Finagle][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.

[!WARNING]
Finch is no longer maintained because Finagle is no longer maintained: twitter/finagle#943.

For an alternative purely functional HTTP server in Scala, take a look at http4s.

Badges

Standard Modules

Finch uses multi-project structure and contains of the following modules:

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

Additional Modules

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

[finch-jackson][finch-jackson] - [Jackson][jackson] + Finch
[finch-json4s][finch-json4s] - [JSON4s][json4s] + Finch
[finch-playjson][finch-playjson] - [PlayJson][playjson] + Finch
[finch-sprayjson][finch-sprayjson] - [SprayJson][sprayjson] + Finch
[finch-oauth2][finch-oauth2] - [Finagle OAuth2][finagle-oauth2] + Finch

Installation

Every Finch module is published at Maven Central. Use the following sbt snippet …

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

Hello World!

This “Hello World!” example is built with just finch-core:

import cats.effect.{IO, IOApp}
import io.finch._

object Main extends IOApp.Simple with Endpoint.Module[IO] {
  override def run: IO[Unit] = {
    val api: Endpoint[IO, String] = get("hello") { Ok("Hello, World!") }
    Bootstrap[IO].serve[Text.Plain]!(api).listen(":8080").useForever
  }
}

See [examples]!(examples/src/main/scala/io/finch) sub-project for more complete examples.

Quickstart

Use [finch.g8][finch.g8] template to quickly bootstrap a minimal Finch project:

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

Performance

We use [wrk][wrk] to load test [Finch+Circe][finch-bench] against [Finagle+Jackson][finagle-bench] 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][tempower]. The most recent round showed that Finch performs really well there, [scoring a second place][finch-is-fast] across all the Scala libraries.

Documentation

The main documentation is hosted at http://finagle.github.io/finch/
The documentation source may be found in the [docs/]!(docs/) folder
The latest Scaladoc is available at http://finagle.github.io/finch/api/

Adopters

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 the [finagle-oauth2][finagle-oauth2] library
Finch Todo Backend: Finch implementation of todobackend

Contributing

There are plenty of ways to contribute into Finch:

Give it a star
Join the [Gitter][gitter] room and leave a feedback or help with answering users’ questions
[Submit a PR]!(CONTRIBUTING.md) (there is an issue label “easy” for newcomers)
Be cool and wear a Finch T-Shirt

The Finch project supports the [Typelevel][typelevel] [code of conduct][conduct] and wants all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.

Finch is currently maintained by [Vladimir Kostyukov][vkostyukov], [Travis Brown][travisbrown], [Ryan Plessner][ryan_plessner], and [Sergey Kolbasov][sergey_kolbasov]. After the 1.0 release, all pull requests will require two sign-offs by a maintainer to be merged.

License

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.