Yggdrasil

This repository contains language bindings for the Unleash Yggdrasil core. The core SDK domain logic lives in that project; this repository wraps it in a Rust FFI layer and a pair of WebAssembly modules, then packages those for Java, .NET, Ruby, Python, JavaScript, Go, and PHP.

Language-specific build and test instructions live in each binding's README.

You need a Rust toolchain for everything that touches the FFI, plus the toolchain for whichever binding you're working on.

The repository ships a devenv shell (devenv.nix) that provides Rust and the GitHub CLI, wired up through direnv via .envrc. mise.toml pins Java to 21.

The Unleash client specification drives the conformance test suites. It is not vendored — you clone it yourself.

The root cargo test does not need it. The Rust tests embed their fixtures from yggdrasilffi/testfiles/. Only the language binding test suites read the specification.

Every binding except Java resolves client-specification/specifications relative to the repository root, so clone it once, here:

git clone --depth 5 --branch v6.1.0 https://github.com/Unleash/client-specification.git client-specification

/client-specification is already in .gitignore.

Java is the exception: its fetchClientSpecification Gradle task downloads and unpacks its own copy, pinned by clientSpecificationVersion in java-engine/gradle.properties. Running ./gradlew test needs no manual clone.

The shared Rust FFI layer builds and tests from the repository root:

cargo test
cargo build --release

Regenerating the C header (needed by the Go and PHP bindings) and the FlatBuffers bindings is documented in yggdrasilffi/README.md.

These have both a build workflow and a publish workflow.

JavaScript is the odd one out: it binds to the WebAssembly build via the npm package @unleash/yggdrasil-wasm, not to the FFI, and is the only binding whose CI does not compile the Rust FFI.

These exist and have READMEs, but nothing builds, tests, or releases them — there are no CI or publish workflows for any of them, and bump-yggdrasil-core.py does not touch them. Treat them as unmaintained until that changes.

Worth internalising before touching the release process:

The Rust FFI is built and released first, as a GitHub release carrying prebuilt binaries for nine targets. Each language binding pins an FFI version in its own metadata file, and at publish time downloads those prebuilt binaries rather than compiling any Rust. That is why every binding carries a yggdrasilCoreVersion-style field, and why the bump script writes the FFI version into those fields rather than the Yggdrasil core version.

Local development is the exception — build.sh in each binding compiles the FFI from source and drops it where the tests expect it.

But that's not necessarily the case for a given patch - these are intentionally cleaved to allow the binding versions to evolve without needing a binary version increment. For example, if you wanted to say... tweak the Python bindings public API to collapse a few functions into a single call, you would need to version the Python bindings as a new major version but touching the FFI layers would be silly and unnecessary.

Use the release helper when updating the dependency on the Yggdrasil crate:

./scripts/bump-yggdrasil-core.py 0.21.3 --dry-run
./scripts/bump-yggdrasil-core.py 0.21.3

--dry-run prints the plan and writes nothing. The target version must be strictly greater than the current highest pin, so re-running with the same version fails.

A run makes four kinds of change:

1. Sets the unleash-yggdrasil pin to the given version in three manifests: yggdrasilffi/Cargo.toml, pure-wasm/Cargo.toml, yggdrasilwasm/Cargo.toml.
2. Patch-bumps yggdrasilffi's own package version in yggdrasilffi/Cargo.toml.
3. Points the four FFI artifact fields at that new FFI version — yggdrasilCoreVersion in java-engine/gradle.properties, __yggdrasil_core_version__ in python-engine/yggdrasil_engine/__init__.py, yggdrasil_core_version in the Ruby gemspec metadata, and <YggdrasilCoreVersion> in the .NET csproj.
4. Patch-bumps the Java, Python, Ruby and .NET package versions.

It does not touch javascript-engine, go-engine or php-engine.

Nothing releases on a tag push. Every publish workflow is workflow_dispatch only, and the workflows create tags rather than react to them. Releasing is two stages, and the FFI always goes first.

Run the Release FFI and Upload Binaries workflow (.github/workflows/release-new-ffi-version.yaml).

It reads version from the [package] section of yggdrasilffi/Cargo.toml, pushes the tag yggdrasilffi-v<version>, generates a changelog with git-cliff, cross-builds nine targets, and uploads the binaries as release assets.

You only need to bump yggdrasilffi/Cargo.toml by hand when releasing the FFI without a core bump. If you ran bump-yggdrasil-core.py, the bump is already in the commit — bumping again would skip a version.

Dispatch the relevant workflow: Publish Java, Publish .NET, Publish Ruby, Publish Python, or Publish JavaScript. Each reads its pinned FFI version, runs gh release download "yggdrasilffi-v$CORE_VERSION" to fetch the binaries from stage 1, publishes to its registry, and tags the repo <lang>-engine-v<version>.

Despite its name, Clippy analysis (Code Quality) is the main Rust test workflow — it runs cargo fmt --check, cargo clippy with SARIF upload, and cargo test --all-features.

There is no CI for go-engine, php-engine, pure-wasm or yggdrasilwasm.