Skip to content

Commit 689caf3

Browse files
Add design decision doc explaining why we regret insertion points and generic services
PiperOrigin-RevId: 992389742
1 parent 89949c9 commit 689caf3

9 files changed

Lines changed: 306 additions & 9 deletions

File tree

‎content/design-decisions/_index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,5 @@ things develop in the broader ecosystem context.
2121
* [Opaque APIs](/design-decisions/opaque-apis)
2222
* [Implicit
2323
Presence](/design-decisions/implicit-presence)
24+
* [Insertion Points and Generic
25+
Services](/design-decisions/insertion-points-and-generic-services)
Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
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.

‎content/news/2026-09-22.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,9 @@ We are removing these APIs because they are not compatible with open enums.
103103
Disable code generation of `cc_generic_services`, as generic services have been
104104
deprecated since they were introduced. You can revert to legacy behavior by
105105
setting the protoc flag `--allow_legacy_generic_services`. This flag will be
106-
removed in a future breaking release.
106+
removed in a future breaking release. For the reasoning behind the deprecation,
107+
see the
108+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
107109

108110
## Changes in Java {#java}
109111

@@ -134,7 +136,8 @@ Respect UTF-8 validation feature for string extensions in all Editions.
134136
Disable code generation of `java_generic_services` as generic services have been
135137
deprecated since 2010. You can revert to legacy behavior by setting the protoc
136138
flag `--allow_legacy_generic_services`. This flag will be removed in a future
137-
breaking release.
139+
breaking release. For the reasoning behind the deprecation, see the
140+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
138141

139142
## Changes in Objective-C {#objectivec}
140143

@@ -191,7 +194,8 @@ protobuf field of type int or float/double.
191194
Disable code generation of `python_generic_services`, as generic services have
192195
been deprecated since 2010. You can revert to legacy behavior by setting the
193196
protoc flag `--allow_legacy_generic_services`. This flag will be removed in a
194-
future breaking release.
197+
future breaking release. For the reasoning behind the deprecation, see the
198+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
195199

196200
## Changes in PHP {#php}
197201

‎content/programming-guides/editions.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1887,7 +1887,9 @@ Here are a few of the most commonly used options:
18871887
implementations should provide
18881888
[code generator plugins](/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb)
18891889
to generate code specific to their system instead of relying on "abstract"
1890-
services that will eventually be removed.
1890+
services that will eventually be removed. For the reasoning behind the
1891+
deprecation, see the
1892+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
18911893
18921894
* `cc_enable_arenas` (file option): Enables
18931895
[arena allocation](/reference/cpp/arenas) for C++

‎content/programming-guides/proto2.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2013,7 +2013,9 @@ Here are a few of the most commonly used options:
20132013
implementations should provide
20142014
[code generator plugins](/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb)
20152015
to generate code specific to their system instead rather than rely on
2016-
"abstract" services which will eventually be removed.
2016+
"abstract" services which will eventually be removed. For the reasoning
2017+
behind the deprecation, see the
2018+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
20172019
20182020
* `cc_enable_arenas` (file option): Enables
20192021
[arena allocation](/reference/cpp/arenas) for C++

‎content/programming-guides/proto3.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1588,7 +1588,9 @@ Here are a few of the most commonly used options:
15881588
implementations should provide
15891589
[code generator plugins](/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb)
15901590
to generate code specific to their system instead rather than rely on
1591-
"abstract" services which will eventually be removed.
1591+
"abstract" services which will eventually be removed. For the reasoning
1592+
behind the deprecation, see the
1593+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
15921594
15931595
* `cc_enable_arenas` (file option): Enables
15941596
[arena allocation](/reference/cpp/arenas) for C++

‎content/reference/cpp/cpp-generated.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1310,7 +1310,8 @@ option cc_generic_services = false;
13101310

13111311
If neither of the above lines are given, the option defaults to `false`, as
13121312
generic services are deprecated. (Note that prior to 2.4.0, the option defaults
1313-
to `true`)
1313+
to `true`.) For the reasoning behind the deprecation, see the
1314+
[design decision on generic services](/design-decisions/insertion-points-and-generic-services#generic-services).
13141315

13151316
RPC systems based on `.proto`-language service definitions should provide
13161317
[plugins](/reference/cpp/api-docs/google.protobuf.compiler.plugin.pb)

0 commit comments

Comments
 (0)