Async loading and cancellation tokens in CloudRequestEngine

[drasmart]

🚧 Expands on #134

For the content delta see:

• Async loading and cancellation tokens in CloudRequestEngine (new for 4.5) postindustria-tech/pipeline-dotnet#5

Changes

• Introduce TaskWaitingCancellation/TaskExtensions static class -- provides Task<T> WithCancellation<T>(this Task<T>, CancellationToken) extension method:
  • Enables cancelling the awaiting on another task.
  • The original task is not affected, await cancellation is just like detaching.
• Introduce AsyncLazyFailable:
  • Counterpart to [Lazy<T>].
  • Value accessed via Task<TResult> GetValueAsync(CancellationToken) method.
  • At most one task (internal "active") is attempting to run value factory delegate at any time.
  • Any number of tasks can cancellably await for the active task to finish.
    • Cancelling the waiting does not cancel already-started "active" task.
  • Exceptions properly propagate (though may now be wrapped into AggregateException).
• Update CloudRequestEngine:
  • Swap out [Lazy<T>] fields for AsyncLazyFailable.
  • Start requesting the "lazy" values (EvidenceKeyFilter, PublicProperties) at constructor time.
  • Pass IFlowData.ProcessingCancellationToken to [HttpClient.SendAsync].
• Update IFlowData interface:
  • Add void Process(CancellationToken) method -- allows the caller to cancel the operation.
    • Correspondingly update FlowData class -- Process() now forwards to Process(CancellationToken) successor implementation.
  • Add CancellationToken ProcessingCancellationToken { get; } property -- exposes the provided [CancellationToken] to pipeline and flow elements.
    • Pipeline.Process(IFlowData) and FlowData.Process(CancellationToken) now respect ProcessingCancellationToken and can throw [OperationCanceledException].
• Update Web integrations:
  • WebPipeline (for ASP.NET Framework) passes the tokens from [HttpContextBase] for IFlowData.Process:
    • [HttpRequest.TimedOutToken].
    • [HttpResponseBase.ClientDisconnectedToken] (if available).
  • PipelineResultService (for ASP.NET Core) passes [HttpContext.RequestAborted] to IFlowData.Process.
• Update CloudRequestException:
  • Add constructors that accept responseHeaders in IReadOnlyDictionary<string, string> form -- as returned by ResponseHeaders property -- to allow re-constructing the exception from AggregateException's inner cause.
  • Move default value (empty dictionary) for ResponseHeaders from constructors lacking this parameter to the getter -- return non-null even if constructor is called with explicitly null responseHeaders parameter.
• Update EvidenceKeyFilterWhitelist:
  • Add constructors that accept inclusionList as IEnumerable<string> rather than List<string> (or IReadOnlyDictionary<string, int> rather than Dictionary<string, int>) -- as they are never mutated and don't need to depend on specific container implementation.
• Update EvidenceKeyFilterAggregator:
  • Change empty filter collection passed to base class from [new List<string>()] to [Enumerable.Empty<string>()] -- prevents unnecessary allocations.
• Add unit tests for:
  • AsyncLazyFailable implementation.
  • TaskExtensions.WithCancellation implementation.
  • CloudRequestEngine and Pipeline reacting to IFlowData processing cancellation.
• Includes content of [cancellation-tokens-4.4] (to be merged by Suppress calls to cloud server for a Recovery Period after request failures. #134 first).

Why

• CloudRequestEngine graceful non-blocking degradation  #132

Test results

• Unit tests run ✅ https://github.com/postindustria-tech/pipeline-dotnet/actions/runs/11406243554
• .nupkg built by 📦 https://github.com/postindustria-tech/pipeline-dotnet/actions/runs/11406530090

Screenshots

Example	Before recovery (new stacktrace)	During recovery (unaffected)
GettingStarted-Web
Framework-Web

[justadreamer]

Decided to possibly postpone to version 5.0