From 71b904a93bc9e846552fa9102ecc2b531cdac420 Mon Sep 17 00:00:00 2001 From: Martino Ferrari Date: Sat, 31 Oct 2026 19:54:23 +0100 Subject: [PATCH] docs: settle source-plugin implementation details in the spec --- .../specs/2026-10-31-source-plugins-design.md | 29 +++++++++++++------ 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/docs/superpowers/specs/2026-10-31-source-plugins-design.md b/docs/superpowers/specs/2026-10-31-source-plugins-design.md index 802cebb..21ed3f1 100644 --- a/docs/superpowers/specs/2026-10-31-source-plugins-design.md +++ b/docs/superpowers/specs/2026-10-31-source-plugins-design.md @@ -42,19 +42,24 @@ later plugins need. (a TOML table), the `--source-opt` form, and what a config widget reads and writes. - **`Frame`**: source-neutral, mirrors `udps_frame_t`: `counter`, `lost`, `late`, `recv_time`, `publish_mode`, `num_samples`, `signals[]` (the existing `SignalInfo`) and - `values[]` (doubles). The hole, backfill and time-base logic needs `counter/lost/late`; a + `values[]` (doubles). `signals` and `values` are pointers into the source's own buffers, + valid only for the duration of `on_data`; `Acquisition` copies what it keeps. The hole, backfill and time-base logic needs `counter/lost/late`; a source with no counter supplies a running counter and `lost = 0`. `Frame::value(sig, k, col)` replaces `udps_frame_value`. - **`DataSource`**: the per-connection object. - `open()`, `poll(timeout_ms)`, `close()`. - `stats()` returns the counters now in `StreamStats`; `connected()` reports link state. - - `post(Command)`: thread-safe queue, drained inside `poll()`. + - `post(Command)`: thread-safe queue, drained inside `poll()`. `Command` is + `std::function`. - `set_datagram_tap(fn)`: optional; lets UDP-based sources feed the raw-packet capture. - Output goes to a `SourceSink` (`on_config`, `on_data`, `on_event`) called inside `poll()`, as `udps_client` does today. - **`SourceKind`**: factory and UI description of one plugin type: `id`, `display_name`, - `identity(cfg)`, `make(cfg)`, `make_config_form(cfg)` (a `GtkWidget*` plus a `read()` - closure) and `make_panels(source)` (each `{id, title, GtkWidget*}`). + `identity(cfg)`, `make(cfg)`, `make_config_form()` and `make_panels(source)` (each + `{id, title, GtkWidget*}`). `make_config_form()` takes no argument: the chooser calls + `form.write(cfg)` to fill the form. A `ConfigForm` is a list of `AdwPreferencesRow` widgets + plus `write` / `read` / `valid` / `on_change` closures, so the chooser can place the rows in + its own group and gate its Connect button on `valid()`. - **`SourceRegistry`**: filled by an explicit `register_builtin_sources()` call. No static-init self-registration (linkers can drop it). A future `dlopen` loader would only call `register_kind()`. @@ -62,7 +67,8 @@ later plugins need. ### 2. Acquisition and the UDPS plugin - `Acquisition` takes a `std::unique_ptr` instead of building a `udps_client_t` - and implements `SourceSink`; the four trampolines go away. + and implements `SourceSink`; it creates the source lazily in `start()`, from the kind and + `SourceConfig` it was given; the four trampolines go away. - `on_config` / `on_data` change only in the type they read. Time base, holes, backfill, decimation, trigger and math code are untouched. - `run()` calls `source_->poll(50)` and copies `source_->stats()` into @@ -81,7 +87,8 @@ later plugins need. interface) moves into the UDPS plugin. The dialog keeps the known-sources list, buffer size, relative time and capture ring size. - **Capability panels**: after the source is created the app calls `make_panels()` and adds - each panel as a page of a "Source" stack in the side area. A panel is insensitive when + each panel as a page of the existing `side_stack` (the side area's page stack, owned by + the tab switcher). A panel is insensitive when disconnected (disabled, not hidden; the tab switcher owns visibility). A source with no panels adds no tab; UDPS has none. Panels call `source->post(Command)`, never the source directly, so cross-thread safety lives in one place. A helper kit for common panels (DIO @@ -90,8 +97,10 @@ later plugins need. - **Config / CLI**: `Config` gains `source_kind` (default `udps`) and a `SourceConfig`. `--server/--port/--multicast/--interface` populate the UDPS entries. `--source NAME` and repeatable `--source-opt k=v` work for any kind. `--help` lists the registered kinds. -- **Sessions**: file `_.toml` with the source's config in a `[source]` - table. Legacy `host_port.toml` is read as `udps`; nothing is migrated destructively. +- **Sessions**: the source's config is stored as top-level TOML keys, `source_kind` and + `source_opt_`, written only for non-UDPS kinds (a UDPS session file is unchanged, so + legacy `host_port.toml` files read as `udps` with nothing migrated). It is not a `[source]` + table. A non-UDPS session file is named by a pseudo-host `-` with port 1. - **Mocks**: `tools/mock_udpstreamer.py` remains the UDPS mock. Each later plugin ships its own mock under `tools/` so the headless self-check keeps working. @@ -99,7 +108,9 @@ later plugins need. - This is a pure refactor for UDPS: the existing headless self-check must read exactly as on `main` -- exactly three build warnings, no `Gtk-CRITICAL` (see `docs/claude/verification.md`). -- New probe `UDPSCOPE_PROBE_SOURCES`, extending the probe/dump in `src/ui.cpp` rather than +- New probe `UDPSCOPE_PROBE_SOURCE_KINDS` (`UDPSCOPE_PROBE_SOURCES` is already the chooser + discovery probe). Its value is a delay in ms, and its presence also registers the stub + `probe` kind. It extends the probe/dump in `src/ui.cpp` rather than adding a harness. It checks that the registry lists its kinds, that a config form round-trips its `SourceConfig`, and -- with a stub test-only kind carrying one panel -- that the panel's tab is built, insensitive while disconnected, and that a posted command is