Solo.Beacon

Solo.Beacon — это переиспользуемый ASP.NET Core пакет для сервисов ft-soft. Он предоставляет:

• endpoint /beacon/discovery, который публикует пути health и stats текущего сервиса
• endpoint /health, который отвечает 200 OK на любой HTTP-метод и содержит ссылку на endpoint статистики
• endpoint /stats для состояния текущего сервиса
• общий флаг логирования запросов к /beacon/discovery, /health и /stats
• опциональный фоновый опрос зависимых сервисов с обработкой результатов через delegate
• стартовую health-проверку зависимостей сразу после запуска приложения

Быстрый старт

using Solo.Beacon;
using Solo.Beacon.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddBeacon();

var app = builder.Build();

// Сразу регистрирует health и fallback stats.
app.MapBeacon();

app.UseAuthentication();
app.UseAuthorization();

// Перезаписывает fallback пользовательским защищенным обработчиком.
app.MapBeaconStats(GetStatsAsync);

MapBeacon() регистрирует /beacon/discovery, /health и fallback /stats, поэтому его можно вызвать до настройки авторизации и получать health и базовую статистику во время запуска приложения.

Пока MapBeaconStats(handler) не вызван, /stats отвечает 200 OK с текстом Статистика не инициализирована. Сервис всё еще запускается, или он не зарегистрировал обработчик. После регистрации обработчика fallback пропускает запрос к защищенному endpoint-у, добавленному после middleware авторизации.

Где настраивать пути

Пути к health и stats можно задавать в трех местах. Это сделано для разных сценариев:

• дефолты пакета — подходят, когда сервису достаточно /health и /stats
• секция Beacon в конфиге — основной способ для приложений, где пути должны меняться без правки Program.cs
• параметры MapHealth(...) и MapBeaconStats(...) — точечное переопределение маршрута рядом с регистрацией endpoint-а

Приоритет такой:

1. url, переданный прямо в MapHealth(url) или MapBeaconStats(handler, url).
2. BeaconOptions.HealthUrl / BeaconOptions.StatsUrl, полученные из AddBeacon(...).
3. дефолтные пути /health и /stats.

Самый высокий приоритет у параметров MapHealth(...) и MapBeaconStats(...), потому что они регистрируют конкретный route в ASP.NET Core.

app.MapBeacon()
    .MapHealth("/internal/health");

app.UseAuthentication();
app.UseAuthorization();
app.MapBeaconStats(GetStatsAsync, "/internal/stats");

Для согласованности discovery с фактическими маршрутами обычно задавайте оба пути в конфигурации.

Рекомендация

Для большинства сервисов лучше хранить пути в конфиге и не передавать url в MapHealth(...) / MapBeaconStats(...). Так настройка остается одинаковой для разных окружений и не требует отдельной правки кода:

{
  "Beacon": {
    "LoggingEnabled": false,
    "HealthUrl": "/health",
    "StatsUrl": "/stats"
  }
}

builder.Services.AddBeacon();

app.MapBeacon();

app.UseAuthentication();
app.UseAuthorization();
app.MapBeaconStats(GetStatsAsync);

Передавайте url прямо в MapHealth(...) или MapBeaconStats(...), когда путь является частью кода конкретного приложения: например, endpoint должен жить под уже существующим /internal/*, рядом с reverse proxy rules или legacy routing.

Конфигурация через код

Если настройки нельзя брать из IConfiguration, используйте перегрузку с Action<BeaconOptions>:

builder.Services.AddBeacon(options =>
{
    options.LoggingEnabled = true;
    options.HealthUrl = "/health";
    options.StatsUrl = "/stats";
});

Эта перегрузка настраивает BeaconOptions из кода. Если нужен обычный appsettings.json, используйте builder.Services.AddBeacon() без lambda.

Stats

MapBeacon() сразу регистрирует fallback /stats с базовым ответом. Чтобы заменить его реальной статистикой, обязательно передайте обработчик в отдельный вызов MapBeaconStats(handler) после middleware аутентификации и авторизации.

/health отвечает 200 OK с Healthy и HTML-ссылкой на endpoint статистики, например <a href="/stats">Статистика</a>.

Если нужен собственный ответ /stats, передайте async-handler в MapBeaconStats(...). В нем доступны HttpContext и CancellationToken, поэтому состав статистики можно настраивать в зависимости от пользователя, заголовков и других деталей запроса.

app.UseAuthentication();
app.UseAuthorization();

app.MapBeaconStats(async (httpContext, cancellationToken) =>
{
    var statsProvider = httpContext.RequestServices.GetRequiredService<StatsProvider>();
    var stats = await statsProvider.GetStatsAsync(cancellationToken);
    var userName = httpContext.User.Identity?.Name;

    return TypedResults.Ok(new
    {
        stats,
        userName,
    });
});

Любой /stats, подключенный через MapBeaconStats(...), закрыт авторизацией и использует стандартные сервисы авторизации ASP.NET Core из хост-приложения. Чтобы в HttpContext.User были данные пользователя, хост-приложение должно само настроить аутентификацию обычным для себя способом.

Мониторинг зависимостей

{
  "Beacon": {
    "LoggingEnabled": false,
    "HealthUrl": "/health",
    "StatsUrl": "/stats",
    "Monitoring": {
      "Enabled": true,
      "ProbeInterval": "00:00:30",
      "RequestTimeout": "00:00:05",
      "Services": [
        "https://solo-butler.ru",
        "https://solo.ru/solo",
        "https://solo.ru/org"
      ]
    }
  }
}

Если мониторинг включен, пакет сразу после старта приложения делает первый проход по Services: запрашивает у каждого сервиса /discovery, находит опубликованный health endpoint и проверяет его доступность. Дальше проверки повторяются с интервалом ProbeInterval.

Если нужно обработать результаты мониторинга зависимостей, настройте handler через BeaconBuilder:

builder.Services
    .AddBeacon()
    .AddMonitoringHandler(
        static async (serviceProvider, responses, cancellationToken) =>
        {
            var cache = serviceProvider.GetRequiredService<IMonitoringCache>();
            await cache.StoreAsync(responses, cancellationToken);
        });

Успешные проверки и ошибки пишутся в лог только при LoggingEnabled = true.

Discovery

/discovery всегда находится на фиксированном пути и не настраивается через конфиг. Мониторинг зависимостей полагается именно на этот адрес, чтобы сначала узнать реальные пути health и stats у сервиса, а затем проверить опубликованный health endpoint.

Если зависимый сервис возвращает 404 Not Found на /discovery, это трактуется как отсутствие поддержки Solo.Beacon. Если health endpoint зависимого сервиса возвращает не JSON, Solo.Beacon сформирует служебный payload со статусом проверки.