Configuration Supervisor

FxMap Supervisor

Automatic failure recovery and resilience for message-based transports with exponential backoff, circuit breaker protection, and health state tracking.

What is Supervisor?

The Supervisor pattern in FxMap provides automatic failure recovery for message-based transports (NATS, RabbitMQ, Kafka, gRPC, Azure Service Bus, AWS SQS). When a transport connection fails, the supervisor automatically attempts to restart it with intelligent backoff strategies.

Auto Recovery

Automatically restarts failed transport connections with exponential backoff

Circuit Breaker

Prevents cascade failures by stopping restart attempts when limits are reached

Health Tracking

Monitor server health states: Healthy, Degraded, or Failed

Basic Configuration

Configure the supervisor when setting up your FxMap services:

builder.Services.AddFxMap(cfg =>
{
    cfg.AddEntitiesFromAssemblyContaining<SomeEntityAssemblyMarker>();
    cfg.AddProfilesFromAssemblyContaining<SomeProfileAssemblyMarker>();
 
    // Configure Supervisor
    cfg.ConfigureSupervisor(opts =>
    {
        opts.Strategy = SupervisionStrategy.OneForOne;
        opts.MaxRestarts = 5;
        opts.EnableCircuitBreaker = true;
    });
})
.AddNats(opts => opts.NatsServerUrl("nats://localhost:4222"));

Supervision Strategies

Strategy	Description	Use Case
OneForOne	Only the failed server is restarted	Independent transports
OneForAll	All servers restart when one fails	Tightly coupled services
RestForOne	Failed server and those started after it restart	Sequential dependencies

Fixed in 4.1.5

• A server of NATS, SQS or Kafka can be started again after the supervisor stopped it. Before, the next start failed with ObjectDisposedException. The default strategy (OneForOne) never stops a server, so it was not affected.
• After the restart of every server with OneForAll, a server that was running was reported as Stopped.
• RestForOne restarts the servers registered after the failed one, in the order of their registration. It used the order of a dictionary.

A known limit of NATS: a request sent in the few milliseconds after a server was stopped can reach its subscription before the NATS server has processed the unsubscribe, and it ends at the request timeout. It matters only when a server is stopped and started again at once, as OneForAll and RestForOne do.

Configuration Options

cfg.ConfigureSupervisor(opts =>
{
    // Supervision strategy
    opts.Strategy = SupervisionStrategy.OneForOne;
 
    // Maximum restart attempts within the time window
    opts.MaxRestarts = 5;
 
    // Time window for counting restarts (default: 60 seconds)
    opts.MaxRestartWindow = TimeSpan.FromSeconds(60);
 
    // Initial backoff delay
    opts.InitialBackoff = TimeSpan.FromSeconds(1);
 
    // Maximum backoff delay
    opts.MaxBackoff = TimeSpan.FromMinutes(5);
 
    // Enable circuit breaker protection
    opts.EnableCircuitBreaker = true;
 
    // Circuit breaker threshold
    opts.CircuitBreakerThreshold = 3;
 
    // Circuit breaker reset timeout
    opts.CircuitBreakerResetTime = TimeSpan.FromMinutes(1);
});

Exponential Backoff

The supervisor uses exponential backoff when restarting failed servers to prevent overwhelming the system during outages:

Attempt 1:

1s

Attempt 2:

2s

Attempt 3:

4s

Attempt 4:

8s

Attempt 5:

16s

Max:

5 minutes (capped)

Health States

Healthy

Server is running normally with no issues detected.

Degraded

Server has experienced failures but is being restarted.

Failed

Server has exceeded restart limits and stopped.

Supervisor Directives

The supervisor determines actions based on failure conditions:

Directive	Action
Restart	Restart the failed server with backoff delay
Stop	Stop the server permanently (max restarts exceeded)
Escalate	Propagate the failure to parent supervisor

Supported Transports

The Supervisor pattern works with all message-based transports:

NATS

RabbitMQ

Kafka

gRPC

Azure Service Bus

AWS SQS

Best Practices

• Use OneForOne strategy for independent services
• Enable circuit breaker in production to prevent resource exhaustion
• Monitor health states and set up alerts for Failed state
• Adjust max backoff based on your infrastructure recovery time

---

Source: https://fxmapper.net/docs/configuration/supervisor/ — the website is always the most up to date version.