Tusk Drift Schemas

This repo holds schemas defined as protobuf files used by Tusk Drift. We use Buf to generate code for each language we support (currently TypeScript, Golang, and Python), and prost-build to generate Rust types.

Prerequisites

Before generating schemas, install the following:

1. Install the Buf CLI.

2. Python betterproto (for Python code generation):

   pip install "betterproto[compiler]>=2.0.0b7"
   # Or using the requirements file:
   pip install -r requirements.txt
   

3. Rust toolchain (for Rust schema crate code generation / checks):

   rustup toolchain install 1.93.1
   

   This repo also pins Rust in rust-toolchain.toml.

Generating Schemas

After modifying .proto files, regenerate the code:

npm run generate

Generated package directories:

[!NOTE] Rust generated files live under rust/src/generated so the published crate is self-contained (crates.io packages only include files within the crate directory).

[!NOTE] You may see "duplicate generated file name" warnings from betterproto. These are harmless and can be ignored — they occur because multiple proto packages share the same Python namespace (tusk.drift).

Then build the TypeScript package:

npm run build

[!NOTE] npm run build runs npm run sync:exports before bundling. You do not need to manually edit package.json exports when adding or removing files within the existing TypeScript export roots (generated/ts/*, and src/*). Only update scripts/sync-exports.mjs ENTRY_GROUPS when introducing a brand-new export root directory.

Generate/check Rust schema types:

cargo check -p tusk-drift-schemas

Usage

Installing schemas in TypeScript projects

npm install @use-tusk/drift-schemas

Developing locally:

• In this repo, run npm link to create a symlink to the local package.
• In your project, run npm link @use-tusk/drift-schemas to use the local package.
• After updating the schemas, run npm run build to rebuild the package.
• Run npm unlink @use-tusk/drift-schemas to remove the local package.

Installing schemas in Golang projects

go get github.com/Use-Tusk/tusk-drift-schemas

When developing locally, add this to go.mod in your project:

replace github.com/Use-Tusk/tusk-drift-schemas => ../tusk-drift-schemas

Run go mod tidy to update the dependencies. Remember to remove this before pushing.

Installing schemas in Python projects

pip install tusk-drift-schemas

Then you can import as

# Core schemas
from tusk.drift.core.v1 import *

# Backend schemas
from tusk.drift.backend.v1 import *

Installing schemas in Rust projects

[dependencies]
tusk-drift-schemas = "0.1.30"

Then import generated protobuf types:

use tusk_drift_schemas::tusk::drift::backend::v1::ExportSpansRequest;
use tusk_drift_schemas::tusk::drift::core::v1::Span;

Releasing

Versioning policy: this repo currently uses lockstep versions across NPM (package.json), PyPI (pyproject.toml), and crates.io packages (rust/Cargo.toml).

Use the release script to create a new release:

# Patch release (0.1.22 → 0.1.23)
./scripts/release.sh

# Minor release (0.1.22 → 0.2.0)
./scripts/release.sh minor

The script will:

1. Run preflight checks (on main, up to date, no uncommitted changes)
2. Run generate and build to verify everything works
3. Update version in package.json, pyproject.toml, and rust/Cargo.toml
4. Commit, tag, and push to GitHub
5. Create a GitHub Release (which triggers the NPM & PyPI publish workflows)

[!TIP] If a broken release occurs, or you just want to test some stuff, you can supply an optional version override to the GH actions manually, like 0.1.23.dev1.

cd rust
cargo publish