Skip to content

A modern and elegant dashboard for network traffic visualization and analysis.

6.4 KB
Raw Blame
"use client";

import { useEffect, useRef, useState } from "react";

// Live transfer rate derived from successive cumulative totals (issue #93).
// Summary pushes arrive every few seconds, so the rate is averaged over a
// short sliding window instead of a single noisy delta.

export interface TotalsSample {
  at: number;
  download: number;
  upload: number;
}

export interface TransferRate {
  download: number;
  upload: number;
}

export const RATE_WINDOW_MS = 15_000;
// Pushes arrive every ~3s with some jitter; a longer span keeps it small.
const MIN_SPAN_MS = 5_000;
const MAX_SAMPLE_AGE_MS = 30_000;

/**
 * Append a sample. Within one window cumulative totals never go down, so a
 * lower value is a stale or inconsistent reading (e.g. an old push shown
 * again after a reconnect) and is ignored rather than used as a new
 * baseline. The window restarts when the previous sample is stale.
 */
export function pushSample(samples: TotalsSample[], next: TotalsSample): TotalsSample[] {
  const last = samples[samples.length - 1];
  if (last && next.at - last.at <= MAX_SAMPLE_AGE_MS && next.at >= last.at &&
      (next.download < last.download || next.upload < last.upload)) {
    return samples;
  }
  if (last && (next.at - last.at > MAX_SAMPLE_AGE_MS || next.at < last.at)) {
    return [next];
  }
  if (last && next.download === last.download && next.upload === last.upload && next.at === last.at) {
    return samples;
  }
  const kept = samples.filter((sample) => next.at - sample.at <= RATE_WINDOW_MS);
  return [...kept, next];
}

/** Bytes per second over the window, or null when there is not enough data. */
export function computeRate(samples: TotalsSample[], now: number): TransferRate | null {
  if (samples.length < 2) return null;
  const first = samples[0];
  const last = samples[samples.length - 1];
  if (now - last.at > MAX_SAMPLE_AGE_MS) return null;
  const spanMs = last.at - first.at;
  if (spanMs < MIN_SPAN_MS) return null;
  return {
    download: Math.max(0, ((last.download - first.download) * 1000) / spanMs),
    upload: Math.max(0, ((last.upload - first.upload) * 1000) / spanMs),
  };
}

export interface RateTrackerState {
  samples: TotalsSample[];
  windowKey: string;
  sourceKey: string;
  enabled: boolean;
  /** Last totals held back after a switch; ignored until they change. */
  pending: Pick<TotalsSample, "download" | "upload"> | null;
  /** How many more distinct totals to hold back before sampling. */
  holds: number;
}

export interface RateTrackerInput {
  at: number;
  download: number | undefined;
  upload: number | undefined;
  windowKey: string;
  sourceKey: string;
  enabled: boolean;
}

export const initialRateTrackerState: RateTrackerState = {
  samples: [],
  windowKey: "",
  sourceKey: "",
  enabled: false,
  pending: null,
  holds: 0,
};

/**
 * Advance the tracker with the latest totals.
 *
 * After a switch (or the first mount) two kinds of totals are unusable as a
 * baseline and are held back:
 * - totals carried over from the old window or backend, which queries keep
 *   showing while the new one loads;
 * - the first fresh totals, held back too as a precaution: right after a
 *   switch, HTTP fetches and WS pushes for the new window can still race.
 * Either would turn the next jump into a huge spurious rate.
 *
 * `clear` tells the caller to drop the displayed reading (backend switched or
 * tracking disabled); `rate` is a fresh reading when one is available.
 */
export function stepRateTracker(
  state: RateTrackerState,
  input: RateTrackerInput,
): { state: RateTrackerState; rate: TransferRate | null; clear: boolean } {
  const { at, download, upload, windowKey, sourceKey, enabled } = input;
  const sourceChanged = state.sourceKey !== sourceKey;
  const switched =
    sourceChanged || state.windowKey !== windowKey || (enabled && !state.enabled);
  const clear = sourceChanged || !enabled;
  const hasTotals = download !== undefined && upload !== undefined;

  let samples = state.samples;
  let pending = state.pending;
  let holds = state.holds;
  if (switched || !enabled) {
    samples = [];
    pending = hasTotals ? { download, upload } : null;
    // Besides the carried-over totals (pending), skip the first fresh value.
    holds = 1;
  }

  const base = { windowKey, sourceKey, enabled };
  if (!enabled || !hasTotals) {
    return { state: { ...base, samples, pending, holds }, rate: null, clear };
  }
  if (pending && pending.download === download && pending.upload === upload) {
    return { state: { ...base, samples, pending, holds }, rate: null, clear };
  }
  if (holds > 0) {
    return {
      state: { ...base, samples, pending: { download, upload }, holds: holds - 1 },
      rate: null,
      clear,
    };
  }
  samples = pushSample(samples, { at, download, upload });
  return {
    state: { ...base, samples, pending: null, holds: 0 },
    rate: computeRate(samples, at),
    clear,
  };
}

/**
 * Track the live rate of cumulative totals.
 * - `windowKey` changes when the queried window moves (rolling presets shift
 *   every minute): samples restart, but the last reading stays on screen
 *   until a new one is available or it goes stale.
 * - `sourceKey` changes when the totals belong to something else (backend
 *   switched): samples and the displayed reading are both cleared.
 */
export function useTransferRate(
  download: number | undefined,
  upload: number | undefined,
  { windowKey, sourceKey, enabled }: { windowKey: string; sourceKey: string; enabled: boolean },
): TransferRate | null {
  const trackerRef = useRef<RateTrackerState>(initialRateTrackerState);
  const lastReadingAtRef = useRef(0);
  const [rate, setRate] = useState<TransferRate | null>(null);

  useEffect(() => {
    const now = Date.now();
    const step = stepRateTracker(trackerRef.current, {
      at: now,
      download,
      upload,
      windowKey,
      sourceKey,
      enabled,
    });
    trackerRef.current = step.state;
    if (step.clear) setRate(null);
    if (step.rate) {
      lastReadingAtRef.current = now;
      setRate(step.rate);
    }
  }, [download, upload, windowKey, sourceKey, enabled]);

  // Expire the reading when pushes stop arriving.
  useEffect(() => {
    if (!enabled) return;
    const timer = setInterval(() => {
      if (Date.now() - lastReadingAtRef.current > MAX_SAMPLE_AGE_MS) {
        setRate((current) => (current ? null : current));
      }
    }, 5_000);
    return () => clearInterval(timer);
  }, [enabled]);

  return rate;
}