|
| 1 | + |
| 2 | + |
| 3 | ++++ |
| 4 | +title = "Insertion Points and Generic Services Regretted and Deprecated" |
| 5 | +weight = 92 |
| 6 | +description = "Covers why the Protobuf team regrets insertion points and generic services, and what to do instead" |
| 7 | +type = "docs" |
| 8 | ++++ |
| 9 | + |
| 10 | +Very early on in Protobuf's history (\~2008-2010), Protobuf added two different |
| 11 | +mechanisms which allow code outside of Protobuf to graft itself onto Protobuf's |
| 12 | +generated code: |
| 13 | + |
| 14 | +* **Generic services**, present since the first public release, are the |
| 15 | + abstract, RPC-system-agnostic `Service`, `Stub`, `RpcChannel` and |
| 16 | + `RpcController` classes that were supported in the C++, Java and Python |
| 17 | + generators |
| 18 | +* **Insertion points**, added in 2010, are comment markers that the generators |
| 19 | + leave in their output so that a *second* protoc plugin can splice arbitrary |
| 20 | + text into the middle of a generated file, including into the body of a |
| 21 | + generated message class. |
| 22 | + |
| 23 | +The two are linked: insertion points were added in the same release that |
| 24 | +deprecated generic services in favor of RPC-specific plugins, and insertion |
| 25 | +points were one mechanism by which a separate plugin could put its stubs back |
| 26 | +into the same generated file that the generic services had occupied. |
| 27 | + |
| 28 | +Generic services have been marked deprecated since 2010, and insertion points |
| 29 | +have always been labeled 'experimental', though their continued existence for |
| 30 | +over 15 years may have incorrectly signaled their ongoing stability. |
| 31 | + |
| 32 | +Both are design decisions the Protobuf team regrets: |
| 33 | + |
| 34 | +* Generic services have been formally deprecated since 2010, and no supported |
| 35 | + language after 2010 added them. We're working towards finally turning down |
| 36 | + this behavior in a future breaking release. |
| 37 | +* Insertion points have always been marked 'EXPERIMENTAL' and still work in |
| 38 | + the generators that originally shipped them, but we consider the mechanism a |
| 39 | + mistake. New language implementations do not emit them, we do not recommend |
| 40 | + that new plugins use them, and we know that routine private implementation |
| 41 | + detail changes to our generated code may break users of them. |
| 42 | + |
| 43 | +Our recommendation for both is the same, and it is to follow the model that gRPC |
| 44 | +uses: write a standalone plugin that emits its own files, with an API designed |
| 45 | +for your system, and compile them in a build target of their own that depends on |
| 46 | +the Protobuf generated code which is in a separate file. |
| 47 | + |
| 48 | +## The Shared Mistake {#shared-mistake} |
| 49 | + |
| 50 | +The two features look different but fail for the same reason: both make code |
| 51 | +that the Protobuf team does not own depend on the *inside* of Protobuf's |
| 52 | +generated code instead of composing with its public surface. |
| 53 | + |
| 54 | +As [We Prefer Opaque APIs](/design-decisions/opaque-apis) |
| 55 | +explains, Protobuf is depended on by nearly everything, so every observable |
| 56 | +detail of generated code is depended on by someone. The only thing that keeps |
| 57 | +Protobuf evolvable is being deliberate about which details are API and which are |
| 58 | +implementation. Generated code is co-versioned with the runtime and is *not* |
| 59 | +API: we restructure it freely to make parsing faster, messages smaller, and new |
| 60 | +features possible (see [Cross-Version Runtime |
| 61 | +Guarantee](/support/cross-version-runtime-guarantee)). |
| 62 | + |
| 63 | +Insertion points hand third parties a way to depend on the text of that |
| 64 | +generated code. Generic services bake an RPC abstraction into the message code |
| 65 | +and the core runtime. Either way, the next improvement to generated code has to |
| 66 | +negotiate with code the Protobuf team never saw. |
| 67 | + |
| 68 | +We know what the alternative costs you. Insertion points gave you one import and |
| 69 | +methods that appear to live on the message itself; generic services gave you an |
| 70 | +RPC-agnostic interface without writing a plugin. Giving those up means a second |
| 71 | +import, a second build target, and, unless you are using an existing RPC system |
| 72 | +such as gRPC, a plugin of your own. That cost is small, explicit, and paid once |
| 73 | +by the plugin author. The cost of grafting onto the generated code instead is |
| 74 | +large, hidden, and paid by everyone downstream of the message library, every |
| 75 | +time the generated code changes. |
| 76 | + |
| 77 | +## Insertion Points {#insertion-points} |
| 78 | + |
| 79 | +### What They Are {#insertion-points-what} |
| 80 | + |
| 81 | +The C++, Java, Python and Objective-C generators write comment markers into |
| 82 | +their output. A C++ header looks roughly like this: |
| 83 | + |
| 84 | +```cpp |
| 85 | +// @@protoc_insertion_point(includes) |
| 86 | + |
| 87 | +namespace foo { |
| 88 | + |
| 89 | +class Bar final : public ::google::protobuf::Message { |
| 90 | + public: |
| 91 | + // ... |
| 92 | + // @@protoc_insertion_point(class_scope:foo.Bar) |
| 93 | +}; |
| 94 | + |
| 95 | +inline int32_t Bar::id() const { |
| 96 | + // @@protoc_insertion_point(field_get:foo.Bar.id) |
| 97 | + return _internal_id(); |
| 98 | +} |
| 99 | + |
| 100 | +// @@protoc_insertion_point(namespace_scope) |
| 101 | +} // namespace foo |
| 102 | + |
| 103 | +// @@protoc_insertion_point(global_scope) |
| 104 | +``` |
| 105 | +
|
| 106 | +A plugin that runs later in the same `protoc` invocation can return a |
| 107 | +`CodeGeneratorResponse.File` whose `insertion_point` names one of these markers. |
| 108 | +`protoc` then splices the plugin's text in immediately above the marker line, |
| 109 | +inheriting its indentation. The plugin never sees the file it is editing; it |
| 110 | +only knows the name of a location in it. |
| 111 | +
|
| 112 | +Each generator exposes its own ad hoc set of markers: C++ has `includes`, |
| 113 | +`namespace_scope`, `global_scope`, `class_scope:T` and a marker inside the body |
| 114 | +of every generated accessor; Java has `outer_class_scope`, `class_scope:T`, |
| 115 | +`builder_scope:T`, `enum_scope:T`, and even `message_implements:T` and |
| 116 | +`builder_implements:T`, which let a plugin add arbitrary interfaces to the |
| 117 | +`implements` clause of a generated class; Python has `imports`, `module_scope` |
| 118 | +and `class_scope:T`. |
| 119 | +
|
| 120 | +The plugin-side API for all of this, `GeneratorContext::OpenForInsert()`, has |
| 121 | +carried the comment "WARNING: This feature is currently EXPERIMENTAL and is |
| 122 | +subject to change" since it was introduced in 2010. It was never promoted out of |
| 123 | +that status. |
| 124 | +
|
| 125 | +### Why They Are Too Invasive {#insertion-points-why} |
| 126 | +
|
| 127 | +**Inserted code sees implementation details and nothing stops it from using |
| 128 | +them.** Text spliced into `class_scope` is compiled as a member of the generated |
| 129 | +class. It can see private fields, internal helpers, the base class, the macros |
| 130 | +that happen to be defined, the headers that happen to be included, and the order |
| 131 | +in which everything was declared. Our documentation has always said "do not |
| 132 | +generate code which relies on private class members declared by the standard |
| 133 | +code generator", but the mechanism has no way to enforce that, and the inserter |
| 134 | +has no way to declare what it actually depends on. In practice, Hyrum's Law |
| 135 | +applies: whatever is visible gets used. |
| 136 | +
|
| 137 | +**They inevitably break as the runtime evolves.** Protobuf generated code is not |
| 138 | +frozen; it is a moving implementation detail of the runtime it ships with. Over |
| 139 | +the years we have moved C++ field storage into an internal `Impl_` struct, split |
| 140 | +rarely-set fields out of the main object, changed how presence bits are tracked, |
| 141 | +introduced `_internal_` accessors, added arena support, changed the default |
| 142 | +headers and macros, and we will keep doing this. Every such change is a |
| 143 | +potential compile error inside someone else's inserted text. Worse, the inserted |
| 144 | +text can keep compiling while silently violating a new invariant: code that |
| 145 | +writes a field directly without setting its hasbit, or that reads a submessage |
| 146 | +field that is now lazily parsed, is wrong in a way that no compiler will report. |
| 147 | +These failures surface in another team's plugin, in another repository, at an |
| 148 | +unpredictable time, and the Protobuf team cannot see them coming because the |
| 149 | +dependency is on a *position in a text file*, not on a declared API. |
| 150 | +
|
| 151 | +**They fuse unrelated code into one artifact and one build target.** Inserted |
| 152 | +code lives in the same `.pb.h`, `Foo.java` or `_pb2.py` as the messages, so it |
| 153 | +lives in the same library. Everyone who depends on the messages now transitively |
| 154 | +depends on whatever the inserting plugin needed, typically an entire RPC |
| 155 | +runtime, and the file can only be produced by running every contributing plugin |
| 156 | +in a single `protoc` invocation, in the right order. This is how a `.proto` that |
| 157 | +merely *defines* a service ends up forcing a message-only client to link an RPC |
| 158 | +stack, and how message libraries end up failing to build on platforms where that |
| 159 | +RPC stack does not exist. |
| 160 | +
|
| 161 | +### Every Major User Has Moved Away {#insertion-points-history} |
| 162 | +
|
| 163 | +The only significant use of insertion points has been RPC systems inserting |
| 164 | +service stubs into message files, and every one of them has since converged on |
| 165 | +standalone files: |
| 166 | +
|
| 167 | +* **gRPC C++** has always generated separate `.grpc.pb.h` / `.grpc.pb.cc` |
| 168 | + files, and its plugin refuses to run if `cc_generic_services` is enabled. |
| 169 | +* **gRPC Python** originally inserted its services into `_pb2.py` at the |
| 170 | + `module_scope` insertion point. The generator now writes a separate |
| 171 | + `_pb2_grpc.py` by default, and the inserted variant is marked for removal |
| 172 | + ("THESE ELEMENTS WILL BE DEPRECATED. Please use the generated |
| 173 | + `*_pb2_grpc.py` files instead."). |
| 174 | +* **gRPC Go** was once generated by a `plugins=grpc` option inside |
| 175 | + `protoc-gen-go`, emitting services into the same `.pb.go` as the messages. |
| 176 | + The option was removed in the APIv2 rewrite of Go Protobuf; gRPC now ships |
| 177 | + its own `protoc-gen-go-grpc`, which writes `_grpc.pb.go`. |
| 178 | +
|
| 179 | +### What to Do Instead {#insertion-points-instead} |
| 180 | +
|
| 181 | +Write a standalone plugin that: |
| 182 | +
|
| 183 | +* emits its own files (`foo.grpc.pb.h`, `FooGrpc.java`, `foo_pb2_grpc.py`, |
| 184 | + `foo_grpc.pb.go`, and so on), and never names an `insertion_point`; |
| 185 | +* depends on messages only through their public generated API and through |
| 186 | + reflection, descriptors and custom options; and |
| 187 | +* is driven by its own build rule (a `*_grpc_library` or equivalent) that |
| 188 | + depends on the message library, rather than being hidden inside the message |
| 189 | + build. |
| 190 | +
|
| 191 | +If you need per-message behavior that *looks* like a method on the message, use |
| 192 | +the idioms the language already has for extending a type you do not own: free |
| 193 | +functions or traits in C++ and Rust, static utility classes or extension |
| 194 | +functions in Java and Kotlin, wrapper types, and so on. If you need per-message |
| 195 | +*data*, put it in a custom option and read it through the descriptor at build |
| 196 | +time or at run time. |
| 197 | +
|
| 198 | +This applies to small insertions too. A `class_scope` helper that has nothing to |
| 199 | +do with RPC does not drag an RPC runtime into the message library, but it is |
| 200 | +still compiled as a member of the generated class, still sees every private |
| 201 | +detail of it, and still breaks when those details change; the first two problems |
| 202 | +in [Why They Are Too Invasive](#insertion-points-why) do not depend on the size |
| 203 | +of the insertion. Interfaces added through `message_implements:T`, |
| 204 | +`builder_implements:T` or `interface_extends:T` have no one-to-one replacement, |
| 205 | +and that is deliberate: use an adapter or wrapper type, or a registry keyed by |
| 206 | +descriptor, rather than changing the type hierarchy of a class you do not own. |
| 207 | +
|
| 208 | +## Generic Services {#generic-services} |
| 209 | +
|
| 210 | +### What They Are {#generic-services-what} |
| 211 | +
|
| 212 | +Generic services date from the original 2008 design and were built on the idea |
| 213 | +that RPC systems could plug in underneath by implementing `RpcChannel` and |
| 214 | +`RpcController`. The intent was that Protobuf would define the shape of a |
| 215 | +service once, and every RPC implementation would fit itself to that shape. |
| 216 | +
|
| 217 | +### Why They Were an Insufficient Generalization {#generic-services-why} |
| 218 | +
|
| 219 | +The `service.h` header describes the controller as "a 'least common denominator' |
| 220 | +set of features which we expect all implementations to support". The least |
| 221 | +common denominator turned out to be too small to hold a real RPC system: |
| 222 | +
|
| 223 | +* **Unary only.** `CallMethod(method, controller, request, response, done)` |
| 224 | + takes exactly one request message and produces exactly one response message. |
| 225 | + Client streaming, server streaming and bidirectional streaming, first-class |
| 226 | + features of both gRPC and Stubby, cannot be expressed at all. |
| 227 | +* **One hard-coded calling convention.** The interface is asynchronous with a |
| 228 | + `Closure*` completion callback (a Google-specific type exposed in a public |
| 229 | + interface). It does not fit blocking calls, futures, completion queues, |
| 230 | + coroutines, Kotlin `suspend` functions or reactive streams. Supporting just |
| 231 | + one additional convention, blocking calls in Java, required a second |
| 232 | + parallel set of generated types: `BlockingInterface`, `BlockingStub`, |
| 233 | + `BlockingRpcChannel`, `BlockingService` and `ServiceException`. |
| 234 | +* **No room for RPC semantics.** `RpcController` offers `Failed()`, |
| 235 | + `ErrorText()`, `StartCancel()`, `SetFailed(string)`, `IsCanceled()` and |
| 236 | + `NotifyOnCancel()`, and nothing else: no deadlines, no metadata or headers, |
| 237 | + no structured status codes (errors are a string), no compression, no |
| 238 | + authentication context, no interceptors, no flow control. Any real system |
| 239 | + has to downcast the controller to its own subtype to get at these, at which |
| 240 | + point the "generic" layer is nothing but, in the words of our own |
| 241 | + documentation, "more levels of indirection than code tailored to one |
| 242 | + system". |
| 243 | +* **Requires full reflection.** Dispatch goes through `MethodDescriptor` and |
| 244 | + `Message` rather than `MessageLite`, so generic services cannot be used with |
| 245 | + the lite runtimes on mobile and embedded platforms, which are precisely the |
| 246 | + platforms where a portable RPC story would have mattered most. `protoc` |
| 247 | + enforces this directly: "Files with `optimize_for = LITE_RUNTIME` cannot |
| 248 | + define services unless you set both options `cc_generic_services` and |
| 249 | + `java_generic_services` to false." |
| 250 | +* **They tie the message library to an RPC abstraction.** The service code is |
| 251 | + emitted into the same files as the messages, and `service.h` lives in the |
| 252 | + core runtime. This is the same coupling problem as insertion points, with |
| 253 | + the same build-time consequences. |
| 254 | +
|
| 255 | +The result is that very few RPC systems were built on generic services. gRPC |
| 256 | +generates its own stubs in every language and its C++ plugin fails outright if |
| 257 | +`cc_generic_services` is on. The original design goal, "define the shape once |
| 258 | +and let RPC systems fit themselves to it", was inverted in practice: the generic |
| 259 | +shape fit very few users, and the RPC systems had to be designed around escaping |
| 260 | +it. |
| 261 | +
|
| 262 | +### What to Do Instead {#generic-services-instead} |
| 263 | +
|
| 264 | +Follow the gRPC model. Keep `service` definitions in your `.proto` files: they |
| 265 | +remain the authoritative schema of the API, they are available through |
| 266 | +reflection and descriptors, and they can carry custom options. But the *code* |
| 267 | +for a service should come from the RPC system's own protoc plugin, into its own |
| 268 | +files, with an API designed for that system's calling conventions, streaming |
| 269 | +model, status codes, deadlines and metadata. |
| 270 | +
|
| 271 | +Protobuf's role is to be the interface definition language and the message |
| 272 | +layer. The RPC layer belongs to the RPC system. |
| 273 | +
|
| 274 | +## Guidance for New Languages and New Plugins {#guidance} |
| 275 | +
|
| 276 | +* New Protobuf language implementations do not emit insertion points and do |
| 277 | + not generate generic services. This is not an oversight to be fixed later. |
| 278 | +* New protoc plugins generate standalone files. A plugin that needs to be |
| 279 | + "inside" Protobuf's generated code is a sign that the design should be |
| 280 | + revisited, not a reason to add an insertion point. |
| 281 | +* Changes to the structure of generated code that break code inserted at an |
| 282 | + insertion point are not considered breaking changes to Protobuf. |
0 commit comments