api.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
// The GUI API surface, expressed as plain functions over a ProjectDB.
//
// Everything here is deliberately HTTP-framework-free: handlers take a
// ProjectDB (plus already-parsed parameters) and return JSON or bytes, and
// signal failure by throwing HttpError. gui/Server.hpp is the only place that
// knows about Crow. That split is what makes the contract unit-testable
// (tests/unit/rux_gui/) without standing up a socket.
//
// The contract these functions implement is docs/gui/openapi.yaml. Any change
// here that alters a response shape is a change to that document too.
 
#include <reusex/pipeline/JobRunner.hpp>
#include <reusex/pipeline/stages.hpp>
 
#include <nlohmann/json.hpp>
 
#include <cstdint>
#include <filesystem>
#include <functional>
#include <map>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
namespace reusex {
class ProjectDB;
}
 
namespace rux::gui {

inline constexpr std::string_view kApiVersion = "1.0.0";
inline constexpr std::string_view kApiPrefix = "/api/v1";
inline constexpr std::string_view kImplementation = "rux-gui";
 
// --- paging ---------------------------------------------------------------
//
// Every collection that grows with the size of a scan is paged the same way:
// `offset` + `limit` in, an `offset`/`count`/`total` envelope out. `limit=0`
// means "the server maximum" — a real number per resource, never "unbounded",
// so no request can ask the server to materialize an arbitrarily large
// response. The maxima differ only where the per-item cost differs.

inline constexpr size_t kMaxPointsPerPage = 1000000;
inline constexpr size_t kDefaultPointsPerPage = 100000;

inline constexpr int kMaxLogEntries = 1000;
inline constexpr int kDefaultLogEntries = 100;

inline constexpr int kMaxCollectionItems = 1000;

inline constexpr int kMaxFrameIds = 10000;

inline constexpr int kMaxImageSize = 4096;

inline constexpr int kWriteLockTimeoutMs = 250;

class HttpError : public std::runtime_error {
    public:
  HttpError(int status, std::string message)
      : std::runtime_error(std::move(message)), status_(status) {}
 
  int status() const noexcept { return status_; }
 
    private:
  int status_;
};

struct Blob {
  std::string content_type;
  std::vector<uint8_t> data;
};

struct Endpoint {
  std::string method;
  std::string path;    
  std::string summary; 
  bool binary = false; 
};

const std::vector<Endpoint> &endpoint_table();

class Params {
    public:
  void set(std::string key, std::string value);
  std::optional<std::string> find(std::string_view key) const;

  std::string str(std::string_view key, std::string fallback) const;

  long long integer(std::string_view key, long long fallback) const;

  std::optional<bool> boolean(std::string_view key) const;
 
    private:
  std::map<std::string, std::string, std::less<>> values_;
};
 
// --- paging ---------------------------------------------------------------
//
// Declared after Params, which these take by reference.

struct PageRequest {
  uint64_t offset = 0;
  uint64_t limit = 0;
};

struct PageWindow {
  size_t first = 0;
  size_t last = 0;
  size_t total = 0;
 
  size_t count() const noexcept { return last - first; }
};

PageRequest parse_page_request(const Params &params, long long default_limit,
                               long long max_limit);

PageWindow page_window(const PageRequest &page, size_t total);

void add_page_envelope(nlohmann::json &object, const PageWindow &window);
 
// --- error / meta ---------------------------------------------------------
 
nlohmann::json error_json(int status, std::string_view message);

nlohmann::json health_json(const reusex::ProjectDB *db,
                           const std::filesystem::path &project);
 
nlohmann::json endpoints_json();
 
// --- project --------------------------------------------------------------

nlohmann::json project_summary_json(const reusex::ProjectDB &db);
 
nlohmann::json projects_json(const reusex::ProjectDB &db, const Params &params);
 
// --- clouds ---------------------------------------------------------------
 
nlohmann::json clouds_json(const reusex::ProjectDB &db, const Params &params);
nlohmann::json cloud_json(const reusex::ProjectDB &db, const std::string &name);

nlohmann::json cloud_labels_json(const reusex::ProjectDB &db,
                                 const std::string &name);

nlohmann::json cloud_points_json(const reusex::ProjectDB &db,
                                 const std::string &name, const Params &params);

struct PointsResponse {
  std::optional<nlohmann::json> body; 
  std::optional<Blob> blob;           
  std::vector<std::pair<std::string, std::string>> headers;
};

PointsResponse cloud_points(const reusex::ProjectDB &db,
                            const std::string &name, const Params &params);
 
// --- meshes ---------------------------------------------------------------
 
nlohmann::json meshes_json(const reusex::ProjectDB &db, const Params &params);
nlohmann::json mesh_json(const reusex::ProjectDB &db, const std::string &name);
nlohmann::json mesh_textures_json(const reusex::ProjectDB &db,
                                  const std::string &name);
Blob mesh_data_blob(const reusex::ProjectDB &db, const std::string &name);
Blob mesh_texture_blob(const reusex::ProjectDB &db, const std::string &name,
                       const std::string &texture);
 
// --- sensor frames --------------------------------------------------------

struct ValueRange {
  bool valid = false;
  double min = 0.0;
  double max = 0.0;
};

struct ImageResponse {
  Blob blob;
  ValueRange range; 
};

nlohmann::json frames_json(const reusex::ProjectDB &db, const Params &params);
nlohmann::json frame_json(const reusex::ProjectDB &db, int id);

ImageResponse frame_image(const reusex::ProjectDB &db, int id,
                          const Params &params);
 
// --- panoramas ------------------------------------------------------------
 
nlohmann::json panoramas_json(const reusex::ProjectDB &db,
                              const Params &params);
nlohmann::json panorama_json(const reusex::ProjectDB &db, int id);

Blob panorama_image_blob(const reusex::ProjectDB &db, int id,
                         const Params &params);
 
// --- components / materials / instances -----------------------------------
 
nlohmann::json components_json(const reusex::ProjectDB &db,
                               const Params &params);
nlohmann::json component_json(const reusex::ProjectDB &db,
                              const std::string &name);
nlohmann::json materials_json(const reusex::ProjectDB &db,
                              const Params &params);
nlohmann::json material_json(const reusex::ProjectDB &db,
                             const std::string &guid);
nlohmann::json instances_json(const reusex::ProjectDB &db,
                              const std::string &cloud, const Params &params);
 
// --- pipeline -------------------------------------------------------------
 
nlohmann::json stages_json(const reusex::ProjectDB &db);

nlohmann::json stage_validation_json(const reusex::ProjectDB &db,
                                     const std::string &stage);
nlohmann::json pipeline_log_json(const reusex::ProjectDB &db,
                                 const Params &params);
 
// --- jobs -----------------------------------------------------------------

nlohmann::json job_json(const reusex::pipeline::JobRecord &record,
                        std::string_view project);

nlohmann::json jobs_json(const std::vector<reusex::pipeline::JobRecord> &jobs,
                         std::string_view project);

nlohmann::json
jobs_page_json(const std::vector<reusex::pipeline::JobRecord> &jobs,
               std::string_view project, const Params &params);
nlohmann::json job_event_json(const reusex::pipeline::JobEvent &event,
                              std::string_view project);
nlohmann::json hello_json(const std::vector<reusex::pipeline::JobRecord> &jobs,
                          const std::filesystem::path &project);

struct JobSubmission {
  reusex::pipeline::JobStage stage = reusex::pipeline::JobStage::clouds;
  std::string parameters; 
  std::optional<std::string> project;
};

JobSubmission parse_job_request(std::string_view body);

void check_job_project(const JobSubmission &submission,
                       std::string_view open_project);

std::optional<nlohmann::json> handle_ws_message(
    std::string_view body,
    const std::function<void(std::optional<std::string>)> &subscribe);

bool event_matches_subscription(const reusex::pipeline::JobEvent &event,
                                const std::optional<std::string> &subscription);
 
} // namespace rux::gui