Veggerby.Ignition 0.6.0

Veggerby.Ignition

A lightweight, extensible startup readiness ("ignition") coordination library for .NET applications. Register ignition signals representing asynchronous initialization tasks (cache warmers, external connections, background services) and await them collectively with rich diagnostics, configurable policies, timeouts, tracing, and health checks.

Features

• Simple IIgnitionSignal abstraction (name, optional timeout, WaitAsync)
• Coordinated waiting via IIgnitionCoordinator
• Global timeout (soft by default) with per-signal overrides
• Policies: FailFast, BestEffort, ContinueOnTimeout
• Health check integration (adds ignition-readiness check)
• Activity tracing (toggle via options)
• Slow handle logging (top N longest signals)
• Task and cancellable Task factory adapters (IgnitionSignal.FromTask, FromTaskFactory)
• Idempotent execution (signals evaluated once, result cached)
• Execution modes: Parallel (default) or Sequential
• Optional parallelism limiting via MaxDegreeOfParallelism
• Cooperative cancellation on global or per-signal timeout

Quick Start

// Program.cs or hosting setup
builder.Services.AddIgnition(options =>
{
    options.GlobalTimeout = TimeSpan.FromSeconds(10);
    options.Policy = IgnitionPolicy.BestEffort; // or FailFast / ContinueOnTimeout
    options.EnableTracing = true; // emits Activity if diagnostics consumed
    options.ExecutionMode = IgnitionExecutionMode.Parallel; // or Sequential
    options.MaxDegreeOfParallelism = 4; // limit concurrency (Parallel mode only)
    options.CancelOnGlobalTimeout = true; // attempt to cancel still-running signals if global timeout hits
    options.CancelIndividualOnTimeout = true; // cancel a signal if its own timeout elapses
});

// Register concrete ignition signals
builder.Services.AddIgnitionSignal(new CustomConnectionSignal());

// Wrap an existing task
builder.Services.AddIgnitionFromTask("cache-warm", cacheWarmTask, timeout: TimeSpan.FromSeconds(5));

// Wrap a cancellable task factory (invoked lazily once)
builder.Services.AddIgnitionFromTask(
    name: "search-index",
    readyTaskFactory: ct => indexBuilder.BuildAsync(ct),
    timeout: TimeSpan.FromSeconds(30));

// Adapt a single service exposing a readiness Task
builder.Services.AddIgnitionFor<MyBackgroundWorker>(w => w.ReadyTask);

// Composite: await all instances of a service type
builder.Services.AddIgnitionForAll<ShardProcessor>(p => p.ReadyTask);

// TaskCompletionSource helpers
_startupReady.Ignited();
_startupReady.IgnitionFailed(ex);

var app = builder.Build();

// Await readiness before starting interactive loop or accepting traffic
await app.Services.GetRequiredService<IIgnitionCoordinator>().WaitAllAsync();

Creating a Custom Signal

public sealed class CustomConnectionSignal : IIgnitionSignal
{
    public string Name => "db-connection";
    public TimeSpan? Timeout => TimeSpan.FromSeconds(8); // optional override

    public async Task WaitAsync(CancellationToken cancellationToken = default)
    {
        // Perform initialization (e.g. open connection, ping server)
        await DatabaseClient.InitializeAsync(cancellationToken);
    }
}

Register it:

services.AddIgnitionSignal<CustomConnectionSignal>();

Policies

Diagnostics & Results

After ignition completes:

var coord = provider.GetRequiredService<IIgnitionCoordinator>();
var result = await coord.GetResultAsync();
if (result.TimedOut)
{
    // handle degraded startup
}
foreach (var r in result.Results)
{
    Console.WriteLine($"{r.Name}: {r.Status} in {r.Duration.TotalMilliseconds:F0} ms");
}

Health Check

AddIgnition automatically registers a health check named ignition-readiness returning:

• Healthy: all signals succeeded
• Degraded: soft global timeout elapsed without per-signal timeouts/failures
• Unhealthy: one or more signals failed, a hard global timeout (with cancellation) occurred, or exception during evaluation

Tracing

Set EnableTracing = true to emit an Activity named Ignition.WaitAll. Attach listeners via ActivitySource to integrate with OpenTelemetry or other observability pipelines.

Design Notes

• Thread-safe lazy execution ensures signals run at most once.
• Global timeout is soft unless cancellation is enabled (see Global Timeout Semantics).
• Factory-based signals honor cancellation tokens for cooperative shutdown scenarios.
• Sequential mode enables early fail-fast behavior and reduces resource contention.
• Per-signal cancellation requires signal implementations to observe passed CancellationToken.

Cancellation Token Semantics for Selectors

The cancellable selector overloads (AddIgnitionFor<TService>(Func<TService, CancellationToken, Task>), AddIgnitionForAll<TService>(Func<TService, CancellationToken, Task>), and scoped variants) receive the cancellation token from the FIRST wait invocation. That token is linked to coordinator-driven cancellations:

• Hard global timeout (CancelOnGlobalTimeout = true)
• Per-signal timeout cancellation (CancelIndividualOnTimeout = true)

Because ignition evaluation is idempotent, subsequent calls to IIgnitionCoordinator.WaitAllAsync() reuse already created tasks; the token cannot be changed after the first invocation. Selector implementations should:

• Avoid capturing ambient tokens elsewhere (use only the provided one)
• Return promptly or cooperatively observe cancellation (e.g. await Task.Delay(timeout, token))
• Not block synchronously; always async-await

If you require a fresh cancellation token per consumer, expose a custom IIgnitionSignal instead of using the built-in selector adapters.

Installation

Add a package reference (after publishing):

dotnet nuget add package Veggerby.Ignition

Roadmap Ideas

• Built-in signals (e.g. HttpEndpointSignal, ChannelDrainSignal)
• OpenTelemetry semantic conventions integration
• Structured metrics export (histograms for durations)

License

MIT

Additional Adapters

// Single instance
services.AddIgnitionFor<CachePrimer>(c => c.ReadyTask);

// Composite group
services.AddIgnitionForAll<Consumer>(c => c.ReadyTask, groupName: "Consumer[*]");

// Arbitrary provider-based readiness
services.AddIgnitionFromFactory(
    taskFactory: sp => Task.WhenAll(
        sp.GetRequiredService<PrimaryConnection>().OpenAsync(),
        sp.GetRequiredService<ReplicaConnection>().WarmAsync()),
    name: "datastore-connections");

// TCS helpers
_readyTcs.Ignited();
_readyTcs.IgnitionFailed(new Exception("boom"));

Global Timeout Semantics

Ignition exposes two timeout layers:

1. Global timeout (GlobalTimeout): A soft deadline unless CancelOnGlobalTimeout = true.
   • Soft (default): Execution continues beyond the elapsed deadline; final result only marked timed out if any signal itself timed out.
   • Hard (cancelling): Outstanding signals receive cancellation; result marked timed out and unfinished signals reported with their names and TimedOut status.
2. Per-signal timeout (IIgnitionSignal.Timeout): Always enforced; if elapsed the signal is marked TimedOut and optionally cancelled when CancelIndividualOnTimeout = true.

Classification summary:

This model avoids penalizing slow but successful initialization while still enabling an upper bound via opt-in cancellation.

Configuration Examples

// Soft global timeout (default behavior):
services.AddIgnition(o =>
{
    o.GlobalTimeout = TimeSpan.FromSeconds(5); // deadline hint
    o.CancelOnGlobalTimeout = false;           // remain soft (default)
    o.CancelIndividualOnTimeout = false;       // per-signal timeouts won't cancel tasks
});

// Hard global timeout with cancellation:
services.AddIgnition(o =>
{
    o.GlobalTimeout = TimeSpan.FromSeconds(5);
    o.CancelOnGlobalTimeout = true;            // cancel all outstanding signals at deadline
    o.Policy = IgnitionPolicy.ContinueOnTimeout; // choose continuation policy
});

// Mixed: hard global timeout + per-signal timeout cancellation:
services.AddIgnition(o =>
{
    o.GlobalTimeout = TimeSpan.FromSeconds(10);
    o.CancelOnGlobalTimeout = true;            // hard deadline
    o.CancelIndividualOnTimeout = true;        // cancel slow individual signals
    o.ExecutionMode = IgnitionExecutionMode.Parallel;
    o.MaxDegreeOfParallelism = 4;
});

// Defining a per-signal timeout (hard for that signal only):
services.AddIgnitionFromTask(
    name: "search-index",
    readyTaskFactory: ct => indexBuilder.BuildAsync(ct),
    timeout: TimeSpan.FromSeconds(30) // this signal will be marked TimedOut if exceeded
);