working on todo.md features

src/event_store.hpp

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 Martino Ferrari
+
+#pragma once
+
+#include "export.hpp"
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace udpscope {
+
+/// What a cached event is, without loading its samples: the sidecar's fields, and what the pane
+/// shows in one row.
+struct EventRecord {
+  std::string stem;         ///< the file's name without the extension
+  std::string file;         ///< `<stem>.npy`, the event's table in the export format
+  std::string thumbnail;    ///< `<stem>.bmp`, the preview drawn from the samples; else empty
+  double wall_time = 0.0;   ///< CLOCK_REALTIME at the latch, for the row's label
+  double duration_s = 0.0;  ///< pre + post
+  double pre_s = 0.0;
+  double post_s = 0.0;
+  double edge = 0.0;        ///< the stream time of the event's x = 0
+  double rate_hz = 0.0;     ///< the stored sample rate at the latch
+  std::size_t signals = 0;  ///< columns in the file
+  std::size_t samples = 0;  ///< rows
+  std::uint64_t seq = 0;    ///< the run's own event counter, so two events in one second differ
+};
+
+/// The cache of captured events: `<cache_dir>/<source>/events/`, one `.npy` per event written in
+/// the **export format** -- so `--open` and the chooser's Waveforms page read it back with the
+/// loader that already exists -- beside a `.txt` sidecar holding what the list shows without
+/// loading the samples, and whatever thumbnail the caller rendered.
+///
+/// No GTK: the caller renders the thumbnail and hands over a path, exactly as it hands over the
+/// table. The store owns naming, the sidecar, pruning and listing, which is what makes it testable
+/// without a window.
+class EventStore {
+ public:
+  /// `source` is the `<host>-<port>` pair, the same key the packet capture uses.
+  explicit EventStore(std::string source = {});
+
+  /// How many events to keep, newest first. The oldest beyond it are deleted on every save; item 9's
+  /// preferences are where this becomes the user's number.
+  static constexpr std::size_t kDefaultKeep = 32;
+
+  const std::string& dir() const noexcept { return dir_; }
+  bool empty_dir() const noexcept { return dir_.empty(); }
+
+  /// Writes `table` as one event, with `meta` in the sidecar and a preview drawn beside it. Returns
+  /// the samples' path, or an empty string on failure -- a cache that cannot be written must not stop
+  /// the scope.
+  ///
+  /// The preview is drawn from the *data* -- min/max per pixel column, one strip per signal -- and not
+  /// captured from the window: the plot is a `GtkGLArea`, and a GL area's ink is not in the widget's
+  /// paint tree, so a snapshot of it is empty (`gtk_snapshot_free_to_node()` returns NULL). Drawing it
+  /// here also keeps this class GTK-free, which is what makes it testable without a window.
+  std::string save(const ExportTable& table, const EventRecord& meta,
+                   std::size_t keep = kDefaultKeep);
+
+  /// The cached events, newest first: the sidecars, never the sample files, so a listing is cheap
+  /// however large the captures are.
+  std::vector<EventRecord> list() const;
+
+  /// Deletes one event's samples, sidecar and thumbnail.
+  bool forget(const std::string& stem);
+
+  /// Deletes the oldest events beyond `keep`.
+  void prune(std::size_t keep) const;
+
+ private:
+  std::string dir_;
+};
+
+/// The sidecar's text, and back. One `key = value` per line, the project's own TOML subset, so a
+/// human can read the cache with `cat` -- which is the point of a forensic directory.
+std::string event_meta_text(const EventRecord& record);
+bool event_meta_parse(const std::string& text, EventRecord* out);
+
+}  // namespace udpscope