Jungfraujoch/receiver/RugnuxLiveStatus.h

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <chrono>
#include <memory>
#include <mutex>
#include <optional>
#include <string>
#include <utility>
#include <vector>

class RugnuxStructure;   // RugnuxStructure.h

// Where the live rugnux run of the last collection is, for the broker's status route: the steps it has
// taken with what each found ("lattice found", "space group P 21 21 21"), the step it is on and how far
// into its images, and - once it is over - its verdict and summary as the report states them, and the
// latency from the last image to every result written.
//
// Times are those of the image puller - when a message came off the socket - and every time reported is
// in seconds since the first image arrived; until it has, since now. The START message comes earlier, by
// start_to_first_image_s. The collection's frame rate is (images_received - 1) / last_image_s.
enum class RugnuxLiveState { Idle, Running, Done, Failed, Cancelled, Skipped };

struct RugnuxLiveStep {
    std::string title;
    double started_s = 0.0;               // since the first image
    std::optional<double> duration_s;     // set once the next step starts or the run ends
    std::vector<std::string> notes;
};

struct RugnuxLiveSnapshot {
    RugnuxLiveState state = RugnuxLiveState::Idle;
    std::string message;                  // why it failed or was skipped
    int64_t images_expected = 0;
    std::optional<double> expected_collection_s; // images_expected x the image time, as set up
    int64_t images_received = 0;
    double elapsed_s = 0.0;
    std::optional<float> step_progress;   // fraction of the current pass's images
    std::vector<RugnuxLiveStep> steps;
    // The lattice probe on the first 60 degrees (JFJochReceiverRugnux::ProbeThread): an early answer
    // to "is there a crystal", seconds into the collection; the run's own answer comes later.
    std::string probe;
    std::optional<double> probe_s;        // when it answered
    std::optional<double> start_to_first_image_s; // from the START message to the first image
    std::optional<double> last_image_s;   // when the last image arrived; set once the collection is over
    // The analysis was cut - "deadline" (the broker's deadline_s after the last image) or "cancel" - at
    // cut_s; what it had established went out, the steps after it were left out.
    std::string cut;
    std::optional<double> cut_s;
    std::optional<double> last_image_to_written_s;
    std::string verdict;                  // OK | WARNINGS | UNUSABLE | FAILED
    std::string verdict_text;
    std::vector<std::pair<std::string, std::string>> summary;
    std::vector<std::string> warnings;
    // The placed model and its maps, once the run has placed one; for the viewer routes.
    std::shared_ptr<const RugnuxStructure> structure;
};

class RugnuxLiveStatus {
    mutable std::mutex m;
    RugnuxLiveSnapshot s;
    // Kept since the START message, shifted to the first image by Get().
    std::chrono::steady_clock::time_point start;
    std::optional<std::chrono::steady_clock::time_point> last_image;
    double Since(std::chrono::steady_clock::time_point t) const;
    double Now() const;
    void CloseStep();
public:
    // start_received, received: when the START message and the image came off the socket (ImagePullerOutput);
    // expected_collection_s: how long the collection is set up to take, none if not known
    void Start(int64_t images_expected, std::optional<double> expected_collection_s,
               std::chrono::steady_clock::time_point start_received);
    void ImageReceived(std::chrono::steady_clock::time_point received);
    void Step(const std::string &title);
    void Note(const std::string &text);
    void Progress(uint64_t done, uint64_t total);
    void Finish(RugnuxLiveState state, const std::string &message = "");
    void Result(const std::string &verdict, const std::string &verdict_text,
                const std::vector<std::pair<std::string, std::string>> &summary,
                const std::vector<std::string> &warnings);
    void Latency(double last_image_to_written_s);
    // The collection is over: last_image_s is set, and the last image's time is returned (none if no image came).
    std::optional<std::chrono::steady_clock::time_point> LastImage();
    void Cut(const std::string &reason);
    void Probe(const std::string &text);
    void Warning(const std::string &text);
    void Structure(std::shared_ptr<const RugnuxStructure> structure);
    // Back to Idle with nothing of the last run, as before any collection.
    void Clear();
    RugnuxLiveSnapshot Get() const;
};