Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

10.0 KB
Raw Blame
import type { Resource, ResourceAvailabilityMeta } from '@/types/resource';
import { formatRelativeTime } from '@/utils/format';

export interface AvailabilityProbePresentation {
  methodLabel: string;
  targetLabel: string | null;
  resultLabel: string;
  freshnessLabel: 'fresh' | 'stale' | 'freshness unknown';
  correlationLabel: string | null;
  netIoLabel: string;
  rowLabel: string;
  detailLabel: string;
  toneClassName: string;
}

type AvailabilityProbeResource = Pick<
  Resource,
  'type' | 'platformType' | 'status' | 'availability' | 'platformData'
>;

const AVAILABILITY_PROBE_SUCCESS_CLASS = 'text-emerald-600 dark:text-emerald-300';
const AVAILABILITY_PROBE_WARNING_CLASS = 'text-amber-600 dark:text-amber-300';
const AVAILABILITY_PROBE_ERROR_CLASS = 'text-red-600 dark:text-red-300';
const AVAILABILITY_PROBE_UNKNOWN_CLASS = 'text-muted';

const normalizeAvailabilityProtocol = (protocol?: string | null): string =>
  (protocol ?? '').trim().toLowerCase();

export const getAvailabilityProbeMethodLabel = (
  availability?: ResourceAvailabilityMeta | null,
): string => {
  const protocol = normalizeAvailabilityProtocol(availability?.protocol);
  if (protocol === 'icmp') return 'ICMP';
  if (protocol === 'tcp' || protocol === 'udp') {
    const label = protocol.toUpperCase();
    return availability?.port ? `${label} ${availability.port}` : label;
  }
  if (protocol === 'http' || protocol === 'https') {
    const path = (availability?.path ?? '').trim();
    return path ? `${protocol.toUpperCase()} ${path}` : protocol.toUpperCase();
  }
  return protocol ? protocol.toUpperCase() : 'Probe';
};

export const getAvailabilityProbeTargetLabel = (
  availability?: ResourceAvailabilityMeta | null,
): string | null => {
  const protocol = normalizeAvailabilityProtocol(availability?.protocol);
  if (protocol === 'tcp' || protocol === 'udp') {
    const port = availability?.port;
    return typeof port === 'number' && Number.isFinite(port) && port > 0 ? String(port) : null;
  }
  if (protocol === 'http' || protocol === 'https') {
    const path = (availability?.path ?? '').trim();
    return path || null;
  }
  return null;
};

export const getAvailabilityProbeEndpointLabel = (
  availability?: ResourceAvailabilityMeta | null,
): string => {
  const address = (availability?.address ?? '').trim();
  const protocol = normalizeAvailabilityProtocol(availability?.protocol);
  const port = availability?.port;
  const addressWithPort =
    address &&
    typeof port === 'number' &&
    Number.isFinite(port) &&
    port > 0 &&
    !address.endsWith(`:${port}`)
      ? `${address}:${port}`
      : address;
  if ((protocol === 'http' || protocol === 'https') && availability?.path) {
    const path = availability.path.trim();
    if (path && !addressWithPort.endsWith(path)) {
      return `${addressWithPort.replace(/\/+$/, '')}${path.startsWith('/') ? path : `/${path}`}`;
    }
  }
  return addressWithPort;
};

/**
 * True when an availability probe that resolved to this resource has failed
 * past its configured threshold.
 *
 * Only `attached` facets count: a standalone, ambiguous, or unresolved probe
 * has not been proven to describe this resource. The threshold mirrors the gate
 * the availability poller uses before raising `availability_unreachable`, so
 * every surface built on this agrees with the alert rather than running ahead
 * of it.
 *
 * This reads the facet already projected onto the resource. The check resource
 * remains the sole owner of the incident, its alert and its history, per the
 * availability check identity record of 2026-07-23.
 */
export const hasFailedAttachedAvailabilityCheck = (source: {
  availability?: ResourceAvailabilityMeta | null;
  availabilityChecks?: ResourceAvailabilityMeta[] | null;
}): boolean => {
  const checks = source.availabilityChecks?.length
    ? source.availabilityChecks
    : source.availability
      ? [source.availability]
      : [];

  return checks.some((check) => {
    if (!check || check.enabled === false) return false;
    if (check.available !== false) return false;
    if (check.correlationState !== 'attached') return false;
    const failures = check.consecutiveFailures ?? 0;
    const threshold = Math.max(check.failureThreshold ?? 1, 1);
    return failures >= threshold;
  });
};

const getAvailabilityProbeFailureLabel = (availability: ResourceAvailabilityMeta): string => {
  const lastError = (availability.lastError ?? '').trim();
  const normalizedError = lastError.toLowerCase();
  if (normalizedError.includes('timed out') || normalizedError.includes('timeout')) {
    return 'timed out';
  }
  const httpStatus = lastError.match(/\b([45]\d{2})\b/);
  if (httpStatus) {
    return httpStatus[1];
  }
  return 'failed';
};

const getAvailabilityProbeResultLabel = (
  resource: Pick<Resource, 'status'>,
  availability: ResourceAvailabilityMeta,
): string => {
  const latency = availability.latencyMillis;
  const normalizedStatus = (resource.status ?? '').trim().toLowerCase();
  if (availability.probeOutcome === 'indeterminate') return 'open or filtered';
  if (availability.available === false || ['offline', 'degraded'].includes(normalizedStatus)) {
    return getAvailabilityProbeFailureLabel(availability);
  }
  if (typeof latency === 'number' && Number.isFinite(latency) && latency >= 0) {
    return `${Math.round(latency)} ms`;
  }
  if (availability.available === true || normalizedStatus === 'online') {
    return 'reachable';
  }
  return 'not checked';
};

const getAvailabilityProbeToneClassName = (
  resource: Pick<Resource, 'status'>,
  availability: ResourceAvailabilityMeta,
  freshnessLabel: AvailabilityProbePresentation['freshnessLabel'],
): string => {
  const normalizedStatus = (resource.status ?? '').trim().toLowerCase();
  if (availability.probeOutcome === 'indeterminate') {
    return AVAILABILITY_PROBE_WARNING_CLASS;
  }
  if (availability.available === false || normalizedStatus === 'offline') {
    return AVAILABILITY_PROBE_ERROR_CLASS;
  }
  if (
    normalizedStatus === 'degraded' ||
    freshnessLabel === 'stale' ||
    availability.correlationState === 'ambiguous' ||
    availability.correlationState === 'unresolved'
  ) {
    return AVAILABILITY_PROBE_WARNING_CLASS;
  }
  if (availability.available === true || normalizedStatus === 'online') {
    return AVAILABILITY_PROBE_SUCCESS_CLASS;
  }
  return AVAILABILITY_PROBE_UNKNOWN_CLASS;
};

const getAvailabilityFreshnessLabel = (
  availability: ResourceAvailabilityMeta,
  now: Date,
): AvailabilityProbePresentation['freshnessLabel'] => {
  const explicitValidUntil = availability.evidence?.validUntil;
  const validUntilMillis = explicitValidUntil ? Date.parse(explicitValidUntil) : Number.NaN;
  if (Number.isFinite(validUntilMillis)) {
    return validUntilMillis >= now.getTime() ? 'fresh' : 'stale';
  }

  const checkedMillis = availability.lastChecked
    ? Date.parse(availability.lastChecked)
    : Number.NaN;
  const pollIntervalSeconds = availability.pollIntervalSeconds;
  if (
    Number.isFinite(checkedMillis) &&
    typeof pollIntervalSeconds === 'number' &&
    Number.isFinite(pollIntervalSeconds) &&
    pollIntervalSeconds > 0
  ) {
    return checkedMillis + pollIntervalSeconds * 2_000 >= now.getTime() ? 'fresh' : 'stale';
  }
  return 'freshness unknown';
};

const getAvailabilityCorrelationLabel = (availability: ResourceAvailabilityMeta): string | null => {
  switch (availability.correlationState) {
    case 'ambiguous':
      return availability.correlationCandidates && availability.correlationCandidates > 1
        ? `${availability.correlationCandidates} possible resource matches`
        : 'Resource match is ambiguous';
    case 'unresolved':
      return 'Resource link is unresolved';
    case 'standalone':
      return 'Standalone endpoint';
    default:
      return null;
  }
};

const getFailureCountLabel = (availability: ResourceAvailabilityMeta): string | null => {
  const failures = availability.consecutiveFailures;
  if (typeof failures !== 'number' || !Number.isFinite(failures) || failures <= 0) {
    return null;
  }
  const threshold = availability.failureThreshold;
  if (typeof threshold === 'number' && Number.isFinite(threshold) && threshold > 0) {
    return `${failures}/${threshold} failures`;
  }
  return failures === 1 ? '1 failure' : `${failures} failures`;
};

export const getAvailabilityProbePresentation = (
  resource: AvailabilityProbeResource,
  now = new Date(Date.now()),
): AvailabilityProbePresentation | null => {
  const platformAvailability = resource.platformData?.availability as
    ResourceAvailabilityMeta | undefined;
  const availability = resource.availability ?? platformAvailability;
  if (!availability) {
    return null;
  }

  const methodLabel = getAvailabilityProbeMethodLabel(availability);
  const targetLabel = getAvailabilityProbeTargetLabel(availability);
  const resultLabel = getAvailabilityProbeResultLabel(resource, availability);
  const freshnessLabel = getAvailabilityFreshnessLabel(availability, now);
  const correlationLabel = getAvailabilityCorrelationLabel(availability);
  const netIoLabel = targetLabel ? `${targetLabel}: ${resultLabel}` : resultLabel;
  const checked = formatRelativeTime(availability.lastChecked, { now: now.getTime() });
  const failures = getFailureCountLabel(availability);
  const detailParts = [`${methodLabel} - ${resultLabel}`, freshnessLabel];
  if (checked) detailParts.push(`checked ${checked}`);
  if (correlationLabel) detailParts.push(correlationLabel);
  if (failures) detailParts.push(failures);
  if (availability.lastSuccess && availability.available === false) {
    const lastSuccess = formatRelativeTime(availability.lastSuccess, { now: now.getTime() });
    if (lastSuccess) detailParts.push(`last success ${lastSuccess}`);
  }
  if (availability.lastError) detailParts.push(availability.lastError);

  const rowLabel = checked ? `${netIoLabel} - checked ${checked}` : netIoLabel;

  return {
    methodLabel,
    targetLabel,
    resultLabel,
    freshnessLabel,
    correlationLabel,
    netIoLabel,
    rowLabel,
    detailLabel: detailParts.join(' - '),
    toneClassName: getAvailabilityProbeToneClassName(resource, availability, freshnessLabel),
  };
};