Table of Contents

Class TcgDexCachingHandler

Namespace
TcgDex.Caching
Assembly
TcgDex.CSharpSdk.dll

Serves repeated reads from a cache, and revalidates with the API rather than re-downloading when an entry goes stale.

public sealed class TcgDexCachingHandler : DelegatingHandler, IDisposable

Inheritance

Implements

Inherited Members

Remarks

A request takes one of three paths:

  1. Fresh hit — within the freshness window, served from memory with no network at all.
  2. Stale hit — the entry is past its window but has an ETag, so the request goes out with If-None-Match. The API answers 304 with an empty body, the entry's clock is reset, and the cached body is served. A 22 KB set response costs 0 bytes here.
  3. Miss — a normal request, stored on the way back.

Only GET is cached, which is the whole API — it is read-only.

This sits in the HttpClient pipeline rather than inside the SDK's transport, so it is transparent to every resource client and composes with any other handler a caller adds.

Exceptions. A body larger than the configured limit, or one whose connection fails mid-read, throws TcgDex.TcgDexApiException out of this handler rather than System.Net.Http.HttpRequestException. This is deliberate: retry policies such as AddStandardResilienceHandler retry System.Net.Http.HttpRequestException, and re-downloading a body that is too large will only fail the same way again. Callers going through TcgDex.TcgDexClient see TcgDex.TcgDexApiException either way.

Constructors

TcgDexCachingHandler(ITcgDexResponseCache, TcgDexCacheOptions?, TimeProvider?, long)

Creates the handler.

public TcgDexCachingHandler(ITcgDexResponseCache cache, TcgDexCacheOptions? options = null, TimeProvider? timeProvider = null, long maxResponseBytes = 33554432)

Parameters

cache ITcgDexResponseCache

Where responses are stored.

options TcgDexCacheOptions?

Freshness policy. Defaults are used when omitted.

timeProvider TimeProvider?

Clock used for freshness; defaults to the system clock.

maxResponseBytes long

The largest body this handler will buffer, matching TcgDex.TcgDexOptions.MaxResponseBytes. Zero removes the limit.

Remarks

maxResponseBytes defaults to the same 32 MiB as TcgDex.TcgDexOptions rather than to unbounded, so a handler constructed by hand is bounded too. Both of the SDK's own construction paths pass the configured value through.

Exceptions

ArgumentNullException

cache is null.

Properties

Statistics

How this handler's cache has been answering requests.

public TcgDexCacheStatistics Statistics { get; }

Property Value

TcgDexCacheStatistics

Remarks

The same instance AddTcgDexWithCaching registers for injection, so under IHttpClientFactory it counts across every handler the factory has built. A handler constructed by hand has its own.

Methods

SendAsync(HttpRequestMessage, CancellationToken)

Sends an HTTP request to the inner handler to send to the server as an asynchronous operation.

protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)

Parameters

request HttpRequestMessage

The HTTP request message to send to the server.

cancellationToken CancellationToken

A cancellation token to cancel operation.

Returns

Task<HttpResponseMessage>

The task object representing the asynchronous operation.

Exceptions

ArgumentNullException

The request was null.

OperationCanceledException

The cancellation token was canceled. This exception is stored into the returned task.