Improve dfctl TUI activity and docs

lquerel · lquerel · commit 854f3a30f737 · 2026-04-24T22:08:26.000-07:00
diff --git a/rust/otap-dataflow/crates/enginectl/README.md b/rust/otap-dataflow/crates/enginectl/README.md
@@ -6,6 +6,27 @@ It is built on top of the public Rust SDK `otap-df-admin-api`, but end users
 should think in terms of the installed `dfctl` command. The Rust package name
 for this crate remains `otap-df-enginectl`.
 
+## Design Goals
+
+`dfctl` is intended to be the practical control surface for local and remote
+OTAP Dataflow Engine instances:
+
+- expose the public admin SDK without inventing a parallel protocol
+- keep local and remote engine workflows consistent
+- provide stable machine-readable output for scripts, CI, and agents
+- provide readable tables, color, diagnostics, and a TUI for humans
+- make long-running operations observable with watch streams and progress
+  feedback
+- keep mutation flows safe through confirmation, dry-run or preflight checks,
+  and clear failure reporting where possible
+- keep commands, renderers, TUI panes, and tests modular enough to evolve with
+  the admin API
+
+For the full design principles, see
+[docs/admin/enginectl.md](../../docs/admin/enginectl.md#design-principles).
+For security and privacy behavior, see
+[docs/admin/enginectl.md](../../docs/admin/enginectl.md#security-and-privacy).
+
 ## Before You Start
 
 - The default admin target is `http://127.0.0.1:8085`.
diff --git a/rust/otap-dataflow/crates/enginectl/src/ui/app/model.rs b/rust/otap-dataflow/crates/enginectl/src/ui/app/model.rs
@@ -759,6 +759,12 @@ pub(crate) struct EnginePipelineItem {
     pub(crate) rollout: String,
 }
 
+#[derive(Clone, Debug, Default, Eq, PartialEq)]
+pub(crate) struct ActivityIndicator {
+    pub(crate) active: bool,
+    pub(crate) frame: u16,
+}
+
 #[derive(Clone, Debug)]
 pub(crate) struct AppState {
     pub(crate) view: View,
@@ -783,6 +789,7 @@ pub(crate) struct AppState {
     pub(crate) engine_readyz: Option<engine::ProbeResponse>,
     pub(crate) engine_vitals: EngineVitals,
     pub(crate) command_context: UiCommandContext,
+    pub(crate) activity_indicator: ActivityIndicator,
     pub(crate) pipelines: PipelinePaneState,
     pub(crate) groups: GroupPaneState,
     pub(crate) engine: EnginePaneState,
diff --git a/rust/otap-dataflow/crates/enginectl/src/ui/app/state.rs b/rust/otap-dataflow/crates/enginectl/src/ui/app/state.rs
@@ -30,6 +30,7 @@ impl AppState {
             engine_readyz: None,
             engine_vitals: EngineVitals::default(),
             command_context: UiCommandContext::local_default(logs_tail),
+            activity_indicator: ActivityIndicator::default(),
             pipelines: PipelinePaneState::default(),
             groups: GroupPaneState::default(),
             engine: EnginePaneState::new(),
@@ -418,6 +419,29 @@ impl AppState {
         &self.command_context.target_url
     }
 
+    pub(crate) fn begin_activity(&mut self) {
+        self.activity_indicator.active = true;
+    }
+
+    pub(crate) fn end_activity(&mut self) {
+        self.activity_indicator.active = false;
+        self.activity_indicator.frame = 0;
+    }
+
+    pub(crate) fn is_activity_active(&self) -> bool {
+        self.activity_indicator.active
+    }
+
+    pub(crate) fn activity_frame(&self) -> u16 {
+        self.activity_indicator.frame
+    }
+
+    pub(crate) fn advance_activity_frame(&mut self) {
+        if self.activity_indicator.active {
+            self.activity_indicator.frame = self.activity_indicator.frame.wrapping_add(1);
+        }
+    }
+
     pub(crate) fn active_header(&self) -> Option<&DetailHeader> {
         match self.view {
             View::Pipelines => match self.pipeline_tab {
diff --git a/rust/otap-dataflow/crates/enginectl/src/ui/mod.rs b/rust/otap-dataflow/crates/enginectl/src/ui/mod.rs
@@ -74,7 +74,7 @@ use std::sync::{
 use std::thread;
 use std::time::Duration;
 use tempfile::Builder;
-use tokio::sync::mpsc;
+use tokio::{sync::mpsc, time::MissedTickBehavior};
 
 pub(crate) use self::refresh::build_command_context;
 
@@ -107,38 +107,34 @@ pub(crate) async fn run_ui(
     let refresh_in_flight = Arc::new(AtomicBool::new(false));
 
     let mut refresh = tokio::time::interval(args.refresh_interval);
+    refresh.set_missed_tick_behavior(MissedTickBehavior::Skip);
     let _ = refresh.tick().await;
+    let mut activity_tick = tokio::time::interval(Duration::from_millis(120));
+    activity_tick.set_missed_tick_behavior(MissedTickBehavior::Skip);
+    let _ = activity_tick.tick().await;
 
     let result = loop {
         session.draw(&mut app)?;
 
         tokio::select! {
             _ = tokio::signal::ctrl_c() => break Ok(()),
+            _ = activity_tick.tick(), if app.is_activity_active() => {
+                app.advance_activity_frame();
+            }
             _ = refresh.tick() => {
-                spawn_refresh_task(
-                    client.clone(),
-                    app.clone(),
-                    args.clone(),
-                    tx.clone(),
-                    refresh_in_flight.clone(),
-                );
+                request_refresh(client, &mut app, &args, &tx, &refresh_in_flight);
             }
             Some(event) = rx.recv() => {
                 match event {
                     UiEvent::RefreshComplete(refreshed) => {
                         apply_refreshed_app(&mut app, *refreshed);
+                        app.end_activity();
                     }
                     UiEvent::Terminal(event) => {
                         match handle_event(event, &mut app) {
                             EventOutcome::Quit => break Ok(()),
                             EventOutcome::Refresh => {
-                                spawn_refresh_task(
-                                    client.clone(),
-                                    app.clone(),
-                                    args.clone(),
-                                    tx.clone(),
-                                    refresh_in_flight.clone(),
-                                );
+                                request_refresh(client, &mut app, &args, &tx, &refresh_in_flight);
                             }
                             EventOutcome::OpenPipelineEditor { group_id, pipeline_id } => {
                                 if let Err(err) = stage_pipeline_editor_draft(
@@ -155,27 +151,15 @@ pub(crate) async fn run_ui(
                                 {
                                     app.last_error = Some(err.to_string());
                                 }
-                                spawn_refresh_task(
-                                    client.clone(),
-                                    app.clone(),
-                                    args.clone(),
-                                    tx.clone(),
-                                    refresh_in_flight.clone(),
-                                );
+                                request_refresh(client, &mut app, &args, &tx, &refresh_in_flight);
                             }
                             EventOutcome::Execute(action) => {
                                 if let Err(err) =
                                     execute_ui_action(client, &mut app, &args, action).await
                                 {
                                     app.last_error = Some(err.to_string());
                                 }
-                                spawn_refresh_task(
-                                    client.clone(),
-                                    app.clone(),
-                                    args.clone(),
-                                    tx.clone(),
-                                    refresh_in_flight.clone(),
-                                );
+                                request_refresh(client, &mut app, &args, &tx, &refresh_in_flight);
                             }
                             EventOutcome::Continue => {}
                         }
@@ -192,25 +176,44 @@ pub(crate) async fn run_ui(
     result
 }
 
+fn request_refresh(
+    client: &AdminClient,
+    app: &mut AppState,
+    args: &UiArgs,
+    tx: &mpsc::Sender<UiEvent>,
+    refresh_in_flight: &Arc<AtomicBool>,
+) {
+    if spawn_refresh_task(
+        client.clone(),
+        app.clone(),
+        args.clone(),
+        tx.clone(),
+        refresh_in_flight.clone(),
+    ) {
+        app.begin_activity();
+    }
+}
+
 fn spawn_refresh_task(
     client: AdminClient,
     mut app: AppState,
     args: UiArgs,
     tx: mpsc::Sender<UiEvent>,
     refresh_in_flight: Arc<AtomicBool>,
-) {
+) -> bool {
     if refresh_in_flight
         .compare_exchange(false, true, Ordering::Relaxed, Ordering::Relaxed)
         .is_err()
     {
-        return;
+        return false;
     }
 
     let _handle = tokio::spawn(async move {
         refresh_view(&client, &mut app, &args).await;
         refresh_in_flight.store(false, Ordering::Relaxed);
         let _ = tx.send(UiEvent::RefreshComplete(Box::new(app))).await;
     });
+    true
 }
 
 fn apply_refreshed_app(app: &mut AppState, refreshed: AppState) {
@@ -234,6 +237,7 @@ fn apply_refreshed_app(app: &mut AppState, refreshed: AppState) {
     let detail_scroll = app.detail_scroll;
     let terminal_size = app.terminal_size;
     let command_context = app.command_context.clone();
+    let activity_indicator = app.activity_indicator.clone();
 
     *app = refreshed;
     app.view = view;
@@ -248,6 +252,7 @@ fn apply_refreshed_app(app: &mut AppState, refreshed: AppState) {
     app.detail_scroll = detail_scroll;
     app.terminal_size = terminal_size;
     app.command_context = command_context;
+    app.activity_indicator = activity_indicator;
 }
 
 #[cfg(test)]
diff --git a/rust/otap-dataflow/crates/enginectl/src/ui/view/chrome.rs b/rust/otap-dataflow/crates/enginectl/src/ui/view/chrome.rs
@@ -83,20 +83,64 @@ pub(super) fn draw_top_tabs(frame: &mut Frame<'_>, area: Rect, app: &AppState) {
 }
 
 pub(super) fn draw_title_bar(frame: &mut Frame<'_>, area: Rect, app: &AppState) {
-    let line = Line::from(vec![
-        Span::styled("Open", open_brand_style(app.color_enabled)),
-        Span::styled("Telemetry", telemetry_brand_style(app.color_enabled)),
+    let mut spans = brand_spans(app);
+    spans.extend([
         Span::styled(" - Rust Dataflow Engine", title_style(app.color_enabled)),
         Span::styled("  |  ", separator_style(app.color_enabled)),
         Span::styled("target ", muted_style(app.color_enabled)),
         Span::styled(app.target_url(), target_style(app.color_enabled)),
     ]);
+    let line = Line::from(spans);
     let title = Paragraph::new(line)
         .alignment(Alignment::Left)
         .style(page_style(app.color_enabled));
     frame.render_widget(title, area);
 }
 
+pub(super) fn brand_spans(app: &AppState) -> Vec<Span<'static>> {
+    if !app.color_enabled || !app.is_activity_active() {
+        return vec![
+            Span::styled("Open", open_brand_style(app.color_enabled)),
+            Span::styled("Telemetry", telemetry_brand_style(app.color_enabled)),
+        ];
+    }
+
+    "OpenTelemetry"
+        .chars()
+        .enumerate()
+        .map(|(index, character)| {
+            Span::styled(
+                character.to_string(),
+                shimmering_brand_style(index, app.activity_frame()),
+            )
+        })
+        .collect()
+}
+
+fn shimmering_brand_style(index: usize, frame: u16) -> Style {
+    let base_style = if index < "Open".len() {
+        open_brand_style(true)
+    } else {
+        telemetry_brand_style(true)
+    };
+    let brand_len = "OpenTelemetry".len();
+    let cycle_len = brand_len + 4;
+    let center = (usize::from(frame) % cycle_len) as isize - 2;
+    let distance = (index as isize - center).unsigned_abs();
+
+    match distance {
+        0 => base_style
+            .fg(Color::Rgb(238, 250, 255))
+            .bg(Color::Rgb(35, 72, 86))
+            .add_modifier(Modifier::BOLD),
+        1 => base_style
+            .fg(Color::Rgb(170, 231, 232))
+            .add_modifier(Modifier::BOLD),
+        2 => base_style.fg(Color::Rgb(113, 177, 211)),
+        _ => base_style,
+    }
+}
+
 pub(super) fn draw_engine_vitals_panel(
     frame: &mut Frame<'_>,
     area: Rect,
diff --git a/rust/otap-dataflow/crates/enginectl/src/ui/view/tests.rs b/rust/otap-dataflow/crates/enginectl/src/ui/view/tests.rs
@@ -117,6 +117,36 @@ fn title_bar_and_command_overlay_render() {
     assert!(rendered.contains("https://admin.example.com:8443/engine-a"));
 }
 
+/// Scenario: activity is in progress while the title bar is rendered.
+/// Guarantees: the shimmer splits the brand into fixed-position character
+/// spans without changing the visible OpenTelemetry label text.
+#[test]
+fn active_brand_shimmer_preserves_label_text() {
+    let mut app = AppState::new(UiStartView::Pipelines, true, 200);
+    assert_eq!(chrome::brand_spans(&app).len(), 2);
+
+    app.begin_activity();
+    app.advance_activity_frame();
+    app.advance_activity_frame();
+
+    let active_spans = chrome::brand_spans(&app);
+    let label = active_spans
+        .iter()
+        .map(|span| span.content.as_ref())
+        .collect::<String>();
+    assert_eq!(label, "OpenTelemetry");
+    assert_eq!(active_spans.len(), "OpenTelemetry".len());
+    assert!(
+        active_spans
+            .iter()
+            .any(|span| span.style != open_brand_style(true)
+                && span.style != telemetry_brand_style(true))
+    );
+
+    app.end_activity();
+    assert_eq!(chrome::brand_spans(&app).len(), 2);
+}
+
 /// Scenario: the header renders a fresh engine-vitals snapshot.
 /// Guarantees: the condensed vitals rail shows CPU, RSS, and pressure
 /// values without reintroducing the removed dedicated panel title.
diff --git a/rust/otap-dataflow/docs/admin/README.md b/rust/otap-dataflow/docs/admin/README.md
@@ -10,7 +10,8 @@ This section documents the admin surface of the OTAP Dataflow Engine:
 ## Document map
 
 - [Admin UI Architecture](architecture.md)
-- [dfctl CLI](enginectl.md)
+- [dfctl CLI](enginectl.md) including command reference, output modes, and
+  design principles
 - [Live Pipeline Reconfiguration](live-reconfiguration.md)
 - [Crate README (admin endpoints and crate layout)](../../crates/admin/README.md)
 - [Public Rust SDK README](../../crates/admin-api/README.md)
diff --git a/rust/otap-dataflow/docs/admin/enginectl.md b/rust/otap-dataflow/docs/admin/enginectl.md
