#Documentation

The user-facing docs for tarantool-protobuf, grouped by what you're trying to do. The README has the feature matrix, quick start, and status numbers; this page is the map for everything else.

#Getting started

If you're new to the project, work through the how-tos in order; each links to the next.

1. Your first message, end-to-end — write a proto, run the plugin, encode/decode in Tarantool.
2. Module layout — prefix, lua_package, LUA_PATH, three side-by-side protoc invocations.
3. gRPC with the loopback transport — Greeter end-to-end with all four streaming flavors.
4. WKT: Struct / Value / ListValue — round-tripping JSON-shaped data through proto.
5. Packing and unpacking Any — typed message payloads, registry, opaque fallback.
6. JSON over tarantool/http — exposing a proto-defined API as JSON HTTP.
7. Text format for debugging — mainline-protoc-compatible printer and parser.
8. Dynamic schemas from a Tarantool space — pb.parse and pb.from_pb for runtime descriptors.
9. When to use decode_lazy — picking eager vs lazy by workload shape.
10. Migrating from the built-in protobuf — side-by-side schema and call-site diffs.
11. Build integration — protoc, Makefile, Justfile, buf, CMake.
12. Writing a custom transport — implementing the four-method contract.

When something doesn't work, troubleshooting collects the common errors and their fixes.

#Reference

• reference/runtime-api.md — every export of require('pb'): codec, lazy view, dynamic descriptors, JSON/text/WKT/gRPC, sentinels, codegen helpers.
• reference/generated-api.md — what each _pb.lua exposes per message, enum, and service.
• reference/cli.md — driving protoc-gen-tarantool and protoc-gen-tarantool-doc from protoc. Flags, file options, path-resolution rules.
• reference/grpc-contract.md — the four-method transport interface, stream-object shapes, and the shipped loopback / multiplex transports.
• api-modes.md — full / runtime / lazy. Same descriptor, three call shapes. When to pick which, with measured trade-offs and the field-name-constants contract for lazy views.
• codegen.md — how protoc-gen-tarantool works: the pipeline, the descriptor-table contract (canonical shape), inline-mode vs runtime-mode emission, the LuaJIT hot-path rules generated code observes, and how to add a new scalar type.
• Auto-generated proto reference — examples/docs/hello.md is the output of the sibling protoc-gen-tarantool-doc plugin against examples/proto/hello.proto. Same plugin can run against any .proto to produce its own per-file Markdown.

#Specs

Forward-looking design docs. These describe contracts and trade-offs for work that's either partly shipped or planned.

• specs/grpc_transports.md — the transport contract (shipped, stable), the protocol matrix (HTTP/2 gRPC vs Connect vs net.box tunnel vs IProto), recommended transports to build, and the gRPC status-code mapping. The loopback and multiplex transports already ship in runtime/pb/grpc.lua; external transports (http_server, netbox, http_client) are not yet built.
• specs/msgpack_encoding.md — brainstorm for a sibling MsgPack codec over the same descriptors. Not implemented; design sketch for picking up later.

#Internals

• Beads issue tracker — durable roadmap and task state. Run bd ready for available work and bd show <id> for context.
• ../CLAUDE.md — invariants and conventions enforced across the codebase: no pairs() on hot paths, 64-bit ints as cdata, SoA over AoS for large index structures, keep hot helpers small, WKT routing.