🐛 fix(web): publish status and usage as one pair (#2002)

The dashboard and the admin status page each loaded the status snapshot and the
usage counters into their own resource, refreshed on its own five-second
interval. Whichever half settled first was written straight to the page, so a
card could show listings counted seconds apart from the accepted-request total
printed above it. Neither combination was ever a state the server held.

Both pages now drive one resource that reads the snapshot and the counters
together, so every published pair comes from a single refresh. A refresh tick
that lands while the previous load is still outstanding is skipped rather than
stacking a second request on a slow endpoint, where the responses could arrive
out of order. A tick can also arrive after its route has been left, since the
interval outlives the page; reading the disposed resource would panic, and there
is nothing left to refresh.

The usage half of the pair carries its own outcome instead of failing the whole
load. `/+stats` is operator-scoped and answers `401` to every other reader, so
pairing that failure with the snapshot would leave anyone without the scope
looking at a blank dashboard, and a first load whose counters fail has no
earlier pair to fall back on. A pair whose usage half failed reports that
failure where the counters would go, never counters measured in another refresh.

Author: gaborbernat

crates/peryx-web/Cargo.toml

@@ -66,6 +66,7 @@ web-sys = { workspace = true, optional = true, features = [
     "XmlHttpRequestUpload",
 ] }
 base64 = { workspace = true, optional = true }
+futures-util.workspace = true
 peryx-core.workspace = true
 serde.workspace = true
 serde_json.workspace = true
@@ -78,7 +79,6 @@ minicov = { workspace = true, optional = true }
 [dev-dependencies]
 any_spawner = "0.3"
 async-trait.workspace = true
-futures-util.workspace = true
 peryx-policy.workspace = true
 peryx-events.workspace = true
 peryx-identity.workspace = true

crates/peryx-web/src/data/mod.rs

@@ -27,7 +27,7 @@ pub use search::load_search;
 #[cfg(all(not(feature = "ssr"), feature = "hydrate"))]
 pub use stats::load_analytics;
 pub use stats::load_stats;
-pub use status::{load_admin_snapshot, load_snapshot};
+pub use status::{UiOverview, load_admin_overview, load_overview};
 pub use topology::load_topology;
 #[cfg(all(not(feature = "ssr"), feature = "hydrate"))]
 pub use topology::{TopologyStream, subscribe_topology};

crates/peryx-web/src/data/status.rs

@@ -1,4 +1,4 @@
-use crate::model::UiSnapshot;
+use crate::model::{UiSnapshot, UiStats};
 
 #[cfg(all(not(feature = "ssr"), feature = "hydrate"))]
 use super::RequiredOption;
@@ -168,12 +168,47 @@ fn required<T>(value: Option<T>) -> Result<T, super::LoaderError> {
     value.ok_or(super::LoaderError::Invalid(super::LoaderEndpoint::Status))
 }
 
+/// A status snapshot and the usage counters read in the same refresh.
+///
+/// The usage half carries its own outcome because `/+stats` is operator-scoped: a reader without
+/// that scope is answered `401` on every poll, and failing the pair on it would leave the whole
+/// dashboard blank rather than show the indexes it is allowed to see.
+pub type UiOverview = (UiSnapshot, Result<UiStats, super::LoaderError>);
+
+/// The dashboard snapshot and the usage counters measured beside it.
+///
+/// Status and usage are separate endpoints that both keep counting while a page is open, so they
+/// are read as one pair: an index card must never report listings counted seconds apart from the
+/// accepted-request total printed above it, a combination the server never held. A pair whose
+/// usage half failed reports that failure instead of the counters, never counters from an earlier
+/// refresh.
+///
+/// # Errors
+///
+/// Returns a typed error when the status endpoint cannot provide a valid document. Nothing is
+/// published then, so the caller keeps the last pair it did publish.
+pub async fn load_overview() -> Result<UiOverview, super::LoaderError> {
+    let (snapshot, usage) = futures_util::future::join(load_snapshot(), super::load_stats(None, None)).await;
+    Ok((snapshot?, usage))
+}
+
+/// The admin snapshot and the usage counters measured beside it, paired as [`load_overview`] pairs
+/// them.
+///
+/// # Errors
+///
+/// Returns a typed error when the status endpoint cannot provide a valid document.
+pub async fn load_admin_overview() -> Result<UiOverview, super::LoaderError> {
+    let (snapshot, usage) = futures_util::future::join(load_admin_snapshot(), super::load_stats(None, None)).await;
+    Ok((snapshot?, usage))
+}
+
 /// The dashboard snapshot.
 ///
 /// # Errors
 ///
 /// Returns a typed error when the status endpoint cannot provide a valid document.
-pub async fn load_snapshot() -> Result<UiSnapshot, super::LoaderError> {
+async fn load_snapshot() -> Result<UiSnapshot, super::LoaderError> {
     #[cfg(feature = "ssr")]
     {
         Ok(crate::ssr::snapshot().await)
@@ -198,7 +233,7 @@ pub async fn load_snapshot() -> Result<UiSnapshot, super::LoaderError> {
 /// # Errors
 ///
 /// Returns a typed error when the status endpoint cannot provide a valid document.
-pub async fn load_admin_snapshot() -> Result<UiSnapshot, super::LoaderError> {
+async fn load_admin_snapshot() -> Result<UiSnapshot, super::LoaderError> {
     #[cfg(feature = "ssr")]
     {
         Ok(crate::ssr::admin_snapshot().await)

crates/peryx-web/src/pages/admin.rs

@@ -1,28 +1,33 @@
 use leptos::prelude::*;
 
-use super::{ErrorMessage, LoadState, ecosystem_stats, human_size, optional_counters_for, retain, start_refresh};
-use crate::data::{load_admin_snapshot, load_stats};
+use super::{
+    ErrorMessage, LoadState, ecosystem_stats, human_size, optional_counters_for, retain, start_refresh, usage_or_error,
+};
+use crate::data::load_admin_overview;
 use crate::model::{UiCounters, UiIndex, UiRecentWrite, UiSnapshot, UiStats, UiSummaryStatus};
 use crate::url::{browse_index_url, stats_index_url};
 
 #[component]
 pub fn AdminStatus() -> impl IntoView {
-    let snapshot = Resource::new(|| (), |()| load_admin_snapshot());
-    let stats = Resource::new(|| (), |()| load_stats(None, None));
-    let loaded_snapshot = RwSignal::new(LoadState::default());
-    let loaded_stats = RwSignal::new(LoadState::default());
-    start_refresh(snapshot);
-    start_refresh(stats);
+    let overview = Resource::new(|| (), |()| load_admin_overview());
+    let loaded = RwSignal::new(LoadState::default());
+    start_refresh(overview);
     view! {
         <section class="page ops-page">
             <Suspense fallback=|| view! { <p class="dim">"loading"</p> }>
                 {move || Suspend::new(async move {
-                    let snapshot = retain(loaded_snapshot, snapshot.await);
-                    let stats = retain(loaded_stats, stats.await);
+                    let loaded = retain(loaded, overview.await);
                     view! {
-                        {snapshot.error.map(|message| view! { <ErrorMessage message /> })}
-                        {stats.error.map(|message| view! { <ErrorMessage message /> })}
-                        {snapshot.value.map(|data| view! { <AdminStatusBody data usage=stats.value /> })}
+                        {loaded.error.map(|message| view! { <ErrorMessage message /> })}
+                        {loaded
+                            .value
+                            .map(|(data, usage)| {
+                                let (usage, error) = usage_or_error(usage);
+                                view! {
+                                    {error.map(|message| view! { <ErrorMessage message /> })}
+                                    <AdminStatusBody data usage />
+                                }
+                            })}
                     }
                 })}
             </Suspense>

crates/peryx-web/src/pages/dashboard.rs

@@ -1,30 +1,35 @@
 use leptos::prelude::*;
 
-use super::{ErrorMessage, LoadState, ecosystem_stats, human_size, optional_counters_for, retain, start_refresh};
-use crate::data::{load_snapshot, load_stats};
+use super::{
+    ErrorMessage, LoadState, ecosystem_stats, human_size, optional_counters_for, retain, start_refresh, usage_or_error,
+};
+use crate::data::{UiOverview, load_overview};
 use crate::model::{UiCounters, UiIndex, UiSnapshot, UiStats};
 use crate::url::{browse_index_url, stats_index_url};
 
 /// The landing dashboard: identity, live counters, and the configured indexes with their usage.
 #[component]
 pub fn Dashboard() -> impl IntoView {
-    let snapshot = Resource::new(|| (), |()| load_snapshot());
-    let stats = Resource::new(|| (), |()| load_stats(None, None));
-    let loaded_snapshot = RwSignal::new(LoadState::default());
-    let loaded_stats = RwSignal::new(LoadState::default());
-    start_refresh(snapshot);
-    start_refresh(stats);
+    let overview = Resource::new(|| (), |()| load_overview());
+    let loaded = RwSignal::new(LoadState::default());
+    start_refresh(overview);
     view! {
         <section class="page">
-            <StoopHero snapshot=loaded_snapshot />
+            <StoopHero overview=loaded />
             <Suspense fallback=|| view! { <StoopLoader /> }>
                 {move || Suspend::new(async move {
-                    let snapshot = retain(loaded_snapshot, snapshot.await);
-                    let stats = retain(loaded_stats, stats.await);
+                    let loaded = retain(loaded, overview.await);
                     view! {
-                        {snapshot.error.map(|message| view! { <ErrorMessage message /> })}
-                        {stats.error.map(|message| view! { <ErrorMessage message /> })}
-                        {snapshot.value.map(|data| view! { <DashboardBody data usage=stats.value /> })}
+                        {loaded.error.map(|message| view! { <ErrorMessage message /> })}
+                        {loaded
+                            .value
+                            .map(|(data, usage)| {
+                                let (usage, error) = usage_or_error(usage);
+                                view! {
+                                    {error.map(|message| view! { <ErrorMessage message /> })}
+                                    <DashboardBody data usage />
+                                }
+                            })}
                     }
                 })}
             </Suspense>
@@ -39,7 +44,7 @@ pub fn Dashboard() -> impl IntoView {
 /// refetch every few seconds would otherwise rebuild this `<svg>`, and a fresh node restarts the
 /// once-on-load dive, so the falcon would re-dive on every poll.
 #[component]
-fn StoopHero(snapshot: RwSignal<LoadState<UiSnapshot>>) -> impl IntoView {
+fn StoopHero(overview: RwSignal<LoadState<UiOverview>>) -> impl IntoView {
     view! {
         <div class="hero-brand">
             <span class="stoop-stage">
@@ -50,7 +55,7 @@ fn StoopHero(snapshot: RwSignal<LoadState<UiSnapshot>>) -> impl IntoView {
                 <span class="wordmark">"peryx"</span>
                 <span class="tagline">
                     "the artifact vault · v"
-                    {move || snapshot.get().value.map(|snapshot| snapshot.version)}
+                    {move || overview.get().value.map(|(snapshot, _)| snapshot.version)}
                 </span>
             </span>
         </div>

crates/peryx-web/src/pages/mod.rs

@@ -41,14 +41,32 @@ pub use topology::AvailabilityTopology;
 pub use trash::Trash;
 
 /// Refresh browser data every five seconds after hydration.
+///
+/// A tick that lands while the previous load is still outstanding is skipped: refetching then
+/// would stack a second request on a slow endpoint and let a later generation overtake an earlier
+/// one.
+///
+/// The interval outlives the page that started it, so a tick can arrive after the route has been
+/// left and the resource disposed. Reading a disposed resource panics, and there is nothing left
+/// to refresh, so a disposed resource skips the tick as well.
 #[cfg(all(not(feature = "ssr"), feature = "hydrate"))]
 fn start_refresh<T>(resource: Resource<Result<T, LoaderError>>)
 where
     T: serde::Serialize + serde::de::DeserializeOwned + Send + Sync + 'static,
 {
     use std::time::Duration;
+
+    use futures_util::FutureExt as _;
+
     Effect::new(move |_| {
-        set_interval(move || resource.refetch(), Duration::from_secs(5));
+        set_interval(
+            move || {
+                if !resource.is_disposed() && resource.ready().now_or_never().is_some() {
+                    resource.refetch();
+                }
+            },
+            Duration::from_secs(5),
+        );
     });
 }
 
@@ -88,6 +106,16 @@ fn retain<T: Clone + Send + Sync + 'static>(
     state.get_untracked()
 }
 
+/// The counters to render from the usage half of a published pair, and the message to report when
+/// that half did not answer. The counters are dropped rather than carried over, so a page never
+/// prints usage measured in a refresh other than the snapshot beside it.
+fn usage_or_error(usage: Result<UiStats, LoaderError>) -> (Option<UiStats>, Option<String>) {
+    match usage {
+        Ok(usage) => (Some(usage), None),
+        Err(error) => (None, Some(error.to_string())),
+    }
+}
+
 /// The per-ecosystem metric groups: one labelled block per ecosystem, so the reader can tell a
 /// ecosystem-scoped counter from the global request count.
 fn ecosystem_stats(data: &UiSnapshot) -> impl IntoView + use<> {

crates/peryx-web/tests/frontend/tests/ui.spec.mjs

@@ -1824,7 +1824,7 @@ test("dashboard preserves and recovers its last status snapshot", async ({
     });
   });
   await page.route("**/+stats**", (route) =>
-    route.fulfill({ json: statsRoutes(3) }),
+    route.fulfill({ json: statsRoutes(phase === "initial" ? 3 : 9) }),
   );
   await goto(page, "/login");
   await openClientPath(page, "/");
@@ -1842,6 +1842,127 @@ test("dashboard preserves and recovers its last status snapshot", async ({
   phase = "recovery";
   await advanceToRequest(page, "/+status");
   await expect(page.locator(".metrics-group").first()).toContainText("42");
+  await expect(page.locator(".card-usage")).toContainText("9 reads");
+  await expect(page.getByRole("alert")).toHaveCount(0);
+});
+
+test("dashboard reports a failed usage half without stale counters", async ({
+  page,
+}) => {
+  await page.clock.install();
+  let phase = "initial";
+  await page.route("**/+status", (route) =>
+    route.fulfill({ json: statusDocument(phase === "initial" ? 41 : 42) }),
+  );
+  await page.route("**/+stats**", (route) => {
+    if (phase === "failure") return route.fulfill({ status: 500 });
+    return route.fulfill({
+      json: statsRoutes(phase === "initial" ? 3 : 9),
+    });
+  });
+  await goto(page, "/login");
+  await openClientPath(page, "/");
+  await expect(page.locator(".tagline")).toContainText("vbrowser-41");
+  await expect(page.locator(".card-usage")).toContainText("3 reads");
+
+  phase = "failure";
+  await advanceToRequest(page, "/+stats");
+  await expect(page.getByRole("alert")).toHaveText(
+    "/+stats returned HTTP 500.",
+  );
+  await expect(page.locator(".tagline")).toContainText("vbrowser-42");
+  await expect(page.locator(".metrics-group").first()).toContainText("42");
+  await expect(page.locator(".card-usage")).toHaveCount(0);
+
+  phase = "recovery";
+  await advanceToRequest(page, "/+stats");
+  await expect(page.locator(".tagline")).toContainText("vbrowser-42");
+  await expect(page.locator(".metrics-group").first()).toContainText("42");
+  await expect(page.locator(".card-usage")).toContainText("9 reads");
+  await expect(page.getByRole("alert")).toHaveCount(0);
+});
+
+test("dashboard renders its first snapshot when usage is out of reach", async ({
+  page,
+}) => {
+  await page.route("**/+status", (route) =>
+    route.fulfill({ json: statusDocument(41) }),
+  );
+  await page.route("**/+stats**", (route) => route.fulfill({ status: 401 }));
+  await goto(page, "/login");
+  await openClientPath(page, "/");
+  await expect(page.locator(".card .card-title")).toHaveText("cache");
+  await expect(page.locator(".metrics-group").first()).toContainText("41");
+  await expect(page.getByRole("alert")).toHaveText(
+    "/+stats returned HTTP 401.",
+  );
+  await expect(page.locator(".card-usage")).toHaveCount(0);
+});
+
+test("dashboard skips a refresh while the previous one is outstanding", async ({
+  page,
+}) => {
+  await page.clock.install();
+  let statusRequests = 0;
+  let usage = null;
+  await page.route("**/+status", (route) => {
+    statusRequests += 1;
+    return route.fulfill({ json: statusDocument(40 + statusRequests) });
+  });
+  await page.route("**/+stats**", async (route) => {
+    if (usage) await usage.promise;
+    await route.fulfill({ json: statsRoutes(3) });
+  });
+  await goto(page, "/login");
+  await openClientPath(page, "/");
+  await expect(page.locator(".tagline")).toContainText("vbrowser-41");
+
+  usage = Promise.withResolvers();
+  await advanceToRequest(page, "/+status");
+  await page.clock.fastForward(5_000);
+  await page.clock.fastForward(5_000);
+  usage.resolve();
+  await expect(page.locator(".tagline")).toContainText("vbrowser-42");
+  expect(statusRequests).toBe(2);
+
+  await advanceToRequest(page, "/+status");
+  await expect(page.locator(".tagline")).toContainText("vbrowser-43");
+  expect(statusRequests).toBe(3);
+});
+
+test("admin status reports a failed usage half without stale counters", async ({
+  page,
+}) => {
+  await page.clock.install();
+  let phase = "initial";
+  await page.route("**/+status", (route) =>
+    route.fulfill({ json: statusDocument(phase === "initial" ? 41 : 42) }),
+  );
+  await page.route("**/+stats**", (route) => {
+    if (phase === "failure") return route.fulfill({ status: 500 });
+    return route.fulfill({
+      json: statsRoutes(phase === "initial" ? 3 : 9),
+    });
+  });
+  await goto(page, "/login");
+  await openClientPath(page, "/admin/status");
+  const usage = page.locator(".ops-table").filter({ hasText: "Refreshes" });
+  const reads = usage.locator("tbody td").nth(2);
+  await expect(page.locator(".metrics-group").first()).toContainText("41");
+  await expect(reads).toHaveText("3");
+
+  phase = "failure";
+  await advanceToRequest(page, "/+stats");
+  await expect(page.getByRole("alert")).toHaveText(
+    "/+stats returned HTTP 500.",
+  );
+  await expect(page.locator(".metrics-group").first()).toContainText("42");
+  await expect(usage).toHaveCount(0);
+
+  phase = "recovery";
+  await advanceToRequest(page, "/+stats");
+  await expect(page.locator(".metrics-group").first()).toContainText("42");
+  await expect(reads).toHaveText("9");
   await expect(page.getByRole("alert")).toHaveCount(0);
 });