Apache Thrift Documentation

Apache Thrift is a lightweight, language-independent software stack for point-to-point RPC (Remote Procedure Call) implementation. It provides abstractions for data transport, data serialization, and application-level processing.

Key features include:

• Code Generation: A definition language is used as input to generate interoperable RPC clients and servers across multiple programming languages.
• Language Support: Supports 28 programming languages.
• Versioning Compatibility: Designed to support non-atomic version changes, allowing servers to be upgraded while servicing older clients, or newer clients to interact with older servers.

The Thrift OCaml library provides abstract classes, exceptions, and general use functions primarily located in Thrift.ml.

Key implementation components include:

• Protocols: TBinaryProtocol
• Transports: TSocket, TServerSocket
• Servers: TSimpleServer, TThreadedServer

Note: The exception TServer is located in Thrift.ml.

Loading the thrift_native extension replaces Thrift::Struct, Thrift::Union, and Thrift::CompactProtocol methods with C implementations for improved performance.

• Fallback: If the native extension cannot be built or loaded, Thrift falls back to the pure-Ruby implementation.
• JRuby: JRuby automatically skips the native extension and uses the pure-Ruby path.
• Binary Protocol: Thrift::BinaryProtocol remains in pure Ruby unless you opt-in to the C-backed version using Thrift::BinaryProtocolAcceleratedFactory or Thrift::BinaryProtocolAccelerated (if available).

Thrift is distributed as a set of Python packages. The top-level package is thrift. It is organized into the following subpackages:

• thrift.protocol: Contains protocol implementations (e.g., TProtocol).
• thrift.transport: Contains transport implementations (e.g., TTransport, TSocket).
• thrift.server: Contains server implementations.
• thrift.reflection: Contains generated code for reflection structures.

FB303 (Facebook Bassline) provides a standard interface for backend services to implement common cross-cutting concerns. Use this service to provide a unified way to handle:

• Monitoring
• Dynamic options and configuration
• Uptime reports
• Activity tracking

Backend projects should inherit from this service to ensure they provide these standard capabilities. If you are adding new functionality, determine if it is a general utility that can be abstracted; if so, it may belong in the fb303 tree.

Apache Thrift uses OSS-Fuzz to continuously test the robustness of both hand-written and generated code. The fuzzing efforts focus on two primary goals:

1. Security: Testing how generated code handles malformed or malicious input.
2. Serialization round-trip correctness: Ensuring data remains identical after a serialization and subsequent deserialization cycle.

For each supported language, Thrift implements two types of fuzzers:

• Deserializer Fuzzer: Attempts to deserialize raw fuzzer input into Thrift structures to test handling of unexpected input across protocols (Binary, Compact, JSON).
• Round-Trip Fuzzer: Deserializes input, re-serializes it, and verifies the result matches the original to ensure data integrity.

Apache Thrift is an IDL-driven cross-language RPC and serialization framework. It is a library and code generator, not a deployed service.

Key Scope Details:

• In-Scope: The apache/thrift repository, including the C++ IDL compiler, language runtimes (lib/<lang>/), and the generated code produced by the compiler.
• Out-of-Scope: The apache/thrift-website repository, test/tutorial/contrib directories, and third-party packaging mechanisms (e.g., vcpkg, crates.io, Maven Central). While the code inside a package is in-scope, the packaging process itself is not.
• Security Reporting: As of the current draft, the project does not have a dedicated SECURITY.md. Vulnerabilities should be reported via the Apache Software Foundation (ASF) security PMC pipeline at security@apache.org.

The /contrib folder in the Apache Thrift repository serves as a repository for sample code demonstrating Thrift capabilities and potentially helpful utilities.

Warning: Code in this folder is not maintained on a regular basis and is not part of regular testing procedures. It may not work for your specific environment, purpose, or software version. Use it primarily as a reference for sample implementations.

Thrift uses different transport types with different buffering behaviors:

• TSocket: An endpoint transport; it is unbuffered.
• TBufferedTransport: A layered transport wrapper that buffers reads and writes.
• TFramedTransport: A layered transport wrapper that buffers an entire frame before deserializing.

If a frame-size cap is set, it bounds the buffered consumption for these layered transports.

To build the Thrift compiler specifically on a Windows environment, you need:

• Visual Studio C++
• Flex and Bison (e.g., the WinFlexBison package)