Add Router to your project
This page adds the Stella Ops Router packages to a .NET solution and keeps them reproducible. You configure the feed, choose the packages for each project, pin one version for the whole Router line, restore with a lock file, check the signature of a Router package, and, on a machine without a network, install from the offline archive of a release. Getting started then builds a first gateway and service on top of it.
Prerequisites
- The .NET 10 SDK. The packages target
net10.0; a gateway host needs the ASP.NET Core runtime. - Access to the Stella Ops feed,
https://nuget.stella-ops.org/v3/index.json. Anyone can download from it without an account. - Access to nuget.org, or to a mirror of it that your organisation approves. The Router packages depend on third-party packages (for example
Microsoft.AspNetCore.Authentication.JwtBearer,RabbitMQ.ClientandStackExchange.Redis) that the Stella Ops feed does not serve.
1. Configure the feed
Put a nuget.config beside your solution. Package source mapping takes every StellaOps.* package from the Stella Ops feed and every other package from nuget.org:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="stella-ops" value="https://nuget.stella-ops.org/v3/index.json" />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</packageSources>
<packageSourceMapping>
<packageSource key="stella-ops">
<package pattern="StellaOps.*" />
</packageSource>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>
- The longest matching pattern wins: every
StellaOps.*id comes fromstella-ops, every other id fromnuget.org. A package with the same id on another feed cannot replace a Router package. <clear />keeps the sources of your user-wide and machine-wide NuGet configuration out of the restore.- To use an internal mirror instead of nuget.org, change the
valueof thenuget.orgsource and keep the mapping.
2. Choose the packages
| Project | Packages |
|---|---|
| A gateway in your own ASP.NET Core host | StellaOps.Router.Gateway.Hosting, and the server half of each transport it offers: StellaOps.Router.Transport.Tcp.Server, .Tls.Server, .Udp.Server, .RabbitMq.Server, .Messaging.Server (with the Messaging backend StellaOps.Messaging.Transport.Valkey) |
| The ready-made gateway | The .NET tool StellaOps.Router.Gateway.Host (command stellaops-router-gateway), every transport included |
| Environment-wide gateway rate limits in your own host | Add StellaOps.Router.Gateway.RateLimiting.Valkey |
| A service with endpoint classes | StellaOps.Microservice, StellaOps.Microservice.SourceGen (development dependency), one client transport: StellaOps.Router.Transport.Tcp, .Tls, .Udp, .RabbitMq or .Messaging (with StellaOps.Messaging.Transport.Valkey), and Microsoft.Extensions.Hosting |
| An existing ASP.NET Core application | StellaOps.Microservice.AspNetCore and one client transport |
| Limits inside an endpoint | StellaOps.Messaging.RateLimiting.InMemory, .Postgres or .Valkey |
| Tests through an in-process gateway | StellaOps.Router.Gateway, StellaOps.Router.Gateway.LocalInMemoryHarness, StellaOps.Router.Transport.InMemory |
StellaOps.Router.Common, StellaOps.Router.Gateway and the shared foundation libraries (for example StellaOps.Messaging) come as dependencies. Router packages lists every package with its role and licence: the client side is Apache-2.0, the gateway, the server transports, the rate limiter and the test harness are under the Router licence.
3. Pin one version for the line
Every Router package of a release has the same version and was built from the same commit, and each member names that version of the other members as its minimum. Give every Router package the same version; a mix of releases restores a combination that no release built and tested.
Versions have the form x.y.z-yyyyMMddTHHmmssZ: the release number, then the UTC time of the release. NuGet reads the time as a prerelease label, so name the version exactly. Browse the released versions at https://nuget.stella-ops.org.
Central package management keeps the line on one version. In Directory.Packages.props at the root of the solution:
<Project>
<PropertyGroup>
<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
<!-- One version for every Router package: the version of a release on the feed. -->
<StellaOpsRouterVersion>1.0.0-20261110T090000Z</StellaOpsRouterVersion>
</PropertyGroup>
<ItemGroup>
<PackageVersion Include="StellaOps.Router.Gateway.Hosting" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Router.Transport.Tls.Server" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Microservice" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Microservice.SourceGen" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="StellaOps.Router.Transport.Tls" Version="$(StellaOpsRouterVersion)" />
<PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
</ItemGroup>
</Project>
The version above shows the form only; put the version of a release the feed lists. The project files then name the packages without a version. The gateway:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="StellaOps.Router.Gateway.Hosting" />
<PackageReference Include="StellaOps.Router.Transport.Tls.Server" />
</ItemGroup>
</Project>
A service:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="StellaOps.Microservice" />
<PackageReference Include="StellaOps.Microservice.SourceGen" PrivateAssets="all" />
<PackageReference Include="StellaOps.Router.Transport.Tls" />
<PackageReference Include="Microsoft.Extensions.Hosting" />
</ItemGroup>
</Project>
To upgrade the line, change StellaOpsRouterVersion and nothing else (Upgrading).
Without central package management, name the version in every command and keep them equal:
dotnet add Contoso.Billing package StellaOps.Microservice --version 1.0.0-20261110T090000Z
dotnet add Contoso.Billing package StellaOps.Router.Transport.Tls --version 1.0.0-20261110T090000Z
The .NET tool is pinned the same way. In a tool manifest, so that every machine of the solution runs the same gateway:
dotnet new tool-manifest
dotnet tool install StellaOps.Router.Gateway.Host --version 1.0.0-20261110T090000Z
On a server, install it into a folder of its own (Deployment).
4. Restore with a lock file
A lock file records the exact version and content hash of every package the restore resolved, so every build restores the same packages. In Directory.Build.props at the root of the solution:
<Project>
<PropertyGroup>
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>
</Project>
Run
dotnet restoreand commit thepackages.lock.jsonfile it writes beside each project.In CI, restore with
dotnet restore --locked-mode.Expected result: the restore fails when the lock file no longer matches the projects’ dependencies or a package’s content hash, instead of changing the build.
After you change
StellaOpsRouterVersion, rundotnet restore --force-evaluate, review the changes of the lock files, and commit them.
5. Check the signature of a Router package
Every package on the feed is signed. NuGet does not check these signatures when it restores, so check them before a first use, in a release pipeline, or when you copy packages into an internal mirror. The commands need openssl, sha256sum and base64 in a POSIX shell (on Windows, Git Bash or WSL). The example checks StellaOps.Router.Gateway.Hosting at the version form above.
Download
cosign.pub,nuget-signing-keys.txtandnuget-signing-keys.txt.sigfromhttps://stella-ops.org/keys/into an empty folder, and check the release key id:sha256sum cosign.pubExpected result:
91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs.Check the keyring with the release key:
base64 -d nuget-signing-keys.txt.sig > keyring.sig.der openssl dgst -sha256 -verify cosign.pub -signature keyring.sig.der nuget-signing-keys.txtExpected result:
Verified OK.In the keyring, find the line that is not
revokedand whose validity window holds the timestamp of the package version (20261110T090000Z). Download the key file it names, for examplenuget-signing.pub, fromhttps://stella-ops.org/keys/, and check that its SHA-256 equals the first field of the line:sha256sum nuget-signing.pubDownload the package and its signature. The feed serves them under lower-case names:
https://nuget.stella-ops.org/v3/flatcontainer/stellaops.router.gateway.hosting/1.0.0-20261110t090000z/stellaops.router.gateway.hosting.1.0.0-20261110t090000z.nupkg, and the same address with.sigappended.Check the package with the package key:
base64 -d stellaops.router.gateway.hosting.1.0.0-20261110t090000z.nupkg.sig > package.sig.der openssl dgst -sha256 -verify nuget-signing.pub -signature package.sig.der \ stellaops.router.gateway.hosting.1.0.0-20261110t090000z.nupkgExpected result:
Verified OK. Any other output means the package is not the one the release host published: do not use it.
To check a whole release, repeat steps 4 and 5 for every Router package at that version. The key chain, its statuses and its rotation are described in Installing Stella Ops packages.
6. Install without a network
A Router release can also be published as one archive, stellaops-nuget-router-<version>.tar.gz, with its SHA-256 in stellaops-nuget-router-<version>.tar.gz.sha256 beside it. Its packages/ folder is a local NuGet feed with every Router package of the release, the Stella Ops packages they depend on, and the signature of each package; its keys/ folder holds the keys of step 5. It holds no third-party package.
Check the archive against its published digest, extract it, and check its files:
sha256sum --check stellaops-nuget-router-1.0.0-20261110T090000Z.tar.gz.sha256 tar -xzf stellaops-nuget-router-1.0.0-20261110T090000Z.tar.gz cd stellaops-nuget-router-1.0.0-20261110T090000Z sha256sum --check SHA256SUMSExpected result:
OKfor every file. These digests come from the same place as the archive: they prove that the files are complete, not who published them. The next step proves the origin.Check the keys and every package in
packages/as in steps 1 to 5 of section 5 above, with the files ofkeys/andpackages/instead of downloads. The release key id must be91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b: never accept an id the archive supplies. Every package, the tool packageStellaOps.Router.Gateway.Hostincluded, must answerVerified OK.Check that the release record names this line and version, and that the SHA-512 of each Router package equals its
member:line:cat release-record.txt sha512sum packages/*.nupkgExpected result:
line: router,version: 1.0.0-20261110T090000Z, and onemember:line per Router package whose SHA-512 matches.Map
StellaOps.*to the extractedpackages/folder innuget.config, and keep a source for every other id:<?xml version="1.0" encoding="utf-8"?> <configuration> <packageSources> <clear /> <add key="stella-ops-offline" value="stellaops-nuget-router-1.0.0-20261110T090000Z/packages" /> <add key="mirror" value="https://nuget.contoso.example/v3/index.json" /> </packageSources> <packageSourceMapping> <packageSource key="stella-ops-offline"> <package pattern="StellaOps.*" /> </packageSource> <packageSource key="mirror"> <package pattern="*" /> </packageSource> </packageSourceMapping> </configuration>A relative path is read from the folder of the
nuget.config. Themirrorsource stands for the internal mirror or local folder that holds the third-party packages.Install the .NET tool from the same folder:
dotnet tool install StellaOps.Router.Gateway.Host --version 1.0.0-20261110T090000Z \ --tool-path /opt/router/tools --add-source stellaops-nuget-router-1.0.0-20261110T090000Z/packages
Pitfalls
- Naming only the Stella Ops feed with
--source. The restore then fails on the first third-party dependency that is not in the local package cache. Keep both sources and the mapping. - Floating versions.
--prereleaseadds the newest release of that moment, andVersion="1.0.0-*"resolves to the newest release at every restore that has no lock file. Pin the exact version. - Two versions of the line. A gateway at one version and services at another, or a service with
StellaOps.Microserviceat one version and its transport at another, run a combination no release built. Keep one property for the line and upgrade gateways and services together (Upgrading). - The source generator flows to other projects. Keep
PrivateAssets="all"onStellaOps.Microservice.SourceGen, so that a project referencing the service does not run the generator. - A transport’s server half in a service, or its client half alone in a gateway. A service needs the client package (
StellaOps.Router.Transport.Tcp); a gateway needs the server package (StellaOps.Router.Transport.Tcp.Server) and stops at start-up without it.
Troubleshooting
| Symptom | Cause | Action |
|---|---|---|
Unable to find package StellaOps.Microservice | The nuget.config does not map StellaOps.* to the feed, or the version is not on the feed | Check the mapping; browse https://nuget.stella-ops.org for the versions |
| A third-party package is not found | The restore reads only the Stella Ops feed | Keep nuget.org or your mirror in packageSources and in the mapping |
NU1603, or a Router package at a version you did not ask for | A float or a minimum version resolved to another release | Pin every Router package to one version |
NU1004 in CI | The lock file differs from the resolved packages | Restore locally, review the lock file change, commit it |
| The package manager lists no versions | Prerelease versions are hidden | Name the version, or tick Include prerelease |
The gateway stops with no server-side transport plugin for it is loaded | The gateway references a client transport package only | Add the .Server package of that transport (Router gateway host) |
