Cross-Version Runtime Guarantee
Protobuf language bindings have two components. The generated code (typically
protoc) and the runtime libraries that must be included when
using the generated code. When these come from different releases of protobuf,
we are in a “cross version runtime” situation.
Historically, protobuf has not documented its cross-version runtime compatibility guarantees and has been inconsistent about enforcing what guarantees it provides. Moving forward, we intend to offer the following guarantees across all languages except C++. These are the default guarantees; however, owners of protobuf code generators and runtimes may explicitly override them with more specific guarantees for that language.
Protobuf will not support mixing generated code and runtimes across major version boundaries. We will add “poison pills” where possible to detect these mismatches.
Within a single major runtime version, generated code from an older version of
protoc will run on a newer runtime.
Within a single major runtime version, generated code from a newer version of
protoc is not guaranteed to run on an older runtime. We will add “poison
pills” where possible to detect these mismatches.
We reserve the right to violate the above promises if needed for security reasons. We expect these exceptions to be rare, but will always prioritize security above these guarantees. For example, footmitten required paired updates to both the runtime and the generated code for Java. As a result, code generated by 3.20.3 (which contained the footmitten fix) would not load with runtime library 3.21.6 (which predates the footmitten fix), creating the following compatibility matrix:
|Generated Code Version|
- “Vuln” indicates that the combination will successfully start, but the security vulnerability still exists.
- “Works” indicates that the combination will successfully start and does not have the vulnerability.
- “Broken” indicates that the combination will not successfully start.
- Bold indicates configurations that were never deliberately intended to function together given the guarantees outlined in this topic.
No Coexistence of Multiple Major Runtime Versions
Coexistence of multiple major versions in the same process is not supported.
C++ Specific Guarantees
Protobuf C++ disclaims all cross-runtime support and requires an exact match between its generated code version and its runtime version at all times. Additionally, Protobuf C++ makes no guarantees about ABI stability across any releases (major, minor, or micro).