GH-4500: only ever write ASP.NET Core's endpoint data sources from the composition thread

[jeremydmiller]

Fixes #4500.

The bug

RouteOptions.EndpointDataSources is a plain ObservableCollection<EndpointDataSource>, and CompositeEndpointDataSource.CreateEndpointsUnsynchronized() walks it with a bare foreach. UseRouting / UseAuthorization trigger that walk on the startup thread while the pipeline is being built. An Add from any other thread at that moment throws InvalidOperationException: Collection was modified on the startup thread — and the host does not start.

GH-3421 made Wolverine publish the host's endpoints into that collection lazily, from WolverineApiDescriptionProvider.OnProvidersExecuting — i.e. from whatever thread happened to read the ApiExplorer. A monitoring observer building a capabilities snapshot as the runtime starts is exactly that, so Wolverine became the concurrent writer that killed the startup thread's enumeration. The old code documented the hazard and reasoned past it:

It cannot exclude ASP.NET Core's UseEndpoints(), which writes the same collection unlocked — but that writer only runs while the host is starting, and an ApiExplorer read concurrent with host start is already unsafe in ASP.NET Core […] with or without Wolverine.

True of the read, but the write was ours, and the thing that died was startup.

The fix

Wolverine writes that collection from exactly one place now: MapWolverineEndpoints(), on the thread composing the application — the same thread ASP.NET Core writes it from.

Publishing the route builder's data sources eagerly at map time would have regressed GH-3421 for anything mapped after that call (MapControllers(), a later MapGroup()), so what gets registered is one deferred UnpublishedEndpointDataSource: a view over routeBuilder.DataSources minus whatever UseEndpoints() has already published. Before start it answers for everything; after start it answers for nothing, so no endpoint is ever registered twice on either side of host start. Reading the ApiExplorer mutates nothing at all.

While in here, the reader that actually hit this: HttpGraphUsageSource searched every ApiExplorer group once per chain, which is quadratic on the several-hundred-endpoint host in the report. It now indexes once, and gives up the OpenAPI shape rather than the whole capabilities snapshot if the read throws.

Test

api_explorer_before_host_start.reading_the_api_explorer_does_not_mutate_the_live_endpoint_collection is deterministic rather than timing-dependent: a gate data source blocks inside Endpoints, holding the collection's enumerator open exactly the way CreateEndpointsUnsynchronized does mid-startup, while the test thread performs the ApiExplorer read. Against main it fails with the issue's own stack trace:

System.InvalidOperationException : Collection was modified; enumeration operation may not execute.
   at System.Collections.Generic.List`1.Enumerator.MoveNext()
   at Microsoft.AspNetCore.Routing.CompositeEndpointDataSource.CreateEndpointsUnsynchronized()
   at Microsoft.AspNetCore.Routing.CompositeEndpointDataSource.EnsureEndpointsInitialized()
   at Microsoft.AspNetCore.Routing.CompositeEndpointDataSource.get_Endpoints()

The existing GH-3373 / GH-3421 tests carry the rest: descriptions complete before start, minimal API routes present on a hybrid host, no duplicate registration once the host starts, and route groups still registered exactly once.

Verification

Full wolverine.slnx built Release pinned to -f net9.0. Wolverine.Http.Tests green (1053 passed, 10 skipped).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VDUrBeB4tTnKj4AExCS1nj