twitter/finatra

Finatra is an open-source framework for building high-performance HTTP and Thrift servers in Scala and Java, built on top of Finagle. It provides a structured approach to service development through dependency injection, automatic routing, and comprehensive request handling features such as JSON marshalling, file uploads, and streaming. The system supports advanced operational needs including dark traffic testing, request-scoped contexts, and detailed observability via metrics and distributed tracing.

36 changes.

This period marks the initial open-source release of Finatra, accompanied by a migration from Maven to SBT and the extraction of core dependency injection abstractions into the inject-core module. Significant work focused on enhancing Java interoperability, introducing request-scoped injection for Finagle services, and expanding the library with utilities for Thrift, HTTP, and metrics. The effort also established a robust testing infrastructure, including embedded server utilities and comprehensive coverage for the new inject and Thrift components.

36 changes.

This period focused on modernizing the Finatra Thrift integration by deprecating legacy filtering patterns and introducing Java-friendly server traits and type-agnostic filters. Significant enhancements were made to the inject-thrift-client module, including per-endpoint configuration, dark traffic sampling, and improved observability through detailed metrics and exception handling. The work also established robust infrastructure for exception mapping, server warmup, and comprehensive test coverage for both Scala and Java implementations.

47 changes.

This period focused on expanding the Finatra and Inject frameworks with new features such as Mustache template rendering, dark traffic filtering for Thrift clients, and Finagle-aware MDC logging. Significant effort was also dedicated to modernizing the build infrastructure by migrating examples and modules to Bazel, while simultaneously deprecating legacy validation components in favor of standard bean validation.

25 changes.

This period focused on restructuring the Finatra HTTP ecosystem by extracting core functionalities—such as routing, marshalling, exception handling, and streaming—into a dedicated http-core module to improve dependency isolation. The work also introduced new modules for HTTP clients and MySQL integration, while enhancing Java interoperability and establishing comprehensive test coverage across the reorganized components.

Users can now use the new @FinagleRequestScoped annotation to scope Guice bindings to the Finagle request lifecycle. This change introduces the FinagleRequestScoped.java annotation class and the corresponding Bazel BUILD file (inject-request-scope-java) that packages this functionality, depending on Guice and marked as Bazel-compatible.

inject/inject-request-scope/src/main/java · high confidence

The examples/benchmark directory now includes a runnable benchmark server implementation (FinatraBenchmarkServer) that serves JSON and plaintext endpoints, along with a local benchmarking script (local\_benchmark.sh) and README documentation. This addition is accompanied by Bazel build files for both main and test sources, and a feature test (BenchmarkFeatureTest) that validates the behavior of both the Finatra and Finagle benchmark server implementations.

examples/benchmark · high confidence

The advanced web-dashboard example now includes a complete Finatra HTTP server implementation, featuring a DashboardController with endpoints for health checks (/ping), static HTML pages (/other, /subdirectory2), and Mustache-rendered user views (/user). The example is fully integrated with the Bazel build system, with BUILD.bazel files added for Scala sources, resources, web assets, and tests, replacing the previous build configuration. It also includes a Logback configuration for logging and a Bootstrap-based frontend.

examples/advanced/web-dashboard · high confidence

The documentation build now includes a new 'flask' Sphinx theme (with a 'flask\_small' variant) that provides a distinct visual style, including a 'Fork me on GitHub' ribbon, specific typography, and mobile-responsive layouts. Additionally, a utility script for extracting library versions from SBT build files has been added to support documentation generation workflows.

_doc/src/sphinx/\themes, doc/src/sphinx/utils · high confidence

This change introduces a new Java-based example for the Injectable Twitter Server, demonstrating how to configure and run a server using Guice and Twitter's inject framework. The example includes the main server class, a queue module for dependency injection, and a Logback configuration for logging. It is fully integrated into the Bazel build system with new BUILD.bazel files for the main source, resources, and tests. Additionally, feature and startup tests are added to verify the server's health and queue processing behavior using EmbeddedTwitterServer.

examples/http-server/scala, examples/injectable-twitter-server/java · high confidence

A new MergedFilter class is introduced in the finatra-utils-filters module, allowing users to combine multiple Finagle filters into a single filter instance. This utility simplifies filter composition by chaining provided filters together, making it easier to manage complex filter pipelines in Finatra applications.

utils/src/main/scala/com/twitter/finatra/filters · high confidence

This change introduces a new integration between Finatra's HTTP layer and the Mustache templating engine. Users can now annotate controller method parameters with \@Mustache\ to specify a template name and content type, enabling automatic rendering of Mustache templates as HTTP responses. The implementation includes a \MustacheMessageBodyWriter\ to handle the serialization, a \MustacheTemplateLookup\ to resolve template details from annotations, and a \RichEnrichedResponse\ extension that provides a convenient \view\ method on responses for rendering templates directly. A \MustacheModule\ is provided to wire these components into the dependency injection container.

http-mustache/src/main · high confidence

The new \PossiblyRetryable\ object in \com.twitter.inject.exceptions\ provides a \ResponseClassifier\ and helper methods to determine if a Thrift request failure is potentially retryable. It classifies responses as retryable only when the exception is non-fatal, not a cancellation, and not explicitly marked as non-retryable, allowing applications to automatically retry transient Thrift errors while avoiding retries on fatal or cancelled requests.

inject/inject-thrift/src/main/scala/com/twitter/inject/exceptions · high confidence

A new Scala-based example application is added to the examples/injectable-app/scala directory, demonstrating how to build a Finatra app with dependency injection. The example includes a sample service (HelloService), a main application class (SampleApp) that uses flags and logging, and corresponding Bazel build files (BUILD.bazel) for both the main source and test targets. It also provides a feature test (HelloWorldAppFeatureTest) that verifies the application lifecycle and flag handling using EmbeddedApp.

examples/injectable-app/scala · high confidence

This location introduces a new Scala example for the injectable Twitter Server, demonstrating a pub-sub pattern using a Publisher and Subscriber component connected via a configurable Queue. The example includes a main server class (ExampleTwitterServer) that manages the lifecycle of these components, along with dependency injection modules (QueueModule) and configuration flags. Additionally, the build system has been migrated from the legacy BUILD files to BUILD.bazel, and a logback.xml configuration has been added to handle logging output.

examples/injectable-twitter-server/scala/src/main · high confidence

Finatra Thrift now includes an exception mapping system that allows users to register custom mappers for specific exception types. The new \ExceptionMapper\ abstract class defines the interface for converting a throwable into a response, while \ExceptionManager\ handles the registration and lookup logic, supporting inheritance-based fallback (e.g., mapping a parent exception class if a specific one is not found). This enables more granular control over how Thrift service exceptions are translated into HTTP or Thrift responses.

thrift/src/main/scala/com/twitter/finatra/thrift/exceptions · high confidence

A new utility object, ThriftMethodUtils, has been added to the inject-thrift module to provide a standardized way to format Thrift RPC method identifiers. It exposes a memoized function that converts a ThriftMethodIface into a human-readable string in the format 'serviceName.methodName', simplifying logging and debugging for users of the inject-thrift integration.

inject/inject-thrift/src/main/scala/com/twitter/inject/thrift · high confidence

A new Sphinx extension, \includecode\, is introduced to allow documentation to include specific sections of external code files. This directive supports filtering content by section markers, including or excluding specific sections, and applying line numbers or language hints, enabling more granular control over code snippets in the generated documentation.

doc/src/sphinx/exts · high confidence

The advanced streaming example now includes a complete Finatra HTTP server demonstrating streaming request and response handling via \Reader\ and \AsyncStream\, along with corresponding integration tests. The example is fully integrated into the Bazel build system with new \BUILD.bazel\ files for resources, Scala sources, and tests, and includes a \logback.xml\ configuration for logging.

examples/advanced/streaming-example · high confidence

The inject-thrift-client module now includes a DarkTrafficFilter, enabling users to route a sampled subset of requests to a secondary 'dark' service for testing or analysis without affecting the primary service's response. This filter supports both Scala and Java Thrift clients, allows configuration for concurrent or post-processing forwarding, and handles method name resolution (including inherited methods and snake\_case to camelCase conversion) to correctly identify the target dark service implementation.

inject/inject-thrift-client/src/main/scala/com/twitter/inject/thrift/filters · high confidence

The inject-dtab module now provides a DtabResolution trait that allows applications to apply supplemental delegation tables via the finagle DtabFlags. When mixed into an App, this trait automatically applies any additional dtab entries during the premain phase and logs the installed delegation table entries for visibility.

inject/inject-dtab · high confidence

The inject-logback module now provides a custom AsyncAppender that extends Logback's core implementation to automatically register debug metrics. Upon startup, the appender exposes gauges for queue size, discarding threshold, max flush time, and current queue depth, while also tracking discarded events via counters. Additionally, it registers configuration details such as max queue size, discarding threshold, and included appenders into the library registry for easier observability.

inject/inject-logback/src/main/scala/ch · high confidence

The inject-server now registers a new Finagle metrics gauge named \finagle/build/revision\. This gauge exposes the current Finagle build revision as a numeric value, allowing users to monitor which version of Finagle is running in their application. If the revision cannot be resolved or converted, a warning or error is logged respectively, and the gauge defaults to -1.

inject/inject-server/src/main/scala/com/twitter/server · high confidence

The \finatra/http-server\ module has been reorganized into distinct Bazel targets (\finatra-http-server\, \finatra-http-controller\, \finatra-http-conversions\) to improve dependency isolation. This change introduces \AbstractController\, an abstract base class for Java users to define routes via a \configureRoutes\ method, enhancing Java interoperability. Additionally, the module now includes \Tls\ trait for simplified HTTPS configuration and new implicit conversion classes (\futureHttp\, \optionHttp\) that provide convenient methods for handling HTTP-specific exceptions and status codes in Scala code.

http-server/src/main/scala/com/twitter/finatra/http · high confidence

Finatra is now available as an open-source project under the Apache License 2.0. This release includes the core framework code, documentation, and a list of adopters (Fitbit, Grovo, Kueski).

(repo-wide) · high confidence

An internal \LibraryModule\ has been added to the \com.twitter.inject.modules.internal\ package, providing a \TwitterModule\ that binds a \Library\ instance by name. This module is exposed for testing purposes and is part of the internal build structure managed by Pants, with strict dependencies enabled and a Java 8 platform target.

inject/inject-modules/src/main/scala/com/twitter/inject/modules/internal · high confidence

Added a new request-scope module that enables Guice-style \@RequestScoped\ injection within Finagle services. This includes a custom \FinagleRequestScope\ implementation backed by Finagle's \LocalContext\, a \FinagleRequestScopeFilter\ (with a \TypeAgnostic\ variant) to initialize and manage the scope per request, and a \TwitterModule\ to wire everything together. Users can now inject request-scoped dependencies that are automatically seeded and isolated per HTTP/Thrift request.

inject/inject-request-scope/src/main/scala/com · high confidence

This change introduces the core HTTP routing infrastructure for Finatra, including the \HttpRouter\ which manages external and admin route services, global filters, and exception mappers. It adds \AdminHttpRouter\ to handle the integration of Finatra routes with the TwitterServer HTTP Admin Interface, including validation against duplicate pre-defined routes and linting for indexable endpoints. The \HttpForward\ class enables programmatic request forwarding with depth limiting, while \HttpWarmup\ provides a mechanism to pre-warm server endpoints. Additionally, the \Registrar\ class registers route metadata into the library registry for introspection.

http-server/src/main/scala/com/twitter/finatra/http/routing · high confidence

This change adds Java-compatible versions of the \@Flag\ and \@Lifecycle\ annotations, along with a \Flags\ utility class for constructing flag keys, enabling Java applications to use the inject framework's flag injection capabilities. It also introduces \AbstractApp\, a Java-friendly base class for \App\ that exposes lifecycle hooks (\onInit\, \preMain\, \postMain\, \onExit\) and flag creation methods, allowing Java users to integrate with the dependency injection and flag parsing system without relying on Scala-specific syntax.

inject/inject-app/src/main · high confidence

The inject-modules library now provides StackClientModuleTrait, a new base trait for configuring generic Finagle StackBasedClients, allowing users to define client-specific modules with customizable timeouts, retry budgets, and monitors. Additionally, LoggerModule, StatsReceiverModule, and TracerModule have been updated to expose a static get() method, improving Java interoperability by allowing Java code to access these singleton module instances directly.

inject/inject-modules/src/main/scala/com · high confidence

A new \StackTransformer\ class has been added to the \inject-stack\ module, allowing plugins to modify Finatra filters before they are applied to controller routes. This component adapts Finagle's stack module system to the Finatra context, enabling more granular control over route-level behavior compared to applying Finagle stack transformers directly. The module is now built using Bazel and targets Java 8.

inject/inject-stack · high confidence

This change introduces the new \finatra-http-core-request\ module, providing core HTTP request artifacts for Finatra. It adds a \RequestBuilder\ class that enables fluent construction of HTTP requests, including support for multipart form-data bodies via \bodyMultipart\. Additionally, it includes \RequestUtils\ for handling request path resolution, content negotiation, and multipart parameter parsing, along with a \ForwardedRequest\ proxy for URI manipulation.

http-core/src/main/scala/com/twitter/finatra/http/request · high confidence

This change introduces the new \finatra-mysql-client\ library, providing a \MysqlClient\ wrapper around Finagle's MySQL client to simplify dependency injection and binding in Finatra applications. It includes \MysqlClientModuleTrait\ for configuring and injecting the client via Guice, along with a \Config\ and \Credentials\ model. Additionally, it adds \finatra-mysql-util\ containing DAO tooling (field extractors, lock helpers) and a \MysqlErrorMapper\ for translating MySQL error codes into typed exceptions. The release also brings a comprehensive test harness (\EmbeddedMysqlServer\) and lifecycle traits (\MysqlTestLifecycle\) to facilitate integration testing with an embedded MySQL instance.

mysql-client · high confidence

A new \inject-ports\ library has been added to the inject module, providing a \Ports\ trait that exposes methods to retrieve the bound ports for HTTP, HTTPS, and Thrift interfaces, along with a \PortUtils\ object for formatting and parsing socket addresses. This change introduces new source files and a Bazel build configuration for the \com.twitter.inject.server\ package, establishing the foundation for port-related functionality within the inject framework.

inject/inject-ports/src/main/scala/com · high confidence

Adds a new marshalling module that enables rendering Mustache templates from the local filesystem. This includes a \MustacheService\ for programmatic template rendering, a \MustacheFactoryBuilder\ to configure template loading and caching behavior, and a \LocalFilesystemMustacheFactory\ that resolves template paths relative to a configured directory using a \FileResolver\. A custom \ScalaObjectHandler\ is also provided to support Scala-specific types like \Future\, \Option\, and collections during template execution.

mustache/src/main/scala/com/twitter/finatra/mustache/marshalling · high confidence

The \finatra/http-client\ module has been introduced (renamed from \finatra/httpclient\) to provide a dedicated HTTP client implementation for Finatra applications. This change adds a new \HttpClient\ class that wraps a Finagle service, supporting configurable retry policies, default headers, and JSON response parsing via Jackson. It also includes a \HttpClientModuleTrait\ for dependency injection, allowing users to easily bind and configure the client within the Finatra injector. Additionally, the legacy \RequestBuilder\ object and class in this package are now deprecated in favor of \com.twitter.finatra.http.request.RequestBuilder\.

http-client/src/main/scala/com · high confidence

Added a new \MustacheFactoryModule\ that integrates the Mustache template engine into Finatra's dependency injection container. This module provides a singleton \MustacheFactory\ instance, configuring template caching behavior based on the \local.doc.root\ flag (disabling cache when set for local development) and allowing users to specify the template directory via the \mustache.templates.dir\ flag.

mustache/src/main/scala/com/twitter/finatra/mustache/modules · high confidence

This release introduces several new example applications to demonstrate Finatra capabilities, including a Twitter clone with validation and Firebase integration, a web dashboard, and Java-based HTTP and Thrift server examples. Additionally, the \finatra/http-core\ module is expanded with new foundational components such as \RouteInfo\ for request context, a comprehensive set of HTTP status exceptions (e.g., \NotFoundException\, \BadRequestException\), JSON Patch support, file upload handling, and a new \MessageBodyManager\ for flexible content marshalling.

repository · high confidence

Added CredentialsModule and FileResolverModule to the Finatra utils modules. CredentialsModule provides a way to load credentials from a file path specified via a flag, supporting both empty (no credentials) and file-based credential loading. FileResolverModule provides a configured FileResolver for serving static files, supporting both classpath resources (via doc.root flag) and local development directories (via local.doc.root flag). Both modules follow the TwitterModule pattern with Java-friendly singleton access via get() method.

utils/src/main/scala/com/twitter/finatra/modules · high confidence

This change introduces a new \finatra-utils-java-annotations\ library containing Guice binding annotations (\CanonicalResourceFilter\, \DarkTrafficFilterType\, \DarkTrafficService\, \Experimental\) to support dark traffic filtering and experimental feature tagging. It also adds a \resources\ build target bundling standard \mime.types\ for content-type identification.

utils/src/main/java · high confidence

The http-server module now includes a suite of new filters: AccessLoggingFilter for standard access logs, ExceptionMappingFilter to convert exceptions into HTTP responses, HttpNackFilter to handle Finagle nacks, HttpResponseFilter to manage Server/Date headers and Location header qualification, LoggingMDCFilter to initialize MDC context, and TraceIdMDCFilter to inject trace IDs into MDC. These filters are bundled in CommonFilters for convenient chaining and are built with strict dependencies enabled for Bazel compatibility.

http-server/src/main/scala/com/twitter/finatra/http/filters · high confidence

The http-server module now includes several new TwitterModule implementations to configure core HTTP behaviors. AccessLogModule binds the CommonLogFormatter for request logging, while HttpResponseClassifierModule sets ServerErrorsAsFailures as the default error classification. MessageBodyModule provides a singleton MessageBodyManager with default readers and writers, allowing users to customize marshalling via configureMessageBodyManager. ExceptionManagerModule registers default exception mappers (including JSON parsing and case class handlers) to standardize error responses. Additionally, DarkTrafficFilterModule enables dark traffic testing by providing a filter that conditionally forwards requests to a secondary service, configurable via the http.dark.service.dest flag and sampling logic.

http-server/src/main/scala/com/twitter/finatra/http/modules · high confidence

Added a complete Java-based Finatra HTTP server example (HelloWorldServer) that demonstrates configuring filters, controllers, exception mappers, and custom message body writers. The example includes a Bazel BUILD.bazel file for building and running the server, along with unit tests verifying endpoints like /hello, /goodbye, and /catFancy.

examples/http-server/java · high confidence

This change introduces a new set of Finagle Type-Agnostic filters for Finatra Thrift services. The AccessLoggingFilter provides standard access logs in the Common Log Format using the new ThriftCommonLogFormatter. The ExceptionMappingFilter delegates exception handling to the ExceptionManager. Additionally, LoggingMDCFilter, ThriftMDCFilter, and TraceIdMDCFilter are added to initialize the MDC adapter and populate diagnostic context with method names, client IDs, and trace identifiers (trace ID, span ID, and sampled flag) for improved log correlation.

thrift/src/main/scala/com/twitter/finatra/thrift/filters · high confidence

The \finatra-thrift-routing\ module is introduced with a new \ThriftWarmup\ class that allows developers to send requests to configured Thrift endpoints to warm up the server before it begins receiving external traffic. The build configuration for this location is established with strict dependency management and Bazel compatibility tags, while the routing logic now supports stack transformation for filters and respects Thrift server stack parameters.

thrift/src/main/scala/com/twitter/finatra/thrift/routing · high confidence

The inject-utils module now provides a comprehensive set of implicit conversion classes (Rich\* wrappers) for common Scala and Twitter Util types. Users can now easily convert Futures to AsyncStreams, transform booleans into Options or execute side-effects conditionally, and convert between Joda Time and Twitter Duration/Time objects. Additional utilities include methods to safely convert byte arrays to loggable strings (SHA-1 + Base64), distinct elements from iterables by a hash function, and flatten nested Future structures (e.g., Future\[Option\[Seq\[A\]\]\]).

inject/inject-utils/src/main/scala/com/twitter/inject/conversions · high confidence

A new \inject-mdc\ library has been introduced to provide Mapped Diagnostic Context (MDC) integration that respects Finagle's request-scoped local contexts. This module replaces the previous thread-local MDC implementation with one that stores context data in \com.twitter.finagle.context.LocalContext\, ensuring that logging context is correctly isolated per request and not leaked across threads. The package includes \FinagleMDCAdapter\ to swap the default SLF4J adapter, \MDCInitializer\ to manage initialization and scoped context binding via \let\, and \MDCKeys\ for common tracing identifiers like \traceId\. Users must call \MDCInitializer.init()\ to activate the adapter and use \MDCInitializer.let\ to manage context scope, ensuring MDC operations are no-ops if not properly initialized.

inject/inject-mdc · high confidence

A new inject-utils module has been introduced, consolidating shared utilities previously scattered across other components. This includes RetryUtils and RetryPolicyUtils for managing Finagle retry policies (exponential and constant backoffs), ExceptionUtils for handling exception details and determining non-retryable or cancellation states, FutureUtils for sequential and parallel future mapping, and new exception types like DetailedNonRetryableSourcedException and NonRetryableException to improve error tracking and retry logic.

inject/inject-utils/src/main/scala/com/twitter/inject/utils · high confidence

The inject-core module now includes an internal LibraryRegistry utility that allows components to store structured, nested configuration data in the global registry. This new class manages entries under a specific library namespace, supporting hierarchical sections (e.g., library\_name.section.key) and automatically sanitizing keys into snake\_case JSON-compatible formats. This change provides a standardized way for inject libraries to expose their configuration metadata to users and other systems via the global registry.

inject/inject-core/src/main/scala/com/twitter/inject/internal · high confidence

This change introduces several new utility classes in the \finatra-utils\ module: \FileResolver\ and \FileResolvers\ for resolving files from local directories or the classpath (including MIME type detection), \FuturePools\ for creating named fixed-size and cached thread pools for \Future\ operations, \AutoClosable\ for safely executing code with auto-closeable resources, and \ClassUtils\ (deprecated in favor of \util-reflect\) for simple class name extraction. These utilities are now available for use in Finatra applications to handle common resource management and file resolution tasks.

utils/src/main/scala/com/twitter/finatra/utils · high confidence

This change publishes the new \inject-thrift-client-http-mapper\ library, which provides a \ThriftClientExceptionMapper\ to automatically map \ThriftClientException\ errors from Thrift clients into HTTP 503 Service Unavailable responses. The module includes build configuration and comprehensive integration tests demonstrating multi-server topologies where HTTP servers call Thrift services, verifying correct error handling, retry behavior, and stats tracing across the HTTP-to-Thrift boundary.

inject-thrift-client-http-mapper · high confidence

The main application entry point (App.scala) in the com.posterous.finatra package has been removed. This eliminates the previous functionality that printed a 'Hello World!' message and concatenated command-line arguments, effectively cleaning up the codebase by discarding this initial scaffold.

src/main · high confidence

The core dependency injection abstractions have been extracted into the new \inject-core\ module, introducing an abstract \Injector\ class and a \TwitterModule\ base class that wrap Guice and ScalaGuice. This change provides a unified API for creating and retrieving instances (via \instance\[T\]\ methods) and managing module configuration, lifecycle hooks (\singletonStartup\, \singletonShutdown\), and flag integration (\TwitterModuleFlags\). The module also includes \TwitterPrivateModule\ for encapsulated bindings and \TypeUtils\ for Scala type handling, establishing the foundational layer for the Finatra inject library.

inject/inject-core/src/main/scala/com/twitter/inject · high confidence

The \contexts\, \exceptions\, and \response\ packages have been moved from the \http-server\ module to \http-core\. This change reorganizes the library structure, making response-related utilities like \ResponseBuilder\, \ResponseUtils\, and \SimpleResponse\ available in the core module, which may affect build dependencies for projects that previously relied on \http-server\ for these classes.

http-core/src/main/scala/com/twitter/finatra/http/response · high confidence

The inject-thrift-client module now includes a Bazel BUILD file defining the java\_library target with Guice dependencies and Bazel-compatible tags, alongside a workaround filegroup for Pants migration. Additionally, a new @NonFiltered binding annotation is introduced to support Scrooge's service-per-endpoint functionality, allowing specific fields, parameters, or methods to be excluded from standard filtering logic.

inject/inject-thrift-client/src/main/java · high confidence

The Scala Thrift server example has been updated to use the \MethodPerEndpoint\ API instead of the legacy \Service.FutureIface\ and \Service\[Future\]\ patterns. This change simplifies the controller implementation by allowing direct method handling and is supported by new Bazel build files, a Thrift IDL definition, and feature tests that verify the server's startup and client interaction.

examples/thrift-server/scala · high confidence

The \inject-thrift-client\ module now includes three new internal filters to enhance observability and error handling for Thrift RPCs. \IncrementCounterFilter\ provides a basic request counter, \LatencyFilter\ records request latency metrics (excluding black-hole responses) with configurable time units, and \ThriftClientExceptionFilter\ wraps retryable exceptions into \ThriftClientException\ instances for better diagnostic insight.

inject/inject-thrift-client/src/main/scala/com/twitter/inject/thrift/internal/filters · high confidence

The documentation site now uses custom Sphinx templates to modify the user interface. A new search box template provides a quick-search form that appears on all pages except the dedicated search page. The sidebar has been updated to include a logo image and a 'Useful Links' section with direct navigation to the User's Guide, Finagle Blog, GitHub repository, and issue tracker.

_doc/src/sphinx/\templates · high confidence

The \com.twitter.inject.Logging\ trait is now deprecated in favor of \com.twitter.util.logging.Logging\. Users should migrate their code to use the utility trait directly, as the inject-specific wrapper no longer provides unique functionality beyond what is available in the core util logging module.

inject/inject-slf4j/src/main/scala/com · high confidence

The Finatra validation module now marks its legacy constraint validators (such as Min, Max, Size, Pattern, and time-based checks), the ValidationResult wrapper, and CommonMethodValidations as deprecated, directing users to migrate to the standard constraints and utilities provided by the util-validator library. This change aligns the framework with a centralized validation engine, ensuring that existing Finatra applications continue to function while encouraging adoption of the newer, unified validation API.

validation/src/main/scala · high confidence

The \ThriftFilter\ trait and \AbstractThriftFilter\ class are deprecated in favor of \Filter.TypeAgnostic\, aligning Thrift filtering with the type-agnostic approach used in HTTP. Additionally, new \ThriftServerTrait\ and \AbstractThriftServerTrait\ are introduced to provide Java-friendly server implementations, exposing configuration flags for port, shutdown timeout, server name, and announcement, while also exposing the bound address for easier integration and debugging.

thrift/src/main/scala/com/twitter/finatra/thrift · high confidence

The \AndThenService\ interface and its internal implementation (\DefaultAndThenServiceImpl\) in the \inject-thrift-client\ module have been deprecated as of version 2022-03-03. Users relying on this service for chaining Thrift client filters should be aware that no direct replacement is provided, signaling that this internal composition mechanism is no longer supported for future use.

inject/inject-thrift-client/src/main/scala/com/twitter/inject/thrift/internal · high confidence

The JSON Patch functionality (including the \JsonPatchOperator\, message body reader, exception handling, and utility classes) has been relocated from the previous location into the \finatra/http-core\ project. This move consolidates the JSON Patch implementation within the core HTTP module, making it available as part of the \finatra-http-jsonpatch\ artifact with dependencies on \util-jackson\ and standard Finagle/Finatra HTTP components.

http-core/src/main/scala/com/twitter/finatra/http/jsonpatch · high confidence

The Finatra HTTP annotations (FormParam, Header, QueryParam, RouteParam) are now defined as Jackson InjectableValue markers within the util-jackson-annotations library, and the http-annotations module has been updated to depend on and export util-jackson-annotations. Additionally, a new JsonIgnoreBody annotation allows disabling automatic JSON body parsing for custom request case classes, and a new MessageBodyWriter marker annotation supports custom MessageBodyComponent rendering. The build definition now targets Java 8 and uses Bazel-compatible tags.

http-annotations · high confidence

The internal routing implementation (including \RoutingService\, \Routes\, \CallbackConverter\, and parameter handling) has been moved from the \finatra/http-server\ project to \finatra/http-core\. This change restructures the library so that the core routing capabilities are available to both the HTTP server and other Finagle-based HTTP clients, while the \http-server\ module now depends on \http-core\ for these internal components.

http-server/src/main/scala/com/twitter/finatra/http/internal/routing · high confidence

The HTTP streaming functionality, including StreamingRequest and StreamingResponse abstractions for handling Reader and AsyncStream inputs/outputs, has been relocated from the http-server module to the http-core module. This change restructures the project layout to make streaming capabilities available as part of the core HTTP library, allowing users to access these streaming features without depending on the full server implementation.

http-core/src/main/scala/com/twitter/finatra/http/streaming · high confidence

The Finatra Jackson integration has been reorganized into distinct sub-modules (core, caseclass, modules, serde, streaming, and annotations) to improve modularity. This change introduces a new case-class validation and injection system via \DefaultAnnotationIntrospector\ and \GuiceInjectableValues\, enabling stricter handling of Guice and Jackson injection annotations on case class fields. It also adds a non-blocking \AsyncJsonParser\ for streaming JSON deserialization and provides new binding annotations (\CamelCaseMapper\, \SnakeCaseMapper\) for configuring property naming strategies. Additionally, Joda-time serialization support is now deprecated in favor of JDK8 equivalents, and the module now depends on \util-jackson\ and \util-validator\ for shared functionality.

jackson/src/main · high confidence

The Finatra Java HTTP components—specifically the core HTTP library, JSON Patch support, and request handling utilities—have been relocated from the http-server module to the http-core module. This restructuring introduces new Bazel build targets (finatra-http-java, finatra-http-java-core, finatra-http-java-jsonpatch, and finatra-http-java-request) and Java source files, including the JavaCallback interface, the Operand enum for JSON Patch operations, and the ContentType enum for HTTP media types, all targeting Java 8.

http-core/src/main/java · high confidence

The Finatra documentation site has been rebuilt using Sphinx, replacing the previous format. This change introduces a new configuration structure (including CONFIG.ini and conf.py) and updates the documentation source to reStructuredText, including a new changelog entry that includes the main CHANGELOG.rst file. The site now uses the Flask theme and provides updated getting-started instructions for Finatra 2.x, including specific guidance on adding test-jar dependencies for sbt and Maven.

doc/src/sphinx · high confidence

The custom validation constraint annotations in the Finatra validation library (including AssertTrue, AssertFalse, CountryCode, FutureTime, Max, Min, NotEmpty, OneOf, PastTime, Pattern, Range, Size, TimeGranularity, and UUID) are now marked as deprecated. Users should migrate to standard bean validation annotations provided by the Jakarta Validation API instead of using these Finatra-specific constraints for case class field validation.

validation/src/main/java/com/twitter/finatra/validation/constraints · high confidence

The core logic for serializing and deserializing HTTP request and response bodies has been relocated from the internal http-server module to the http-core module. This change consolidates the DefaultMessageBodyReader and DefaultMessageBodyWriter implementations, along with their supporting traits and Jackson integration (MessageInjectableValues), into a shared http-core package. For users, this ensures that the fundamental JSON routing and body parsing capabilities are available as part of the core HTTP library, decoupling them from the specific server implementation details.

http-core/src/main/scala/com/twitter/finatra/http/marshalling · high confidence

The internal Thrift method service implementation has been updated to automatically attach method-level tags (specifically the method name and service name) to the Finagle stack parameters. This ensures that requests handled by this service are tagged for observability and routing purposes, leveraging the Finagle param.Tags mechanism within the internal service layer.

thrift/src/main/scala/com/twitter/finatra/thrift/internal · high confidence

The injectable-app and thrift-server Java examples have been migrated to use Bazel build files (BUILD.bazel) instead of the previous build system. This change adds the necessary build definitions, Java source files, and test suites for these examples, ensuring they are compatible with the Bazel build environment.

examples/injectable-app/java, examples/thrift-server/java · high confidence

The exception handling components (ExceptionManager, ExceptionMapper, and specific exception types like HttpException and RouteParamExtractionException) have been moved from the http-server module to the http-core module. This change makes these core exception-handling utilities available to modules that depend on http-core without requiring a dependency on the full http-server, facilitating better modularization and allowing users to configure exception mappers in lighter-weight HTTP server setups.

http-core/src/main/scala/com/twitter/finatra/http/exceptions · high confidence

The file upload implementation has been moved from the http-server module to http-core. This change relocates the core parsing logic (FinagleRequestFileUpload, RequestContext, FileUploadException) into a new finatra-http-fileupload artifact, making the file upload capability available as a standalone dependency rather than being bundled exclusively with the full HTTP server.

http-core/src/main/scala/com/twitter/finatra/http/fileupload · high confidence

This change introduces new dependency injection modules in the \finatra-thrift-modules\ package to standardize exception handling and response classification. The \ExceptionManagerModule\ now automatically registers a default \ThrowableExceptionMapper\ during startup, ensuring consistent exception mapping for Thrift services. Additionally, the \ThriftResponseClassifierModule\ binds a default \ThriftResponseClassifier\ that treats Thrift exceptions as failures, aligning response classification behavior with the updated \StatsFilters\ logic. These modules are part of a broader restructuring to support a new Pants build layout and improve the modularity of Finatra Thrift's core behaviors.

thrift/src/main/scala/com/twitter/finatra/thrift/modules · high confidence

The Finatra Thrift module now includes a new internal exception handling layer located in \thrift/src/main/scala/com/twitter/finatra/thrift/internal/exceptions\. This change introduces an \AbstractFrameworkExceptionMapper\ base class that standardizes how uncaught exceptions are mapped to responses, and a \ThrowableExceptionMapper\ singleton that serves as the root handler for any uncaught \Throwable\, forwarding them as exceptions. This infrastructure provides a structured way to handle framework-level errors and allows for future overrides or customizations within the Thrift integration.

thrift/src/main/scala/com/twitter/finatra/thrift/internal/exceptions · high confidence

The internal exception handling logic for the Finatra HTTP server has been reorganized into dedicated \internal/exceptions\ and \internal/exceptions/json\ packages. This change introduces an \AbstractFrameworkExceptionMapper\ base class to standardize how exceptions like \HttpException\, \CancelledRequestException\, and \TException\ are converted into HTTP responses, and adds specific mappers for JSON parsing errors (\JsonParseExceptionMapper\) and case-class mapping failures (\CaseClassExceptionMapper\). Users relying on these internal classes for custom exception handling will need to update their imports to reflect the new package structure.

http-server/src/main/scala/com/twitter/finatra/http/internal/exceptions · high confidence

The \inject-thrift-client\ modules have been restructured to support Finagle's \ServicePerEndpoint\ and \MethodPerEndpoint\ interfaces, replacing the older \AndThenService\ pattern (now deprecated). A new \ThriftMethodBuilderClientModule\ allows for fine-grained, per-method configuration and filtering of Thrift clients, while the existing \ThriftClientModule\ provides a simpler binding for standard interfaces. Additionally, new \DarkTrafficFilterModule\ implementations (\ReqRepDarkTrafficFilterModule\ for Scala and \JavaDarkTrafficFilterModule\ for Java) enable dark traffic sampling with configurable destination and client ID flags, and a dedicated \ThriftClientIdModule\ makes the client ID configurable via flags.

inject/inject-thrift-client/src/main/scala/com/twitter/inject/thrift/modules · high confidence

The TwitterServer framework has changed its shutdown behavior: previously, the server waited for all registered Awaitables to complete before exiting. It now exits as soon as any single registered Awaitable becomes ready. This allows applications to terminate more quickly when a specific background task finishes, rather than blocking on all other pending tasks.

inject/inject-server/src/main/scala/com/twitter/inject · high confidence

The marshalling subsystem now uses dedicated Guice modules to configure the message body reader and writer as singletons. MessageBodyManagerModule provides the DefaultMessageBodyReader and DefaultMessageBodyWriter, injecting dependencies like ScalaObjectMapper and FileResolver, while MessageBodyFlagsModule exposes the ResponseCharsetEnabled flag to control whether HTTP response Content-Type headers include the UTF-8 charset.

http-core/src/main/scala/com/twitter/finatra/http/marshalling/modules · high confidence

The Thrift client module now supports non-camelCase Thrift method names and provides finer-grain insight into ThriftClientExceptions via the new ThriftClientExceptionSource, allowing users to map exceptions to logical service names. Additionally, the ThriftMethodBuilder exposes idempotent and nonIdempotent method configurations, and the legacy AndThenService trait has been deprecated.

inject/inject-thrift-client/src/main/scala/com/twitter/inject/thrift · high confidence

The internal routing layer for Finatra Thrift services has been restructured to provide richer introspection capabilities. The new Registrar component populates the LibraryRegistry with specific metadata for each Thrift method, including the service name, implementation class, argument and response codec classes, annotations, and applied filters. Additionally, support for Java Thrift services has been added, allowing Java method signatures (including parameter and return type details) to be registered alongside Scala methods. A new NullThriftService object and a dedicated BUILD file for the routing package were also introduced to support this internal refactoring.

thrift/src/main/scala/com/twitter/finatra/thrift/internal/routing · high confidence

The Twitter Clone example has been migrated to the Bazel build system (replacing legacy BUILD files) and updated to use Finatra 2.0 APIs, including the removal of deprecated \FinatraObjectMapper\ and \Mockito\ traits. The example now uses \ScalaObjectMapper\ for JSON handling, integrates with Firebase via a dedicated HTTP client module, and includes a warmup handler to pre-warm the server. Tests have been updated to use the new \util-mock\ package and verify tweet creation, retrieval, and validation.

examples/advanced/twitter-clone · high confidence

Added Bazel build rules and tests for inject-slf4j; Added Bazel build targets and test assets for http-server test resources; Added Finatra HTTP benchmark suite and validation tests; Added Java integration tests for Finatra HTTP server; Added Java integration tests for Thrift dark traffic features; Added Java test coverage for TestInjector, EmbeddedApp, and TestConsoleWriter; Added Java test suite for Finatra HTTP streaming; Added Java test suite for Finatra Thrift server; Added Java unit tests for Finatra Jackson modules; Added Java unit tests for Finatra file resolvers; Added Thrift integration test utilities; Added Thrift service definitions for testing; Added Thrift test fixtures and Bazel build rules for Java/Scala code generation; Added comprehensive test coverage for finatra validation constraints; Added comprehensive test coverage for inject-core utilities and module bindings; Added comprehensive test suite for Finatra Thrift server and client integration; Added comprehensive test suite for inject-app testing utilities; Added integration and unit tests for the Finatra HTTP client; Added integration test infrastructure for Thrift client testing; Added integration tests for Mustache template rendering; Added integration tests for ServiceB Thrift client inheritance and HTTP controller wiring; Added integration tests for Thrift client modules and dark traffic; Added integration tests for Thrift client modules and service implementation; Added integration tests for per-endpoint Thrift client configuration; Added integration tests for snake\_case Thrift method dark traffic filtering; Added test controllers for Finatra Thrift integration; Added test coverage for Finatra Jackson deserialization and streaming; Added test coverage for Thrift exception mapping; Added test coverage for finatra http-core components; Added test coverage for inject-server utilities and integration scenarios; Added test coverage for inject-utils conversion utilities; Added test fixtures for annotation processing in inject-utils; Added test helper annotations and Bazel build configuration; Added test infrastructure for Finatra HTTP server; Added test infrastructure for Finatra Thrift server configuration and warmup; Added test module for dark traffic filtering; Added test resources and Bazel build configuration; Added test suite for Finatra HTTP server; Added test support for Guice binding annotations; Added test support modules for in-memory stats and tracing; Added test utilities for in-memory credential injection; Added test utilities for local filesystem and stats assertions; Added tests for DefaultResponseBuilder; Added tests for Finagle build revision parsing; Added tests for Finagle request scope filtering and lifecycle; Added tests for Finatra Mustache template rendering and lookup; Added tests for Finatra Thrift exception mapping behavior; Added tests for Finatra utils and credentials modules; Added tests for JsonLogging lazy evaluation; Added tests for Logback AsyncAppender behavior and configuration; Added tests for LogbackAsyncAppenderBase null-safety and test utilities; Added tests for MergedFilter; Added tests for PossiblyRetryable exception handling; Added tests for StackClientModuleTrait and StatsReceiverModule; Added tests for ThriftMethodUtils; Added tests for exception utility classes; Added tests for inherited Thrift service implementations; Added tests for server port utilities and port resolution; Added tests for the Injectable Twitter Server example; Added unit tests for inject-utils utility classes; New embedded testing utilities for Finatra integration tests; New test utilities for Finatra inject-app; New test utilities for stats, tracing, and async assertions in inject-core; Removed sample test files for JUnit, ScalaTest, and Specs.

The project has switched its build tooling from Maven to SBT. The legacy Maven \pom.xml\ has been removed and replaced with a comprehensive \build.sbt\ that defines the project structure, dependency versions (such as Jackson 2.14.3, Guice 5.1.0, and Scala 2.13.6), and publishing configuration. A new \benchmarks/build.sbt\ has been added to configure JMH benchmarking, and \project/build.sbt\ sets global compiler options.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 46 → 66 (+20.2)
• Rubric changed (rubric-2026.08.15 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 94 (-5.7)
• Architecture 94 → 74 (-19.7)
• Maturity 46 → 55 (+9.2)
• Readiness 27 → 70 (+43.3)
• Security 65 → 88 (+23.1)

• Coverage not measured — test suite did not build
• Dimension evaluation failed
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Low: security finding (details withheld)
• Low: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• Medium: security finding (details withheld)
• No exposed public API
• No tests found
• Test reliability not included
• The examples README is a 'Details' note directing readers to the per-project READMEs, with no dedicated Examples or Quickstart section. (examples/README.md)
• early-stage repository — too little history to judge knowledge freshness
• single-commit history — no usable git history window to measure hotspots
• single-maintainer — knowledge-concentration (bus factor) risk

• Documentation: no project overview (doc/src/sphinx/user-guide/index.rst)
• Dormant codebase
• Duplicated block (10 lines × 2) (examples/injectable-twitter-server/scala/src/main/scala/com/twitter/finatra/example/Publisher.scala)
• Duplicated block (14–19 lines × 2) (validation/src/main/scala/com/twitter/finatra/validation/constraints/MaxConstraintValidator.scala)
• Duplicated block (23 lines × 2) (http-core/src/main/scala/com/twitter/finatra/http/response/HttpResponseClassifier.scala)
• Duplicated block (6 lines × 2) (http-client/src/main/scala/com/twitter/finatra/httpclient/RequestBuilder.scala)
• Duplicated block (8 lines × 2) (http-client/src/main/scala/com/twitter/finatra/httpclient/HttpClient.scala)
• Duplicated block (8 lines × 2) (http-server/src/main/scala/com/twitter/finatra/http/filters/TraceIdMDCFilter.scala)
• Duplicated block (8 lines × 5) (http-server/src/main/scala/com/twitter/finatra/http/routing/HttpRouter.scala)
• Duplicated block (8–10 lines × 2) (http-server/src/main/scala/com/twitter/finatra/http/filters/AccessLoggingFilter.scala)
• Duplicated block (8–9 lines × 4) (http-server/src/main/scala/com/twitter/finatra/http/routing/HttpRouter.scala)
• Duplicated block (9 lines × 2) (http-core/src/main/scala/com/twitter/finatra/http/marshalling/MessageBodyManager.scala)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• IncludeCode.run (cognitive 48) (doc/src/sphinx/exts/includecode.py)
• IncludeCode.run (cyclomatic 31) (doc/src/sphinx/exts/includecode.py)
• Low cohesion: HttpRouter (LCOM4 4) (http-server/src/main/scala/com/twitter/finatra/http/routing/HttpRouter.scala)
• Medium: security finding (details withheld)
• …and 29 more

• Containers 0 added · 0 removed · contexts 1 added · 0 removed · edges 0 added · 0 removed

• repository

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

twitter/finatra was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.