Skip to content

feat(plugin): add structured async plugin health checks with cancellation - #37

Merged
rian-be merged 8 commits into
developmentfrom
Health-Checks
Sep 13, 2026
Merged

rian-be merged 8 commits into
developmentfrom
Health-Checks

Conversation

@rian-be

@rian-be rian-be commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds first class structured and asynchronous health check contract to the AuthKit plugin API: plugins can now report multiple structured health results for independent dependencies while respecting host provided cancellation. The previous boolean health hook is replaced by default interface implementation so existing plugins remain source compatible and stay healthy by default when they do not implement custom checks.

Structured Health Models (D1–D2)

  • adds PluginHealthStatus with Healthy, Degraded, and Unhealthy classifications
  • adds PluginHealthResult carrying Status, optional Reason, and optional plugin-owned diagnostic Data
  • preserves each result's semantics through serialization in the host health endpoint

Extended Health Contract (D3–D4)

  • replaces Task<bool> CheckHealthAsync(IServiceProvider) on IAuthKitPlugin with an additive default interface implementation: Task<IReadOnlyList<PluginHealthResult>> CheckHealthAsync(IServiceProvider, CancellationToken = default)
  • the default implementation reports Healthy, so plugins without custom checks never become implicitly unhealthy
  • plugins can return a single result or multiple independent results without changing the API
  • cancellation is passed through to plugins; host cancellation (request aborted) is never converted into a fabricated health result
  • DevTokens and DevTools adopt the structured contract, including a Marten-backed check for DevTokens

Host Integration

  • the /health endpoint collects every plugin's result list, propagates RequestAborted, and aggregates via the maximum per plugin status (Healthy + Degraded -> Degraded), returning 200 or 503 accordingly
  • the plugin contract validator's HealthRule invokes the new async contract with a cancellation token and rejects plugins that return no results
  • fixes console startup under non interactive output (guarded Spectre.Console status spinner in JwtKeyStoreInitializer, which previously crashed when multiple hosts started concurrently)

Validation

  • 109/109 tests pass (29 Abstractions, 70 Host, 10 Integration)
  • dotnet build completes with zero errors across the solution
  • git diff --check passes
  • PluginContractValidator passes end to end against DevTools and DevTokens

Result

Plugins report structured, asynchronous, cancellable health for each dependency or capability independently, the host aggregates these results without collapsing them to a boolean, and existing plugin implementations continue to compile, load, and report healthy without modification.

Closes #14
Closes #15

@rian-be rian-be self-assigned this Sep 13, 2026
@rian-be rian-be added enhancement New feature or request area/abstractions AuthKit.Plugins.Abstractions contract area/host Host-side runtime (DI, OpenAPI, health exec) area/health-checks Plugin health check contract/infra (Section D) contract Changes the plugin contract additive Additive, non-breaking change labels Sep 13, 2026
@rian-be
rian-be merged commit 7e29719 into development Sep 13, 2026
9 checks passed
@rian-be
rian-be deleted the Health-Checks branch September 14, 2026 00:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

additive Additive, non-breaking change area/abstractions AuthKit.Plugins.Abstractions contract area/health-checks Plugin health check contract/infra (Section D) area/host Host-side runtime (DI, OpenAPI, health exec) contract Changes the plugin contract enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Task] Extend the Plugin Health Check Contract [Task] Introduce PluginHealthResult and Structured Health Status

1 participant