Section API Reference

API Reference Language: C# Component: Evidence Audience: developer

Readiness

Type

HttpReadinessProbe

Source

Waits for an explicit status-only HTTP condition under one cooperative monotonic deadline.

Method

WaitAsync

2 overloads

Task WaitAsync(HttpClient client, Uri endpoint, string probePath, TimeSpan timeout, HttpReadinessOptions? options = null, CancellationToken cancellationToken = default)

Source

Sends headers-only GET requests until the status condition succeeds or a bound is reached.

Parameters

client
Borrowed client; its configuration and lifetime remain caller-owned.
endpoint
Absolute HTTP(S) base endpoint.
probePath
Nonempty relative or root-relative path; it must resolve to the same origin.
timeout
Finite positive total budget, including retries and delays.
options
Optional snapshotted status, timer, and attempt policy.
cancellationToken
Caller cancellation; wins over simultaneous deadline expiry.

Returns

Completion only after the declared condition passes inside the original budget.

Remarks

Never reads response bodies, mutates the client, or logs raw exceptions. Redirect behavior belongs to the client; initial-origin validation is not a redirect sandbox. Non-cooperative callbacks can outlast the budget.

Task WaitAsync(HttpClient client, Uri endpoint, string probePath, TimeSpan timeout, HttpReadinessOptions? options, CancellationToken cancellationToken, TimeProvider timeProvider)

Source

Clock seam for deterministic timer and cancellation verification.

Method

ValidateProbePath

void ValidateProbePath(string probePath)

Source

Validates the path without requiring an allocated endpoint; adapters call before acquisition.

Method

ResolveProbeUri

Uri ResolveProbeUri(Uri endpoint, string probePath)

Source

Resolves and checks HTTP(S) scheme, IDN host, and effective port before dispatch.

Method

WaitCoreAsync

Task WaitCoreAsync(HttpClient client, Uri endpoint, string probePath, HttpReadinessSettings settings, ReadinessDeadline deadline)

Source

Shared core used by adapters with their original deadline and validated option snapshot.

Type

HttpReadinessOptions

Source

Configures one HTTP readiness operation; values are snapshotted before work begins.

Property

RequestTimeout

TimeSpan RequestTimeout { get; init; } Source

Gets the finite positive per-request maximum; defaults to three seconds.

Property

RetryDelay

TimeSpan RetryDelay { get; init; } Source

Gets the finite positive delay between failed attempts; defaults to 250 milliseconds.

Property

IsSuccess

Func<HttpStatusCode, bool> IsSuccess { get; init; } Source

Gets the synchronous status-only predicate; defaults to exact HTTP 200. Exceptions terminate the operation.

Property

MaxAttempts

int? MaxAttempts { get; init; } Source

Gets the optional positive request cap; null means the deadline alone bounds attempts.

Type

HttpReadinessSettings

Source

Immutable validated settings shared by the public probe and hosting adapters.

Parameters

RequestTimeout
Finite positive maximum for one request, shortened by remaining time.
RetryDelay
Finite positive fixed delay, shortened by remaining time.
IsSuccess
Snapshotted synchronous status-only predicate; exceptions are terminal.
MaxAttempts
Positive request cap, or null for deadline-only behavior.

Method

Snapshot

HttpReadinessSettings Snapshot(HttpReadinessOptions options)

Source

Validates and snapshots options without acquiring resources or invoking callbacks.

Type

ReadinessDeadline

Source

One monotonic cooperative budget preserving caller and deadline cancellation identities.

Method

ValidateDuration

void ValidateDuration(TimeSpan duration, string parameterName)

Source

Validates finite positive durations supported by BCL timers before acquiring resources.

Method

Check

void Check(ReadinessPhase phase, ReadinessAttempt last = default)

Source

Checks caller first, then original deadline, then adapter shutdown; never resets the budget.

Remarks

The single sequential operation retains only safe latest HTTP scalars so post-probe cleanup checks keep attempt/cause diagnostics. A deadline instance must not be shared across independent concurrent waits.

Method

Dispose

void Dispose()

Source

Releases timers and links after all cooperative work has settled.

Property

TimeProvider

TimeProvider TimeProvider { get; } Source

Gets the provider used for monotonic measurements, timers, and delays.

Property

Token

CancellationToken Token { get; } Source

Gets cooperative cancellation for work; errors must be checked with Check .

Property

Remaining

TimeSpan Remaining { get; } Source

Gets the remaining original budget, clamped to zero.

Type

ReadinessCleanup

Source

Preserves fatal cleanup leaves before an adapter summarizes a secondary failure.

Remarks

Each adapter supplies its existing fatal-type policy; aggregate traversal does not broaden that policy.

Method

FindFatal

Exception? FindFatal(Exception exception, Func<Exception, bool> isFatal)

Source

Finds the first fatal exception in depth-first aggregate order without replacing its identity.

Parameters

exception
The non-null cleanup or diagnostic-storage failure.
isFatal
The owning adapter's non-null fatal-type classifier.

Returns

The original fatal exception, or null when every leaf is nonfatal.

Remarks

Traversal uses an explicit stack so aggregate nesting does not consume the runtime call stack.

Method

ThrowIfFatal

void ThrowIfFatal(Exception exception, Func<Exception, bool> isFatal)

Source

Rethrows an original fatal leaf before a failure can be converted into safe secondary metadata.

Parameters

exception
The non-null owned cleanup or diagnostic-storage failure.
isFatal
The owning adapter's existing non-null fatal-type classifier.

Type

ReadinessException

Source

Describes a generated readiness failure without retaining request data or raw transport exceptions.

Remarks

Original factory, build, predicate, and programming errors remain their original exceptions. Caller cancellation remains an OperationCanceledException carrying the original token.

Method

SafeCleanupType

string SafeCleanupType(Type? type)

Source

Maps cleanup types to a fixed BCL allowlist; arbitrary names and exception instances are never retained.

Property

Phase

ReadinessPhase Phase { get; } Source

Gets the phase active at failure.

Property

LastCause

ReadinessFailureCategory? LastCause { get; } Source

Gets the last retryable HTTP cause, or null before any failed attempt.

Property

LastStatusCode

HttpStatusCode? LastStatusCode { get; } Source

Gets the last rejected status; null for transport, timeout, or no attempt.

Property

LastHttpRequestError

HttpRequestError? LastHttpRequestError { get; } Source

Gets only the last transport error enum; null for other causes.

Property

Attempts

int Attempts { get; } Source

Gets the number of requests dispatched.

Property

Problem

string Problem { get; } Source

Gets a fixed safe problem description.

Property

Cause

string Cause { get; } Source

Gets a fixed safe explanation.

Property

NextAction

string NextAction { get; } Source

Gets a fixed safe next check.

Property

DocumentationUrl

string DocumentationUrl { get; } Source

Gets the canonical troubleshooting reference; it contains no request data.

Type

ReadinessAttempt

Source

Constant-space safe state of the most recent HTTP attempt; never stores a request, response, or exception.

Parameters

Attempts
Dispatched request count, retained when no further attempt can begin.
LastCause
Last retryable HTTP cause, or null before a failed HTTP observation.
Status
Rejected status only when the last cause is StatusRejected; otherwise null.
HttpError
Transport enum only when the last cause is TransportFailure; otherwise null.

Enum

ReadinessPhase

Source

Identifies the phase that failed to complete under the readiness budget.

Enum

ReadinessFailureCategory

Source

Safe failure categories; deadline and attempt-limit errors retain the last HTTP cause separately.