products_log.h

Go to the documentation of this file.

/// \file products_log.h
/// \brief Клиентская библиотека для REST API Products (статистика
///        использования приложений).
/// \details Зеркалирует Java-библиотеку ru.gentoos.ProductsLog и Python
///          e_lib.product_log. Читает переменные окружения PRODUCTS_HOST,
///          PRODUCTS_USER, PRODUCTS_PASS; при отсутствии любой из них клиент
///          отключается (методы становятся no-op, приложение не падает).
/// \see https://gitea.gentoos.ru/e.anisimov/products_log
 
#pragma once
 
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
 
namespace products_log {
 
/// HTTP-запрос, описывающий обращение к Products API.
struct HttpRequest {
  std::string method; ///< "GET" или "POST".
  std::string url; ///< Полный URL (путь уже URL-закодирован).
  std::string body;     ///< Тело запроса (для POST).
  std::string username; ///< Basic-auth пользователь (пусто = без авторизации).
  std::string password; ///< Basic-auth пароль.
  int timeout_seconds = 5; ///< Таймаут запроса в секундах.
};
 
/// Ответ на запрос.
struct HttpResponse {
  bool ok = false; ///< true, если транспорт донёс запрос до сервера.
  int status = 0; ///< HTTP-код статуса (0 при транспортной ошибке).
  std::string body; ///< Тело ответа.
  std::string error; ///< Описание ошибки (без секретов).
};
 
/// Транспорт HTTP — функция, выполняющая запрос. Заменяемая для тестов.
using Transport = std::function<HttpResponse(const HttpRequest &)>;
 
/// Клиент Products API.
///
/// При инициализации не обращается к сети: идентификатор продукта
/// находится/регистрируется лениво, при первой отправке сообщения.
/// Если PRODUCTS_HOST / PRODUCTS_USER / PRODUCTS_PASS не заданы (или
/// переданы пустыми), клиент становится неактивным — все методы возвращают
/// false и логируют предупреждение в stderr.
class ProductsLog {
public:
  /// Конфигурация из переменных окружения PRODUCTS_HOST / PRODUCTS_USER /
  /// PRODUCTS_PASS. Версия продукта обычно приходит из PRODUCTS_VERSION.
  explicit ProductsLog(std::string product_name, std::string product_version,
                       Transport transport = DefaultTransport());
 
  /// Явная конфигурация (не зависит от окружения; используется в тестах).
  /// version и baseUrl могут быть пустыми — тогда включается запасной вариант:
  /// version="UNKNOWN", base_url из окружения.
  ProductsLog(std::string product_name, std::string product_version,
              std::string base_url, std::string username, std::string password,
              Transport transport = DefaultTransport());
 
  ProductsLog(const ProductsLog &) = delete;
  ProductsLog &operator=(const ProductsLog &) = delete;
  ~ProductsLog() = default;
 
  /// Активен ли клиент (все credentials заданы).
  bool enabled() const { return enabled_; }
 
  /// Отправить запись статистики. Возвращает false при любой ошибке.
  bool PostMessage(const std::string &comment);
  /// Отправить "Program started".
  bool PostStart();
  /// Отправить "Program shutdown".
  bool PostShutdown();
 
private:
  bool ResolveProductId();
  bool SendStat(int64_t product_id, const std::string &comment);
  std::optional<int64_t> FindProductId();
  std::optional<int64_t> RegisterProduct();
 
  static Transport DefaultTransport();
  static std::string UrlEncode(const std::string &s);
  static std::string JsonEscape(const std::string &s);
  static std::optional<int64_t> ParseProductId(const std::string &body);
 
  std::string product_name_;
  std::string product_version_;
  std::string base_url_;
  std::string username_;
  std::string password_;
  bool enabled_ = false;
  std::optional<int64_t> product_id_;
  Transport transport_;
};
 
} // namespace products_log