Build-Time Generation Pipeline
Palyra uses a decentralized generation model where each Rust crate responsible for a service (e.g.,palyra-daemon, palyra-cli) generates its own stubs during the cargo build lifecycle. This ensures that the generated code is always in sync with the crate’s specific version of the protocol.
Implementation Details
The pipeline relies on two primary components defined in the workspace:protoc-bin-vendored: Provides a platform-agnosticprotocbinary, eliminating the need for developers to install Protobuf compilers manually Cargo.toml#53-53.tonic-prost-build: A build-time utility that translates.protofiles into Rust code using theprostandtonicframeworks Cargo.toml#74-75.
Data Flow: Proto to Rust
The following diagram illustrates howschemas/proto files are transformed into usable Rust code within the palyra-daemon and palyra-cli crates.
Stub Generation Architecture
Sources: crates/palyra-daemon/build.rs#3-36, crates/palyra-cli/build.rs#3-35, Cargo.toml#53-75
Build Configuration
Bothpalyra-daemon and palyra-cli implement a build.rs script that monitors the schemas/proto directory for changes using cargo:rerun-if-changed crates/palyra-daemon/build.rs#16-22.
Key function calls in the build process:
protoc_bin_vendored::protoc_bin_path(): Locates the vendored compiler crates/palyra-daemon/build.rs#4-4.tonic_prost_build::configure(): Sets whether to generate server-side traits (build_server) or client-side handles (build_client) crates/palyra-daemon/build.rs#24-24.compile_protos(): Consumes the array of.protopaths and the include root crates/palyra-cli/build.rs#24-35.
Protocol Governance and Validation
To prevent breaking changes and ensure cross-platform compatibility (Android/Kotlin and iOS/Swift), Palyra employs a suite of governance scripts located inscripts/protocol/.
Validation Scripts
| Script | Purpose |
|---|---|
validate-proto.ps1 | Uses protoc to verify that all .proto files are syntactically correct and can be compiled into a descriptor set scripts/protocol/validate-proto.ps1#57-66. |
check-generated-stubs.ps1 | A CI-gate script that ensures the stubs currently in the repository match what the latest schemas would produce. |
generate-stubs.ps1 | The master script for regenerating all language-specific stubs (Rust, Kotlin, Swift). |
Cross-Language Enforcement
While Rust stubs are generated at build time, Kotlin and Swift stubs are typically pre-generated and checked into the repository to simplify mobile app builds. Thevalidate-kotlin-stubs.ps1 and validate-swift-stubs.ps1 scripts ensure these remain synchronized with the core schemas.
Protocol Governance Workflow
Sources: scripts/protocol/validate-proto.ps1#9-71, .github/workflows/ci.yml#172-212
CI Enforcement
TheQuality job in the CI pipeline enforces protocol governance. It runs several hygiene checks, including the check-generated-stubs logic, to ensure that no developer has modified a .proto file without also updating the corresponding generated code .github/workflows/ci.yml#172-190.
Additionally, the Security Gates workflow performs a High-risk pattern scan via scripts/check-high-risk-patterns.sh, which includes checks for unsafe protocol usage or unversioned schema changes .github/workflows/security.yml#128-129.
Versioning Governance
The protocol follows a strict versioning scheme defined by thePROTOCOL_MAJOR_VERSION. All services must include common.proto which defines baseline types used across the gateway, browser, and node services crates/palyra-daemon/build.rs#12-14.
Sources: crates/palyra-daemon/build.rs#8-14, scripts/protocol/validate-proto.ps1#48-51, .github/workflows/ci.yml#172-187