namespace NpgsqlRest;

/// <summary>

/// A named caching policy that an endpoint can opt into via the <c>@cache_profile</c> comment annotation.

/// Profiles let you maintain multiple distinct caching policies (different backends, expirations, key shapes,

/// or bypass conditions) within a single application.

///

/// At the C# / library level a <see cref="CacheProfile"/> is fully configured: its <see cref="Cache"/> is an

/// <see cref="IRoutineCache"/> instance you provide. The NpgsqlRestClient configuration layer reads JSON profiles

/// (with a <c>"Type"</c> string and optional <c>"Enabled": true</c>) and constructs profile instances on your behalf.

/// The core library itself stays interface-only and does not know about Memory/Redis/Hybrid backends — it just

/// stores the resolved <see cref="IRoutineCache"/>.

///

/// Profile resolution at startup:

/// - Each endpoint with <c>@cache_profile name</c> looks up <c>name</c> in <see cref="CacheOptions.Profiles"/>.

/// - Unknown names cause startup to fail with a single error listing all unresolved references and the offending endpoints.

/// - Endpoints without <c>@cache_profile</c> use <see cref="CacheOptions.DefaultRoutineCache"/> (the root cache).

/// </summary>

public class CacheProfile

{

/// <summary>

/// The cache backend instance for this profile. Required.

///

/// The library does not interpret <see cref="Cache"/> beyond calling <c>Get</c>/<c>AddOrUpdate</c>/<c>Remove</c>.

/// In the client app, the same <see cref="IRoutineCache"/> instance is reused for every profile of the same

/// <c>"Type"</c> — one Memory cache, one Redis connection, one HybridCache singleton at most.

/// </summary>

public IRoutineCache Cache { get; set; } = null!;

/// <summary>

/// Default expiration for entries written under this profile. <c>null</c> means entries never expire (matches

/// today's <c>@cached</c> behavior when no <c>@cache_expires</c> is set).

///

/// An endpoint's <c>@cache_expires &lt;interval&gt;</c> annotation overrides this value.

/// </summary>

public TimeSpan? Expiration { get; set; }

/// <summary>

/// Default cache-key parameter list for endpoints using this profile when their <c>@cached</c> annotation

/// does not specify any. Three semantics:

///

/// - <c>null</c> (or property omitted): use ALL routine parameters as the cache key — same as today's bare <c>@cached</c>.

/// - <c>[]</c> (empty array): use NO parameters — one cache entry per endpoint URL, regardless of inputs.

/// - <c>["p1", "p2"]</c>: use only these named parameters as the cache key.

///

/// The endpoint's <c>@cached p1, p2</c> annotation overrides this list; if both the annotation and the profile

/// specify parameters, the annotation wins.

/// </summary>

public string[]? Parameters { get; set; }

/// <summary>

/// Optional list of conditional rules evaluated against the resolved parameter values at request time.

/// Each rule combines a <see cref="CacheWhenRule.Parameter"/> name, a <see cref="CacheWhenRule.Value"/>

/// condition (scalar or array), and an action — either bypass the cache (<see cref="CacheWhenRule.Skip"/>)

/// or override the entry's TTL (<see cref="CacheWhenRule.ThenExpiration"/>).

///

/// Rules are evaluated in declaration order; the first match wins. No match → fall through to the profile's

/// (or annotation's) default <see cref="Expiration"/>. Use this for:

/// - Skip-on-condition (e.g. "if `to` is null, fetch fresh")

/// - Tiered TTLs ("if `tier=free`, cache 5 min; if `tier=pro`, no cache")

/// - Status-aware caching ("if `status=draft`, cache 30 sec; if `status=published`, cache 1 hour")

///

/// Each rule's <c>Parameter</c> must be in the cache-key parameter list (via profile's <see cref="Parameters"/>

/// or the endpoint's <c>@cached</c> annotation), otherwise different rule-evaluations would share the same cache

/// entry and produce confusing results. Rules whose Parameter isn't in the cache key are dropped with a startup

/// Warning.

/// </summary>

public CacheWhenRule[]? When { get; set; }

}