RussiaRunning.FeatureFlags.Client 1.1.0

RussiaRunning.FeatureFlags.Client

Клиентская библиотека для работы с публичным REST API фича-флагов через API и интеграцию с ASP.NET Core 9+.

v1.1.0 — отказоустойчивость и скорость. Сбой сервера флагов больше никогда не валит бизнес-операцию: жёсткий таймаут, retry с джиттером, stale-while-revalidate, single-flight и настраиваемый fail-safe режим.

Содержание

• Что нового в v1.1.0
• Конфигурация
• Варианты подключения
• Использование
• Поведение при сбое сервера флагов
• Все опции клиента

Что нового в v1.1.0

Публичные интерфейсы IFeatureFlagsClient, IFeatureGate, IFeatureFlagsCache не изменились — апдейт 1.0.1 → 1.1.0 не требует правок кода.

Конфигурация

Минимальный набор:

{
  "FeatureFlags": {
    "BaseUrl": "https://flags.myhost.com",
    "EnvironmentKey": "prod",
    "DefaultTenantKey": "def_tenant_key"
  }
}

Полный пример с тонкой настройкой отказоустойчивости:

{
  "FeatureFlags": {
    "BaseUrl": "https://flags.myhost.com",
    "EnvironmentKey": "prod",
    "DefaultTenantKey": "def_tenant_key",

    "EnableCaching": true,
    "CacheTtl": "00:00:30",
    "StaleTtl": "00:10:00",
    "NegativeCacheTtl": "00:00:30",

    "RequestTimeout": "00:00:02",
    "MaxRetryAttempts": 2,
    "RetryBaseDelay": "00:00:00.100",

    "FailureMode": "ReturnStale",
    "EnableStaleWhileRevalidate": true
  }
}

Варианты подключения

Вариант 1 — через appsettings.json

using RussiaRunning.FeatureFlags.Client.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFeatureFlagsClient(builder.Configuration.GetSection("FeatureFlags"));

var app = builder.Build();
app.Run();

Вариант 2 — программная настройка

builder.Services.AddFeatureFlagsClient(opts =>
{
    opts.BaseUrl          = "https://flags.myhost.com";
    opts.EnvironmentKey   = "staging";
    opts.DefaultTenantKey = "global";

    opts.RequestTimeout   = TimeSpan.FromSeconds(2);
    opts.CacheTtl         = TimeSpan.FromSeconds(30);
    opts.StaleTtl         = TimeSpan.FromMinutes(10);
    opts.FailureMode      = FeatureFlagsFailureMode.ReturnStale;
});

Вариант 3 — с собственным кэшем (например, Redis)

builder.Services.AddStackExchangeRedisCache(o => o.Configuration = "localhost:6379");

builder.Services.AddFeatureFlagsClient(
    builder.Configuration.GetSection("FeatureFlags"),
    cacheFactory: sp => new DistributedCacheAdapter(sp.GetRequiredService<IDistributedCache>())
);

Использование

public class CheckoutController(IFeatureGate flags) : ControllerBase
{
    [HttpGet("/checkout")]
    public async Task<IActionResult> Checkout(CancellationToken ct)
    {
        var enabled = await flags.IsEnabledAsync("checkout.enabled", @default: false, ct: ct);
        if (!enabled)
            return Forbid();

        var limit  = await flags.GetIntAsync("checkout.maxItems", 10, ct: ct);
        var theme  = await flags.GetStringAsync("ui.theme", "light", ct: ct);
        var config = await flags.GetValueAsync<CheckoutConfig>("checkout.config", tenantKey: "store-42", ct: ct);

        return Ok(new { enabled, limit, theme, config });
    }

    public record CheckoutConfig(string Mode, int MaxItems);
}

При недоступности сервера флагов этот код всё ещё работает — каждый вызов вернёт @default без исключений и без зависаний на минуту.

Поведение при сбое сервера флагов

FeatureFlagsFailureMode управляет поведением клиента после исчерпания retry-попыток:

Stale-копия живёт CacheTtl + StaleTtl (по умолчанию 30с + 10мин = ~10мин). Это «окно живучести» при полной недоступности сервера флагов.

Поток обработки одного вызова EvaluateAsync:

┌─ cache HIT (свежий) ─────────► return value
│
├─ cache HIT (stale)  ─────────► return value + fire-and-forget refresh
│
└─ cache MISS ────► single-flight ────► HTTP (timeout 2с, retry x2)
                                              │
                                       success ► cache + return
                                              │
                                       fail    ► FailureMode:
                                                  ReturnStale → stale | null
                                                  ReturnDefault → null
                                                  Throw → throw

Все опции клиента