Fluens.Web.Discovery 0.7.4

Fluens.Web.Discovery

Consul self-registration and a central, blocking-query-refreshed service catalog for Fluens web applications that start on dynamic ports.

The library owns both halves of discovery per ADR-0004:

• Registration (write) — the application registers itself into Consul after Kestrel binds, using its real post-start address and port, and deregisters on shutdown. A self-healing reconciler re-applies the held registration on an interval (idempotent upsert), surviving Consul auto-deregistration after transient unhealth.
• Resolution (read) — a single long-polling worker keeps an in-memory IServiceCatalog (the contract lives in Fluens.Web) converged with Consul; the mesh and HTTP clients read the catalog snapshot instead of each issuing their own Consul query. The worker watches both registration topology and health-state transitions, so a peer recovering from critical is picked up within seconds without a topology change.

The library owns the fluens- meta/tag namespace (DiscoveryMeta: fluens-version, fluens-cluster). The hyphen separator is DNS-safe and legal in both Consul meta keys (which reject .) and tags.

Install

dotnet add package Fluens.Web.Discovery

Usage

builder.AddFluens()
    .AddWeb()
    .AddDiscovery(); // reads "Fluens:Web:Discovery"; no-op when Enabled == false

Configuration (appsettings.json):

{
  "Fluens": {
    "Web": {
      "Discovery": {
        "Enabled": true,
        "Url": "http://localhost:8500",
        "AdvertisedHost": null,
        "ClusterId": "cluster-1",
        "Tags": [ "grpc" ],
        "Meta": { "region": "eu-west" },
        "ReregisterIntervalSeconds": 30,
        "HealthCheckPath": "/health",
        "HealthCheckIntervalSeconds": 10,
        "DeregisterCriticalServiceAfterSeconds": 60,
        "CatalogWaitSeconds": 300
      }
    }
  }
}

Options

Address normalization

The advertised address is computed once from IServerAddressesFeature and held. Wildcard/loopback bind tokens ([::], [::1], *, 0.0.0.0) are normalized to localhost. Set AdvertisedHost to advertise a routable host instead of the bound one.

Health check

A health check is registered only when a source is configured, with precedence:

1. an explicit health path passed to the registration call,
2. else IHealthEndpointInfo resolved from DI (e.g. provided by Fluens.Web.Healthchecks),
3. else none.

When present it is a Consul HTTP check with DeregisterCriticalServiceAfter as the native auto-cleanup.

Resolution

AddDiscovery() registers a singleton IServiceCatalog (ServiceCatalog) and a CatalogRefreshWorker. The worker runs two concurrent Consul blocking queries — Catalog.Services (registration topology) and Health.State(HealthStatus.Any) (health transitions), each on its own WaitIndex and bounded by CatalogWaitSeconds — and rebuilds the snapshot as soon as either advances. It then reads the current topology plus per-service Health.Service(passingOnly), assembles an immutable snapshot, and swaps it into the catalog. Reacting to the health index means a peer's critical→passing transition wakes a refresh within seconds even when no service was added or removed. Consumers read the catalog directly:

// Resolve a single healthy endpoint (round-robins across instances).
ResolvedServiceEndpoint? endpoint = catalog.Resolve("orders.eu");

// Enumerate services by tag (and optional meta) — e.g. discover mesh peers.
IReadOnlyList<DiscoveredService> peers = catalog.List(
    "fluens-mesh",
    new Dictionary<string, string> { ["fluens-cluster"] = "cluster-1" });

// React to topology changes.
IChangeToken token = catalog.GetChangeToken();

Sibling libraries that require the catalog (for example the messaging mesh) call the idempotent TryAddDiscovery() — it wires discovery exactly once, so the catalog worker is never registered twice.

ADR-0007 — endpoint resolution only. The catalog answers where to deliver now; it is not the source of mesh peer subscriptions. The messaging mesh stores subscriptions in a durable Consul-KV store (fluens/<ClusterId>/subscriptions/<app>) read over the same IConsulClient this library registers, so a peer going health-critical drops from the catalog without dropping from the mesh's owed-app set. Because that KV store is not re-derivable from a fresh Consul, run Consul persistently (-server -bootstrap-expect=1 -data-dir + a named volume), never -dev, wherever mesh durability is load-bearing.

Contributor model

A sibling library can advertise additive tags/meta into this application's registration without Discovery depending on it, by registering an IServiceRegistrationContributor:

internal sealed class MeshContributor : IServiceRegistrationContributor
{
    public ServiceRegistrationContribution Contribute() =>
        new(["fluens-mesh"], new Dictionary<string, string>(StringComparer.Ordinal));
}

services.AddSingleton<IServiceRegistrationContributor, MeshContributor>();

Contributions merge into the descriptor with auto → contributor → user precedence; tags are unioned with ordinal de-duplication. The mesh uses this to add the fluens-mesh tag so peers can be discovered by tag.