Winglet.Client 0.2.0

Winglet.Client

Winglet.Client is the small shared HTTP infrastructure for maintained Winglet service-owned typed clients. A service package owns its semantic operations, routes and Contracts DTOs, then composes this package for common endpoint configuration, authentication, error handling, resilience and optional logical correlation.

Registration

Service packages register their typed client and select the service key and wire profile:

services.AddHttpClient<IPartyClient, PartyClient>()
    .AddWingletClientInfrastructure(
        configuration,
        "Party",
        WingletRemoteContractProfile.Canonical);

The endpoint is deployment configuration under:

Winglet:Clients:Party:BaseUrl

It must be an absolute HTTP or HTTPS URI without embedded credentials. A reverse-proxy path prefix belongs in the configured URL when deployment requires one.

Service-client baseline

A maintained service client normally lives in src/Winglet.<Service>.Client/ with a typed interface, implementation, options, requests/models and service-owned exceptions; tests live in tests/Winglet.<Service>.Client.Tests/. The service package owns routes, query/body DTOs and semantic validation. Winglet.Client owns the IHttpClientFactory pipeline, delegated token-provider boundary, correlation, transport/resilience and common error parsing.

Client options should normally contain only the service BaseUrl. They must not duplicate issuer, JWT, tenant, privilege, token-cache or generic retry configuration. A normal tenant-scoped operation uses the caller tenant from the authenticated token context; a TenantId parameter is reserved for an API operation that explicitly targets another tenant.

Use typed records and value types for public contracts. A 2xx response with a missing or malformed required contract is a WingletClientContractException, not a successful result. Clients expose stable reusable operations only; internal/provider-specific endpoints and generic raw transport are excluded by default. /self is a separate delegated-human use case and must not be assumed to work with service-only tokens. Long-running operations expose StartOperationAsync/GetOperationAsync rather than hidden polling loops.

The baseline targets the repository's current net10.0 runtime; clients do not lower their TFM speculatively. Package metadata, README, symbols and central package versions are required for reusable client packages.

Concurrency and write conventions

WingletClientResponseReader.ReadResourceAsync<T> returns the resource and an optional ETag. A write that requires optimistic concurrency accepts an ETag explicitly and can use WingletClientHeaders.SetIfMatch; HTTP 412 is never automatically retried. SetIdempotencyKey forwards the caller's key unchanged; the shared client never silently creates or replaces a key.

WingletRemoteApiException is the common structured ProblemDetails failure for non-success HTTP responses. WingletTransportException represents reachability/timeouts, WingletProtocolException represents an unsupported HTTP/error protocol, and WingletClientContractException represents an invalid required success payload. None of these exceptions is specialized per business error code. The standard resilience pipeline retries only bounded transient safe requests; mutating retries require explicit idempotency semantics and 409/412 are not replayed automatically.

Boundaries

The package exposes an outbound IWingletClientTokenProvider boundary. A service operation marks its required service-only or on-behalf-of token semantics using WingletClientRequestOptions; the application caller does not choose authentication mode at each call site. The package never parses JWTs or forwards an inbound bearer token implicitly.

Canonical Problem Details failures are exposed as WingletRemoteApiException, while transport failures and malformed protocol responses use WingletTransportException and WingletProtocolException. LegacyErrorEnvelope is a contained compatibility profile for the known legacy { error, message, details, correlationId } shape. It does not invent a stable code when the legacy response does not provide one.

The standard .NET HTTP resilience pipeline uses bounded timeouts and transient retries for safe methods. Unsafe methods such as POST and PATCH are excluded from blind automatic retry. Technical tracing remains native HttpClient / Activity / W3C propagation. X-Correlation-Id is sent only when an application-provided IWingletCorrelationIdAccessor has a logical correlation value; X-Request-Id is not generated.

This package is not a universal client, service registry, generated-client framework, JWT/authentication authority, tracing framework or business orchestration layer. It is deliberately independent of the implementation language of the target service.