~bigbes/tarantool-protobuf: docs(readme): vendoring an upstream .proto schema

7ae72311d3e4722ba8a95acb95c60c0496b6cb75 — Eugene Blikh 3 months ago 14e1981

docs(readme): vendoring an upstream .proto schema

Consumers vendoring upstream protos (etcd, prometheus, pprof, …) hit
annotation-import resolution that protoc-gen-tarantool can't fix on
its own — mainline protoc rejects files with unresolved imports like
versionpb / google.api / gogoproto. Document the standard workaround:
strip the offending imports + their attached options, optionally
rewrite cross-package imports to a flat layout, then run protoc.

Reference implementation: tarantool-etcd's proto/_strip_annotations.py.

patch browse .tar.gz .zip

1 files changed, 44 insertions(+), 0 deletions(-)

M README.md

M README.md => README.md +44 -0

@@ 107,6 107,50 @@ prefix is prepended to the option's value. See
 For a full walk-through that takes a fresh `.proto` to a Tarantool process
 encoding and decoding it, see **[docs/howto/01-first-message.md](docs/howto/01-first-message.md)**.
 
+## Vendoring an upstream `.proto` schema
+
+If you're vendoring someone else's `.proto` into your project (etcd,
+prometheus, opentelemetry, pprof, …), `protoc-gen-tarantool` plus a
+small preprocessor is the typical path.
+
+Upstream protos commonly import annotation extensions that only the
+original generator consumes — `versionpb`, `google.api`, `gogoproto`,
+`grpc.gateway.protoc_gen_openapiv2`. Mainline `protoc` won't parse a
+file with an unresolved import, so the choice is between vendoring the
+extension `.proto` files (lots of additional surface, no wire effect)
+or stripping the imports and their attached options before generating.
+Stripping is the lower-cost path — these annotations affect nothing on
+the wire.
+
+A drop-in preprocessor (one `python3` script, no dependencies) should
+drop `import "versionpb/...";` / `google/api/...` / `gogo.proto` /
+`protoc-gen-openapiv2/...` lines, drop single-line and brace-balanced
+`option (foo.bar) = ...;` blocks at file/message/field scope, and drop
+inline field options `[(foo.bar) = "..."]`. Reference: tarantool-etcd's
+[`proto/_strip_annotations.py`][strip] (~60 lines).
+
+The same preprocessor is also where you rewrite cross-package imports
+to a flat layout: e.g. `import "etcd/api/mvccpb/kv.proto"` →
+`import "mvccpb/kv.proto"`, so a single `protoc -I proto` resolves
+every file without mirroring the upstream subdirectory tree.
+
+Putting it together:
+
+```bash
+mkdir -p proto/<pkg>
+for f in upstream/<path>/*.proto; do
+    python3 strip_annotations.py < "$f" > proto/<pkg>/"$(basename "$f")"
+done
+protoc -I proto --tarantool_out=prefix=myapp.proto:out $(find proto -name '*.proto')
+```
+
+One pitfall: this plugin is proto3-only. If an upstream schema mixes
+proto2 and proto3, either skip the proto2 files (provided your proto3
+side doesn't import them) or wait for proto2 support — see PLAN.md's
+deferred non-goals.
+
+[strip]: https://git.srht.bigb.es/tarantool-etcd/tree/master/item/proto/_strip_annotations.py
+
 ## Generated API
 
 For each message `Foo` the plugin emits: