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

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>

2. Choose the packages

ProjectPackages
A gateway in your own ASP.NET Core hostStellaOps.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 gatewayThe .NET tool StellaOps.Router.Gateway.Host (command stellaops-router-gateway), every transport included
Environment-wide gateway rate limits in your own hostAdd StellaOps.Router.Gateway.RateLimiting.Valkey
A service with endpoint classesStellaOps.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 applicationStellaOps.Microservice.AspNetCore and one client transport
Limits inside an endpointStellaOps.Messaging.RateLimiting.InMemory, .Postgres or .Valkey
Tests through an in-process gatewayStellaOps.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>
  1. Run dotnet restore and commit the packages.lock.json file it writes beside each project.

  2. 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.

  3. After you change StellaOpsRouterVersion, run dotnet 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.

  1. Download cosign.pub, nuget-signing-keys.txt and nuget-signing-keys.txt.sig from https://stella-ops.org/keys/ into an empty folder, and check the release key id:

    sha256sum cosign.pub
    

    Expected result: 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b. Stop if it differs.

  2. 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.txt
    

    Expected result: Verified OK.

  3. In the keyring, find the line that is not revoked and whose validity window holds the timestamp of the package version (20261110T090000Z). Download the key file it names, for example nuget-signing.pub, from https://stella-ops.org/keys/, and check that its SHA-256 equals the first field of the line:

    sha256sum nuget-signing.pub
    
  4. Download 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 .sig appended.

  5. 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.nupkg
    

    Expected 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.

  1. 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 SHA256SUMS
    

    Expected result: OK for 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.

  2. Check the keys and every package in packages/ as in steps 1 to 5 of section 5 above, with the files of keys/ and packages/ instead of downloads. The release key id must be 91481209caf0499d1063e2d5955bb5c151466a9258c0b4c2ec76e5db52e3409b: never accept an id the archive supplies. Every package, the tool package StellaOps.Router.Gateway.Host included, must answer Verified OK.

  3. 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/*.nupkg
    

    Expected result: line: router, version: 1.0.0-20261110T090000Z, and one member: line per Router package whose SHA-512 matches.

  4. Map StellaOps.* to the extracted packages/ folder in nuget.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. The mirror source stands for the internal mirror or local folder that holds the third-party packages.

  5. 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

Troubleshooting

SymptomCauseAction
Unable to find package StellaOps.MicroserviceThe nuget.config does not map StellaOps.* to the feed, or the version is not on the feedCheck the mapping; browse https://nuget.stella-ops.org for the versions
A third-party package is not foundThe restore reads only the Stella Ops feedKeep nuget.org or your mirror in packageSources and in the mapping
NU1603, or a Router package at a version you did not ask forA float or a minimum version resolved to another releasePin every Router package to one version
NU1004 in CIThe lock file differs from the resolved packagesRestore locally, review the lock file change, commit it
The package manager lists no versionsPrerelease versions are hiddenName the version, or tick Include prerelease
The gateway stops with no server-side transport plugin for it is loadedThe gateway references a client transport package onlyAdd the .Server package of that transport (Router gateway host)