Engine contract & codegen
ratavyr talks to the engine through gRPC bindings generated from the engine API contract, which is owned and versioned by motioncore: crates/engine-api/proto/motioncore/engine/v1/engine.proto, released as git tags engine-api/vX.Y.Z. See motioncore: engine gRPC API and contracts & versioning.
Compatibility: engine-api 1.x (motioncore.engine.v1). At every connect, ratavyr calls GetInfo and refuses an engine whose api_version major is not 1.
No copy of the proto
This repository never contains the .proto. Instead, contract.lock pins exactly which file the bindings came from:
repo=github.com/bzy-logics/motioncore
tag=engine-api/v1.0.2
commit=c761df0896c9a12f4e51100ec4cd78ef318a1b9d
path=crates/engine-api/proto/motioncore/engine/v1/engine.proto
import_path=motioncore/engine/v1/engine.proto
sha256=21b68b14523684cc4f93b90762a019466af884c8d739912840cba75b4bac7422The generated code in gen/ is committed. Don't edit it by hand.
Scripts
scripts/generate.sh # regenerate gen/
scripts/check-contract.sh # verify gen/ matches contract.lock (CI)generate.sh:
- reads the proto with
git show <tag>:<path>from a local motioncore clone ($MOTIONCORE_REPO, default../motioncore); - checks the tag resolves to the recorded commit (warns if not) and that the file's SHA-256 matches (fails if not);
- writes it to
.contract/(gitignored); - runs
go tool buf generate(buf.gen.yaml).
buf, protoc-gen-go and protoc-gen-go-grpc are pinned in go.mod with the tool directive and run with go tool; nothing needs installing.
check-contract.sh runs the same steps into a temporary directory and fails if the result differs from gen/.
Moving to a newer contract
For example, to engine-api/v1.1.0:
- Fetch the tag in your motioncore clone:
git -C ../motioncore fetch --tags. - Update
tag,commitandsha256incontract.locktogether:shgit -C ../motioncore rev-parse 'engine-api/v1.1.0^{commit}' git -C ../motioncore show engine-api/v1.1.0:crates/engine-api/proto/motioncore/engine/v1/engine.proto | sha256sum - Run
scripts/generate.sh. - Map any new fields in
internal/api/restand document them indocs/rest-api.md, the source of truth for the HTTP API. - Tell sindrava about REST changes: it mirrors the API in
src/types/api.ts.
A new major version (motioncore.engine.v2) is a separate package and requires code changes.
Mapping rules (proto → REST)
- Enum values lose their prefix and become lowercase:
ROBOT_STATE_EMERGENCY_STOPPED→"emergency_stopped". - Values unknown to this build (from a newer 1.x engine) become
"unknown";*_UNSPECIFIEDbecomes"unspecified". - Unset optional fields become
null, never omitted. - Empty strings that mean "none" in the proto (e.g.
endstop_pin) becomenull.