Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

ci(release): publish Rust crates from release tags (#329)

nachiketb-nvidia511167810065
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 01910bfe2..d705e3732 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -59,13 +59,24 @@ jobs:
with open("pyproject.toml", "rb") as file:
pyproject = tomllib.load(file)
+ with open("Cargo.toml", "rb") as file:
+ cargo = tomllib.load(file)
+
package_version = pyproject["project"]["version"]
+ workspace_version = cargo["workspace"]["package"]["version"]
+ if workspace_version != package_version:
+ raise SystemExit(
+ "Python package version "
+ f"{package_version!r} does not match Rust workspace version "
+ f"{workspace_version!r}"
+ )
+
expected = f"v{package_version}"
if tag != expected:
raise SystemExit(
f"release tag {tag!r} does not match pyproject version {package_version!r}"
)
- print(f"release tag {tag} matches pyproject version {package_version}")
+ print(f"release tag {tag} matches Python and Rust version {package_version}")
PY
python-release-checks:
@@ -417,7 +428,7 @@ jobs:
publish:
name: Publish distributions
if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
- needs: [source-dist, wheels]
+ needs: [source-dist, wheels, publish-rust-server]
runs-on: ubuntu-latest
environment: pypi
permissions:
@@ -438,3 +449,100 @@ jobs:
- name: Create GitHub Release
uses: softprops/action-gh-release@v2
+
+ publish-rust-protocol:
+ name: Publish switchyard-protocol
+ if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+ needs: [source-dist, wheels]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Publish crate
+ env:
+ CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+ run: cargo publish --locked --package switchyard-protocol
+
+ publish-rust-foundations:
+ name: Publish ${{ matrix.crate }}
+ if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+ needs: [publish-rust-protocol]
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ crate: [switchyard-libsy, switchyard-translation]
+ steps:
+ - uses: actions/checkout@v4
+ - name: Wait for registry dependencies
+ shell: bash
+ run: |
+ set -euo pipefail
+ version="${GITHUB_REF_NAME#v}"
+ for attempt in {1..30}; do
+ cargo info --registry crates-io "switchyard-protocol@${version}" >/dev/null 2>&1 \
+ && exit 0
+ echo "Waiting for switchyard-protocol ${version} (${attempt}/30)"
+ sleep 10
+ done
+ echo "switchyard-protocol ${version} did not reach the crates.io index" >&2
+ exit 1
+ - name: Publish crate
+ env:
+ CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+ run: cargo publish --locked --package "${{ matrix.crate }}"
+
+ publish-rust-client:
+ name: Publish switchyard-llm-client
+ if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+ needs: [publish-rust-foundations]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Wait for registry dependencies
+ shell: bash
+ run: |
+ set -euo pipefail
+ version="${GITHUB_REF_NAME#v}"
+ for attempt in {1..30}; do
+ ready=true
+ for crate in switchyard-libsy switchyard-translation; do
+ cargo info --registry crates-io "${crate}@${version}" >/dev/null 2>&1 \
+ || ready=false
+ done
+ if [[ "${ready}" == true ]]; then
+ exit 0
+ fi
+ echo "Waiting for Rust foundation crates ${version} (${attempt}/30)"
+ sleep 10
+ done
+ echo "Rust foundation crates ${version} did not reach the crates.io index" >&2
+ exit 1
+ - name: Publish crate
+ env:
+ CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+ run: cargo publish --locked --package switchyard-llm-client
+
+ publish-rust-server:
+ name: Publish switchyard-server
+ if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+ needs: [publish-rust-client]
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Wait for registry dependencies
+ shell: bash
+ run: |
+ set -euo pipefail
+ version="${GITHUB_REF_NAME#v}"
+ for attempt in {1..30}; do
+ cargo info --registry crates-io "switchyard-llm-client@${version}" >/dev/null 2>&1 \
+ && exit 0
+ echo "Waiting for switchyard-llm-client ${version} (${attempt}/30)"
+ sleep 10
+ done
+ echo "switchyard-llm-client ${version} did not reach the crates.io index" >&2
+ exit 1
+ - name: Publish crate
+ env:
+ CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+ run: cargo publish --locked --package switchyard-server
diff --git a/README.md b/README.md
index 5226b9b20..7ead4efd3 100644
--- a/README.md
+++ b/README.md
@@ -67,19 +67,16 @@ switchyard launch claude --model my-route --config routes.toml
### Server Path
-Use this path to build and run the standalone Rust proxy. Install
-[Rust with Cargo](https://rust-lang.org/tools/install/), then build the release
-binary from source:
+Use this path to install and run the standalone Rust proxy. Install
+[Rust with Cargo](https://rust-lang.org/tools/install/), then install the
+published binary:
```bash
-git clone https://github.com/NVIDIA-NeMo/Switchyard.git
-cd Switchyard
-cargo build --locked --release -p switchyard-server
-./target/release/switchyard-server --help
+cargo install --locked switchyard-server
+switchyard-server --help
```
-Prebuilt binaries are not published yet. `rustup` installs the pinned toolchain
-automatically when you run Cargo from the repository.
+Cargo builds the release binary and installs it into `~/.cargo/bin` by default.
Create `routes.toml` using the
[Getting Started guide](docs/getting_started.md#server-path), then validate it
@@ -87,8 +84,8 @@ and start the server:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml --host 127.0.0.1 --port 4000
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml --host 127.0.0.1 --port 4000
```
Verify the proxy in another terminal:
diff --git a/crates/libsy-llm-client/Cargo.toml b/crates/libsy-llm-client/Cargo.toml
index 359019aef..0bba91472 100644
--- a/crates/libsy-llm-client/Cargo.toml
+++ b/crates/libsy-llm-client/Cargo.toml
@@ -7,9 +7,14 @@ version.workspace = true
description = "HTTP LLM client speaking Switchyard's neutral IR directly"
authors.workspace = true
edition.workspace = true
+homepage = "https://github.com/NVIDIA-NeMo/Switchyard"
license.workspace = true
+readme = "README.md"
repository.workspace = true
rust-version.workspace = true
+documentation = "https://docs.rs/switchyard-llm-client"
+keywords = ["llm", "client", "openai", "anthropic"]
+publish = ["crates-io"]
[dependencies]
switchyard-libsy.workspace = true
diff --git a/crates/switchyard-server/Cargo.toml b/crates/switchyard-server/Cargo.toml
index 5d8a44939..1b22546a8 100644
--- a/crates/switchyard-server/Cargo.toml
+++ b/crates/switchyard-server/Cargo.toml
@@ -7,9 +7,14 @@ version.workspace = true
description = "Rust HTTP server surface for libsy algorithms"
authors.workspace = true
edition.workspace = true
+homepage = "https://github.com/NVIDIA-NeMo/Switchyard"
license.workspace = true
+readme = "README.md"
repository.workspace = true
rust-version.workspace = true
+documentation = "https://docs.rs/switchyard-server"
+keywords = ["llm", "proxy", "routing", "openai", "anthropic"]
+publish = ["crates-io"]
[dependencies]
async-stream.workspace = true
@@ -20,7 +25,7 @@ rustls = { version = "0.23", default-features = false, features = ["aws-lc-rs",
clap = { version = "4", features = ["derive", "env"] }
futures-util.workspace = true
http.workspace = true
-libsy = { package = "switchyard-libsy", path = "../libsy" }
+libsy = { package = "switchyard-libsy", path = "../libsy", version = "0.2.0" }
opentelemetry = { version = "0.32", default-features = false, features = ["metrics", "trace"] }
opentelemetry-otlp = { version = "0.32", default-features = false, features = ["http-proto", "metrics", "reqwest-blocking-client", "reqwest-rustls", "trace"] }
opentelemetry-prometheus = "0.32"
diff --git a/crates/switchyard-server/README.md b/crates/switchyard-server/README.md
index afab8f986..221be2196 100644
--- a/crates/switchyard-server/README.md
+++ b/crates/switchyard-server/README.md
@@ -55,7 +55,8 @@ confidence_threshold = 0.5
```bash
export API_KEY="..."
-cargo run -p switchyard-server -- --config routes.toml
+cargo install --locked switchyard-server
+switchyard-server --config routes.toml
```
Ctrl+C and Unix `SIGTERM` stop new connections and allow active requests to drain for up to
diff --git a/docs/cli_reference.md b/docs/cli_reference.md
index dd2c6aae0..9f50c693e 100644
--- a/docs/cli_reference.md
+++ b/docs/cli_reference.md
@@ -50,9 +50,8 @@ This command does not install or run the standalone `switchyard-server` binary.
## Server Path: `switchyard-server`
-Build the standalone binary with
-`cargo build --locked --release -p switchyard-server`. It reads the same native
-TOML deployment schema accepted by the launcher.
+Install the standalone binary with `cargo install --locked switchyard-server`.
+It reads the same native TOML deployment schema accepted by the launcher.
### Usage
@@ -60,9 +59,6 @@ TOML deployment schema accepted by the launcher.
switchyard-server --config <deployment.toml> [options]
```
-When built from the repository, invoke it as
-`./target/release/switchyard-server`.
-
| Option | Default | Purpose |
|---|---|---|
| `--config PATH` | Required | TOML file defining LLM clients, targets, and algorithm routes. |
@@ -80,8 +76,8 @@ When built from the repository, invoke it as
Validate a deployment, then start the proxy:
```bash
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
@@ -102,7 +98,7 @@ switchyard launch claude --model my-route --config routes.toml
```
The CLI does not save provider credentials or deployment paths.
-Use `./target/release/switchyard-server --config routes.toml --dry-run` to
+Use `switchyard-server --config routes.toml --dry-run` to
validate a native deployment before starting the standalone server.
## Related Documentation
diff --git a/docs/getting_started.md b/docs/getting_started.md
index b737cf01d..b6cb82d8c 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -109,20 +109,16 @@ cargo --version
uv --version
```
-### Build the server
+### Install the server
-Build the Rust server from source:
+Install the Rust server from crates.io:
```bash
-git clone https://github.com/NVIDIA-NeMo/Switchyard.git
-cd Switchyard
-cargo build --locked --release -p switchyard-server
-./target/release/switchyard-server --help
+cargo install --locked switchyard-server
+switchyard-server --help
```
-The repository pins Rust `1.96.1` in `rust-toolchain.toml`; `rustup` selects and
-installs it automatically when Cargo runs from the repository. Prebuilt Rust
-binaries are not published yet.
+Cargo builds the release binary and installs it into `~/.cargo/bin` by default.
### Configure
@@ -168,8 +164,8 @@ socket, then start the release binary:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
@@ -213,7 +209,7 @@ the complete TOML schema, route options, TLS, and metrics.
```bash
test -n "$OPENROUTER_API_KEY" && echo "key is set" || echo "key is missing"
-./target/release/switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml --dry-run
```
Confirm that `api_key_env` in `routes.toml` names the environment variable you
diff --git a/docs/internal/release_workflow.md b/docs/internal/release_workflow.md
index 8be709d32..25d470a70 100644
--- a/docs/internal/release_workflow.md
+++ b/docs/internal/release_workflow.md
@@ -8,7 +8,8 @@ Switchyard currently follows the OSS-style NeMo path for GitHub builds:
- manual dev builds create one Linux x86_64 wheel as a one-day GitHub Actions artifact;
- manual dev matrix builds create the full sdist and wheel set as GitHub Actions artifacts;
- root `vMAJOR.MINOR.PATCH` tags run the complete release validation and wheel matrix;
-- public PyPI/GitHub publishing happens only from approved `vMAJOR.MINOR.PATCH` tag releases.
+- public PyPI, crates.io, and GitHub publishing happens only from approved
+ `vMAJOR.MINOR.PATCH` tag releases.
Wheel metadata uses the public distribution name `nemo-switchyard`, while the Python import and CLI
stay `switchyard`.
@@ -69,7 +70,8 @@ Create a root `vMAJOR.MINOR.PATCH` tag only when a real release has been approve
- native wheel smoke installs where the runner can execute the artifact.
The workflow rejects release tags that do not exactly match `pyproject.toml`'s package version. For
-example, package version `0.0.1` must be released with the `v0.0.1` tag.
+example, package version `0.2.0` must be released with the `v0.2.0` tag. The Rust workspace and
+Python package versions must also match.
The official `publish` job uses `uv publish --trusted-publishing always`, so PyPI project creation
and uploads require a matching pending trusted publisher:
@@ -85,6 +87,19 @@ and uploads require a matching pending trusted publisher:
Do not create a root release tag until the PyPI pending publisher and GitHub `pypi` environment are
ready.
+The same tag publishes these crates to crates.io in dependency order:
+
+1. `switchyard-protocol`
+2. `switchyard-libsy`
+3. `switchyard-translation`
+4. `switchyard-llm-client`
+5. `switchyard-server`
+
+Add a repository Actions secret named `CARGO_REGISTRY_TOKEN` containing a crates.io API token that
+can publish all five crates and create new crates. The job waits for each version to reach the
+crates.io index before publishing its dependents. If publication stops partway through, use
+GitHub's **Re-run failed jobs** action so successful crate jobs are not repeated.
+
## Local Metadata Helper
To preview the metadata stamp locally:
diff --git a/docs/routing_algorithms/escalation_router_routing.md b/docs/routing_algorithms/escalation_router_routing.md
index 4d3073c05..e2246144e 100644
--- a/docs/routing_algorithms/escalation_router_routing.md
+++ b/docs/routing_algorithms/escalation_router_routing.md
@@ -117,14 +117,14 @@ resets the streak to zero.
## Run the route
-After building the Rust server, as described in
-[Getting Started](../getting_started.md#build-the-server), export the provider
+After installing the Rust server, as described in
+[Getting Started](../getting_started.md#install-the-server), export the provider
credential, validate the configuration, and start the binary:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
diff --git a/docs/routing_algorithms/llm_classifier_routing.md b/docs/routing_algorithms/llm_classifier_routing.md
index 5bb000fcb..e3f750974 100644
--- a/docs/routing_algorithms/llm_classifier_routing.md
+++ b/docs/routing_algorithms/llm_classifier_routing.md
@@ -209,14 +209,14 @@ user-message text.
## Run the route
-After [building the Rust server](../getting_started.md#build-the-server), export
+After [installing the Rust server](../getting_started.md#install-the-server), export
the provider credential, validate the configuration, and start the release
binary:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
diff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.md
index c595cab6f..e5cd4299f 100644
--- a/docs/routing_algorithms/overview.md
+++ b/docs/routing_algorithms/overview.md
@@ -111,14 +111,14 @@ the configured endpoint.
## Run a deployment
-After building the Rust server, as described in
-[Getting Started](../getting_started.md#build-the-server), export the provider
+After installing the Rust server, as described in
+[Getting Started](../getting_started.md#install-the-server), export the provider
credential, validate the configuration, and start the binary:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
diff --git a/docs/routing_algorithms/random_routing.md b/docs/routing_algorithms/random_routing.md
index 3af82f12e..e889afce2 100644
--- a/docs/routing_algorithms/random_routing.md
+++ b/docs/routing_algorithms/random_routing.md
@@ -77,14 +77,14 @@ therefore use different targets.
## Run the route
-After [building the Rust server](../getting_started.md#build-the-server), export
+After [installing the Rust server](../getting_started.md#install-the-server), export
the provider credential, validate the configuration, and start the release
binary:
```bash
export OPENROUTER_API_KEY="your-openrouter-key" # pragma: allowlist secret
-./target/release/switchyard-server --config routes.toml --dry-run
-./target/release/switchyard-server --config routes.toml \
+switchyard-server --config routes.toml --dry-run
+switchyard-server --config routes.toml \
--host 127.0.0.1 --port 4000
```
diff --git a/tests/getting_started/test_getting_started.py b/tests/getting_started/test_getting_started.py
index e8ba4581f..d862ac9ad 100644
--- a/tests/getting_started/test_getting_started.py
+++ b/tests/getting_started/test_getting_started.py
@@ -14,8 +14,8 @@ def test_getting_started_documents_current_paths() -> None:
assert guide.index("## Launcher Path") < guide.index("## Server Path")
assert 'uv tool install --python 3.12 "nemo-switchyard[cli,server]"' in guide
assert "switchyard launch claude --model switchyard" in guide
- assert "cargo build --locked --release -p switchyard-server" in guide
- assert "./target/release/switchyard-server --config routes.toml --dry-run" in guide
+ assert "cargo install --locked switchyard-server" in guide
+ assert "switchyard-server --config routes.toml --dry-run" in guide
for legacy_command in (
"switchyard configure",
diff --git a/tests/readme/test_readme.py b/tests/readme/test_readme.py
index 3aebc93c2..fc7cbcd96 100644
--- a/tests/readme/test_readme.py
+++ b/tests/readme/test_readme.py
@@ -12,8 +12,8 @@ def test_readme_documents_current_paths() -> None:
assert readme.index("### Launcher Path") < readme.index("### Server Path")
assert 'uv tool install --python 3.12 "nemo-switchyard[cli,server]"' in readme
assert "switchyard launch claude --model switchyard" in readme
- assert "cargo build --locked --release -p switchyard-server" in readme
- assert "./target/release/switchyard-server --config routes.toml --dry-run" in readme
+ assert "cargo install --locked switchyard-server" in readme
+ assert "switchyard-server --config routes.toml --dry-run" in readme
for legacy_command in (
"switchyard configure",