Orbita examples

Runnable, failure-verified examples for Orbita. They use generated gRPC stubs directly. There is no Orbita client library here.

The first milestone covers a fenced lock and fenced leader election. Each example uses a scoped tenant credential and includes a verifier that kills a real holder or leader.

Requirements

• Python 3.11 or newer
• Docker with Compose

Run

make setup
make up
make verify
make down

make setup creates .venv, downloads the pinned Orbita protobuf files, and generates Python stubs under the ignored generated/ directory. make up starts one authenticated development node at 127.0.0.1:7100.

The failure demos can also use the production-shaped three-node profile:

make cluster-up
make cluster-verify
make cluster-down

That profile exposes HAProxy at 127.0.0.1:7200. The explicit haproxy Compose target starts only the three cluster nodes and their dependencies.

Version pin

orbita.pin is the only Orbita version input. During prerelease it has the form <image-tag>@<source-commit>. The image uses the tag while setup fetches protobuf files from that exact commit, so a moving branch cannot change the generated wire contract.

The first release changes that one line to 0.1.0. A release pin resolves source from the immutable v0.1.0 Git tag. make setup writes the resolved image to the ignored .env file used by Compose.

The current Orbita source repository and 0.1.0-dev GHCR package require authentication. During prerelease, setup reads GH_TOKEN/GITHUB_TOKEN or an existing gh auth login to fetch the pinned source. CI needs an ORBITA_SOURCE_TOKEN repository secret with read access to that repository and its GHCR package. The workflow does not substitute a mock or another build, so missing access fails clearly. These credentials are no longer needed once the source and release image are public. GitHub does not pass this secret to fork pull requests, so an external contribution needs a maintainer rerun from a trusted branch during prerelease.

Boundaries

common/client.py only creates a channel, adds Bearer metadata, and retries UNAVAILABLE with bounded backoff. It does not route requests, cache topology, or hide the generated API. Provisioning is separate in common/provision.py and uses the local demo root credential only to create a keyspace and tenant credential.

There are deliberately no benchmarks or Kubernetes manifests in this repository.