Finagle: Twitter's Fault-Tolerant RPC System for the JVM

What Finagle Is and the Problem It Solves

Finagle is an RPC system for the JVM developed at Twitter and released under the Apache-2.0 license. Its README describes it as extensible, protocol-agnostic, and designed for high-concurrency servers. The core observation behind Finagle is that most of what makes distributed systems hard (retries, timeouts, load balancing, circuit breaking, tracing, metrics) is independent of the protocol used. Finagle separates that cross-cutting infrastructure from the protocol-specific details.

The README states that Finagle is used in production at Twitter and at several other organizations including Foursquare, ING Bank, Pinterest, SoundCloud, and Tumblr. A more complete adopter list is maintained in the ADOPTERS.md file on the release branch. The project is based on the JVM, written primarily in Scala, and has been in active development since 2010.

Protocol Support: HTTP, Thrift, ThriftMux, and More

Finagle's repository is organized as a set of independent modules. The top-level directory lists the following modules: finagle-core, finagle-http, finagle-http2, finagle-thrift, finagle-thriftmux, finagle-mysql, finagle-redis, finagle-memcached, finagle-postgresql, finagle-netty4, finagle-netty4-http, finagle-mux, finagle-grpc-context, finagle-scribe, finagle-serversets, finagle-stats, finagle-logging, finagle-zipkin-core, finagle-zipkin-scribe, and several others.

The most commonly used modules are finagle-http and finagle-thrift. ThriftMux is a multiplexing Thrift protocol that runs multiple Thrift sessions over a single TCP connection. finagle-grpc-context provides context propagation for gRPC rather than a full gRPC server implementation. The finagle-mux module implements Mux, a session-layer multiplexing protocol developed by Twitter.

Each module publishes separately to Maven Central. The badge in the README links to the Maven Central listing at the coordinate com.twitter/finagle-core_2.12, which is the Scala 2.12 build of the core module.

Core Abstractions: Future, Service, and Filter

The Finagle programming model is built on three abstractions. A Future represents an asynchronous computation that will eventually produce a value or fail. All Finagle operations return futures, and composition of futures is the primary way to build request pipelines.

A Service is a function from a request to a future of a response. Both clients and servers implement the Service interface, which makes it possible to use the same combinators on both sides. A client makes an outbound call; a server handles an inbound one; the interface is the same.

A Filter wraps a Service, allowing middleware to be composed around a service without modifying it. Retry logic, timeout enforcement, authentication, and metrics collection are all implementable as Filters. Filters are composable and can be stacked, which is how Finagle's built-in resilience features are attached to services without changing the service's code. The user guide and API documentation at https://twitter.github.io/finagle/ provide extensive documentation on these abstractions.

Adding Finagle to a Scala Project

Finagle is distributed through Maven Central. The project uses SBT (Scala Build Tool) as its own build system, as indicated by the build.sbt in the repository root. To add the HTTP module to an SBT project, you add the finagle-http artifact as a library dependency in build.sbt. To add the Thrift module, you add finagle-thrift.

The README points to the user guide at https://twitter.github.io/finagle/guide/ as the primary resource for getting started. The API documentation is at https://twitter.github.io/finagle/docs/com/twitter/finagle. The CHANGELOG.rst file in the repository root documents public API breaks and changes in runtime behavior for each release; the README explicitly states that the changelogs are detailed and include sections on breaking changes.

The repository publishes releases approximately monthly. Weekly snapshots are published to the develop branch. The release branch holds the latest stable release.

Load Balancing, Retries, and Circuit Breaking

Finagle's load balancing, retry policy, and circuit breaking are implemented as Filters and are part of the standard client stack. A Finagle client automatically balances load across available service instances. When a call fails, the retry policy (configurable per client) determines whether to retry and how many times. Circuit breaking prevents a cascade failure by temporarily stopping requests to an endpoint that has been returning errors.

The finagle-core module contains the client stack and these cross-cutting behaviors. Most of the code in the repository is protocol-agnostic and lives in finagle-core, as the README states: "Most of Finagle's code is protocol agnostic, simplifying the implementation of new protocols."

Metrics are collected through finagle-stats, which integrates with Twitter's Metrics library. Distributed tracing is available through finagle-zipkin-core and finagle-zipkin-scribe for systems that use Zipkin. The finagle-opencensus-tracing module handles OpenCensus integration.

What Finagle Does Not Cover

Finagle is an RPC framework, not a service mesh. It does not run a sidecar proxy alongside your services. All the load balancing and circuit breaking logic runs in-process within each Finagle client. Migrating to a sidecar model (such as Envoy or Linkerd) means moving that logic out of the application code.

Finagle is written in Scala for the JVM. There is no official port to other runtimes. Teams building services in Go, Python, or Node.js cannot use Finagle directly.

The latest GitHub release is finagle-24.5.0 from 2024-05-07. This does not mean the project is unmaintained; the README states it is actively developed and used in production, and the last push to the repository was on 2026-08-13. But the gap between the latest formal release and the current develop branch means users must decide between the stable 2024 release and the develop branch snapshots.

The build process requires SBT and a compatible Scala version. The repository uses a custom sbt launcher script (./sbt) and the project/plugins.sbt defines the build plugins. For contributors, the Bazel BUILD.bazel file exists alongside the SBT build, indicating dual build system support.

Finagle versus gRPC for JVM Services

gRPC with the grpc-java library is the most common alternative for JVM teams building high-concurrency RPC services today. gRPC is backed by the CNCF, uses Protocol Buffers for serialization, and has first-class support in most languages.

Finagle predates gRPC and takes a different architecture. Where gRPC defines a specific wire protocol (HTTP/2 with Protocol Buffers), Finagle is protocol-agnostic and can run over HTTP, Thrift, ThriftMux, or Mux. The finagle-grpc-context module provides context propagation for systems that interact with gRPC services but does not provide a full gRPC server or client implementation.

For a new service that will communicate primarily with other gRPC services, grpc-java is the simpler choice. For a system already built on Finagle, or for a service that needs to speak multiple protocols (ThriftMux internally and HTTP externally), Finagle's protocol-agnostic model avoids running separate client stacks for each protocol.

License, Community, and Maintenance

Finagle is licensed under the Apache-2.0 license. Copyright is held by Twitter, Inc., as of 2010. The full license text is at https://www.apache.org/licenses/LICENSE-2.0.

The project maintains a mailing list at [email protected] and a Gitter chat room. A blog is hosted at https://finagle.github.io/blog/. The CODE_OF_CONDUCT.md references Twitter's Open Source Code of Conduct. Contributing is documented in CONTRIBUTING.md on the release branch; pull requests should be submitted against the develop branch.

The CHANGELOG.rst is the authoritative record of changes. The README states that changelogs include sections on public API breaks and changes in runtime behavior, which is relevant for any upgrade. The last push to the repository was on 2026-08-13. The repository also includes a CONTRIBUTORS file and a .mailmap for identity normalization across the commit history.

Editorial conclusion

Finagle is appropriate for Scala teams building high-concurrency JVM services that need protocol-agnostic load balancing, retries, and circuit breaking without wiring them separately. It is not appropriate for teams outside the JVM ecosystem or for small services where the Scala dependency and the complexity of the Future/Service/Filter model are disproportionate to the problem. The latest GitHub release is finagle-24.5.0 from May 2024; the repository received a push on 2026-08-13, so the codebase is under active development beyond the most recent public release. Evaluate against the weekly develop branch snapshots if you need changes not in the May 2024 release.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. twitter/finagle on GitHub