doctor_checks.hpp

Go to the documentation of this file.

/*
  ____             _              ____ _               _
 |  _ \  ___   ___| |_ ___  _ __ / ___| |__   ___  ___| | _____
 | | | |/ _ \ / __| __/ _ \| '__| |   | '_ \ / _ \/ __| |/ / __|
 | |_| | (_) | (__| || (_) | |  | |___| | | |  __/ (__|   <\__ \
 |____/ \___/ \___|\__\___/|_|   \____|_| |_|\___|\___|_|\_\___/
 
Pure, unit-testable check logic backing `mads doctor` (src/main/doctor.cpp).
 
Every function here either performs a small, self-contained, dependency-light
check (settings-file parsing via toml++, CURVE key well-formedness via
libzmq's Z85 codec, reading the pinned plugin protocol out of a JSON manifest
text) or is a pure *evaluator* that turns already-collected facts (a broker
probe's boolean result, a dry-run plugin load's outcome) into a CheckResult.
 
Deliberately NOT here: the actual pugg::Kernel-based plugin dry-run load. That
needs the mads_plugin headers (source.hpp/filter.hpp/sink.hpp) and pugg's
Kernel.h, which -- exactly like mads-source/-filter/-sink -- are only on the
include path for src/main (see the top-level CMakeLists.txt's
`include_directories()` call, scoped to src/main and src/plugin). So the
actual dlopen/registration/create() sequence
lives in src/main/doctor.cpp (mirroring src/main/plugin_loader.cpp), which
then hands the resulting facts to evaluate_plugin_load()/evaluate_plugin_protocol()
here for the pass/warn/fail decision -- keeping that decision logic testable
without linking pugg or building a real .plugin fixture.
 
Author(s): Paolo Bosetti
*/
#ifndef MADS_DOCTOR_CHECKS_HPP
#define MADS_DOCTOR_CHECKS_HPP
 
#include "broker_probe.hpp"
 
#include <chrono>
#include <cstdint>
#include <filesystem>
#include <optional>
#include <string>
 
namespace Mads {
namespace Doctor {
 
enum class Status { Pass, Warn, Fail };
 
struct CheckResult {
  std::string name;
  Status status = Status::Pass;
  std::string message;
  std::string fix_hint;
  bool fixable = false;
};
 
using CurveKeyCheck = Mads::ProbeCurveKeys;
 
/* ---- 1. Settings file found and parses ---------------------------------- */
 
CheckResult check_settings_file(const std::filesystem::path &path);
 
/* ---- 2. Broker reachable -------------------------------------------------
   The actual probe is Mads::probe_broker() (src/broker_probe.hpp, from P5);
   evaluate_broker_reachable() is split out so the pass/warn/fail wording is
   testable without a real socket.
 
   `curve` must be set whenever the broker runs with --crypto: the probe is an
   ordinary REQ round-trip, so an unencrypted one gets dropped in the ZMTP
   handshake and times out indistinguishably from a broker that is not there.
   `crypto` on the evaluator only selects the wording for that case. */
 
CheckResult evaluate_broker_reachable(const std::string &uri, bool reachable,
                                      bool crypto = false);
 
CheckResult
check_broker_reachable(const std::string &uri, std::chrono::milliseconds timeout,
                       const std::optional<CurveKeyCheck> &curve = std::nullopt);
 
/* ---- 3. Declared plugin(s) resolve and load (dry-run) -------------------- */
 
struct PluginLoadFacts {
  std::string plugin_file;   // path probed
  bool file_exists = false;
  bool loaded = false;       // load + driver lookup + create() all succeeded
  std::string driver_kind;   // "source" | "filter" | "sink" | "" (unknown)
  std::string driver_name;   // the created instance's own kind()
  int protocol_version = -1; // pugg::Driver::version(); -1 if unknown
  std::string error;         // populated when loaded == false
};
 
CheckResult evaluate_plugin_load(const PluginLoadFacts &facts);
 
/* ---- 4. Plugin protocol matches the pinned mads_plugin version ---------- */
 
constexpr int kMinSupportedPluginProtocol = 7;
 
std::optional<int> parse_pinned_plugin_protocol(const std::string &manifest_json_text);
 
CheckResult evaluate_plugin_protocol(int loaded_version,
                                     std::optional<int> pinned_version,
                                     int min_supported = kMinSupportedPluginProtocol);
 
/* ---- 5. CURVE key files exist and are well-formed ------------------------
   Uses CurveKeyCheck, declared at the top of this header because check 2
   needs it too. */
 
bool is_well_formed_curve_key(const std::string &key_line);
 
CheckResult check_curve_keys(const CurveKeyCheck &cfg);
 
/* ---- 6. Local port-availability sanity check ------------------------------
   The actual probe is Mads::probe_tcp_port() (src/broker_probe.hpp): its
   "true" means "something answered", i.e. the *opposite* of what doctor
   wants to hear before launching a broker on that port -- so the evaluator
   below inverts the pass/fail mapping relative to `ready = "port:<n>"`'s own
   use of the same probe. */
 
CheckResult evaluate_port_available(const std::string &host, int port, bool in_use);
 
CheckResult check_port_available(const std::string &host, int port,
                                 std::chrono::milliseconds timeout);
 
/* ---- 7. CURVE handshake actually succeeds ---------------------------------
   The actual probe is Mads::probe_curve_handshake() (src/broker_probe.hpp,
   from ZMQ_DEVELOPMENT.md §2.1); evaluate_curve_handshake() is split out so
   the pass/fail wording is testable without a real socket, mirroring
   check 2. Reuses CurveKeyCheck (check 5) for the key-file location. */
 
CheckResult evaluate_curve_handshake(const std::string &uri,
                                     CurveProbeResult result);
 
CheckResult check_curve_handshake(const std::string &uri, const CurveKeyCheck &cfg,
                                  std::chrono::milliseconds timeout);
 
/* ---- 8. Open-file limit leaves room for the fleet -------------------------
   The broker holds two descriptors per connected agent -- the agent's
   publisher on the XSUB frontend, its subscriber on the XPUB backend -- so
   RLIMIT_NOFILE, not anything in libzmq, is what bounds fleet size. The
   default soft limit of 1024 stops at roughly 495 agents, and libzmq refuses
   everything past it near-silently.
 
   Reported from *this* process's limit: doctor cannot see what a broker
   started under systemd would inherit, so the wording says "a broker started
   the same way as this check". The evaluator takes the limits as plain
   integers rather than the Mads::detail type that produces them, so this
   installed header stays free of src/detail/. */
 
CheckResult evaluate_fd_limit(bool supported, uint64_t soft, uint64_t hard,
                              std::optional<int64_t> configured);
 
CheckResult check_fd_limit(std::optional<int64_t> configured);
 
} // namespace Doctor
} // namespace Mads
 
#endif // MADS_DOCTOR_CHECKS_HPP