MaksIT.Nats.Client 2.0.0

MaksIT.Nats

MaksIT.Nats is a product foundation for NATS JetStream administration using NATS.Net v3.

It includes a DI-friendly client library, an ASP.NET Core Admin API host, and a WebUI fronted by YARP. Identity users, refresh tokens, and user entity scopes are persisted in PostgreSQL.

Installation

dotnet add package MaksIT.Nats.Client

Usage

Implement INatsClientConfiguration in the host (URL, optional monitoring URL, allowlisted streams), then register services:

using MaksIT.Nats.Client.Extensions;

builder.Services.RegisterNatsJetStreamAdmin<MyNatsConfigurationAdapter>();

Or register configuration manually:

builder.Services.AddSingleton<INatsClientConfiguration>(sp => /* ... */);
builder.Services.RegisterNatsJetStreamAdmin();

Inject INatsJetStreamService for:

• GetHealthAsync() / GetAccountInfoAsync() — health and account JetStream readiness (limits/usage; not broker enablement)
• EnsureStreamAsync() / UpdateStreamAsync() / ListStreamsAsync() / GetStreamAsync() / DeleteStreamAsync() / PurgeStreamAsync() — stream administration
• ListConsumersAsync() / GetConsumerAsync() / CreateConsumerAsync() / UpdateConsumerAsync() / DeleteConsumerAsync() / pause / resume / reset — consumer administration
• SearchStreamMessagesAsync() — paginated message browse (newest first; GetDirect then Get fallback)
• DeleteStreamMessageAsync() — delete by sequence

Also register INatsKeyValueAdminService and INatsObjectStoreAdminService for KV buckets/keys and Object Store buckets/objects.

All operations return MaksIT.Results Result types. Stream and consumer create/update accept NATS.Net v3 StreamConfig and ConsumerConfig.

Admin API host

src/MaksIT.Nats exposes Swagger and authenticated JetStream, KV, and Object Store administration endpoints. Login is at /api/identity/login. Settings bind from the Configuration section into Configuration / NatsEngineConfiguration: connection string, Admin, JwtSettingsConfiguration, and nested Nats broker client settings. Secrets belong in /secrets/appsecrets.json; non-secrets in /configMap/appsettings.json. On startup the host ensures the identity schema and seeds the configured administrator under a MaksIT.HAMode PostgreSQL lease (nats-bootstrap on app_runtime_leases), so only one replica performs bootstrap.

HA: Symmetric server replicas share one PostgreSQL database. Runtime coordination uses MaksIT.HAMode (IRuntimeInstanceId, IRuntimeLeaseService). In Kubernetes, set POD_NAME (Helm chart injects metadata.name) so lease holder ids are stable per pod. Default Helm replicas remains 1; raise it when you run multi-replica behind a load balancer with a shared DB.

Set Configuration:NatsEngineConfiguration:Nats:Url, MonitoringUrl, and optionally JetStreamDomain. An empty Streams list permits account-wide stream, consumer, and message administration (Compose default). A non-empty Streams list restricts message search/delete to those exact stream names (safer for embedded hosts such as cicd) and drives per-stream Home health rows.

JetStream on the broker is enabled by Compose (-js) or Helm (jetstream.enabled) — the Admin UI cannot toggle the NATS process. Home shows account JetStream readiness via $JS.API.INFO (available, domain, streams/consumers, memory/storage vs limits).

The WebUI side menu is sectioned (Overview / JetStream / Storage / Access). Streams supports create/edit with richer StreamConfig, detail pages for purge, consumers (including pause/resume/reset), and message browse/delete. KV buckets and Object stores pages manage JetStream-backed stores (Object Store supports put via UTF-8 or base64 payload; large binary file upload UI is not included in this release).

Deployment

Start a local NATS broker with JetStream and the API:

cd src
docker compose up --build

The NATS Admin UI and proxied API are available at http://localhost:8080; Swagger is at http://localhost:8080/swagger. NATS client and monitoring ports are 4222 and 8222; PostgreSQL is exposed on 5435 and pgAdmin on 8082. After client or API changes, rebuild the server service (docker compose up --build server) so the WebUI proxies the updated JetStream endpoints.

Compose persists PostgreSQL data at D:\Compose\MaksIT.Nats\postgresql\data, pgAdmin state at D:\Compose\MaksIT.Nats\postgresql\pgadmin-data, and JetStream data at D:\Compose\MaksIT.Nats\nats\data. Before starting Compose, copy:

• src\postgresql\servers.json.example → D:\Compose\MaksIT.Nats\postgresql\servers.json
• src\MaksIT.Nats\appsettings.json → D:\Compose\MaksIT.Nats\configMap\appsettings.json (fill Nats URLs for Compose, e.g. nats://nats:4222 / http://nats:8222)
• Create D:\Compose\MaksIT.Nats\secrets\appsecrets.json with secrets only (ConnectionString, Admin, JwtSecret, PasswordPepper) — use empty strings in the repo template; set real values locally. Shape matches Configuration:NatsEngineConfiguration in appsettings.json.

The Helm chart at src/helm installs only the API. It points to an external NATS deployment and external PostgreSQL. Set natsServerSecrets.connectionString to a shared PostgreSQL server connection string using Database=nats, Username=nats, and its corresponding password. See src/helm/README.md.

Build and test

Local (host SDK):

cd src && dotnet build MaksIT.Nats.slnx
utils\Invoke-TestEngine.bat

Runs DotNetTest on the host SDK (Coverlet → QualityGate → CoverageBadges). No container required for compile or test.

Release:

utils\Invoke-ReleasePackage-Single.bat

Packs MaksIT.Nats.Client with host DotNetPack. Docker/Podman are used only to push server/WebUI/reverseproxy images and the Helm chart (when publish guard and secrets allow).

Release

See CONTRIBUTING.md. Version is defined in src/MaksIT.Nats.Client/MaksIT.Nats.Client.csproj.

License

See LICENSE.md.