Reachability Schema

The reachability system uses several data types for probe targets, results, and status summaries.

ProbeTarget

Defines a target to be probed for reachability.

interface ProbeTarget {
  id: string;           // Unique identifier
  name: string;         // Human-readable name
  type: "ip" | "hostname" | "url";
  target: string;       // IP, hostname, or URL to probe
  priority: "high" | "normal";
  asn?: string;         // Associated ASN
  regions?: string[];   // Specific regions to probe from
}

Priority Levels

Priority	Probe Interval	Use Case
high	1 minute	Critical infrastructure (DNS, CDN)
normal	10 minutes	Standard monitoring

Example

{
  "id": "cloudflare-dns",
  "name": "Cloudflare DNS",
  "type": "ip",
  "target": "1.1.1.1",
  "priority": "high",
  "asn": "AS13335"
}

---

ProbeResult

Individual probe measurement result.

interface ProbeResult {
  targetId: string;
  target: string;
  timestamp: string;    // ISO 8601
  region: string;       // Probe region (e.g., "SJC")
  probeType: "ping" | "http" | "traceroute";
  reachable: boolean;
  latencyMs?: number;
  statusCode?: number;  // For HTTP probes
  error?: string;
  hops?: TracerouteHop[];  // For traceroute probes
}

Probe Types

Type	Description	Latency Measurement
ping	ICMP-like connectivity check	Round-trip time
http	HTTP/HTTPS request	Time to first byte
traceroute	Path tracing	Per-hop latency

Example

{
  "targetId": "cloudflare-dns",
  "target": "1.1.1.1",
  "timestamp": "2025-01-15T12:00:00Z",
  "region": "SJC",
  "probeType": "http",
  "reachable": true,
  "latencyMs": 15,
  "statusCode": 200
}

---

ReachabilityStatus

Aggregated reachability status for a target.

interface ReachabilityStatus {
  targetId: string;
  target: string;
  name: string;
  lastUpdated: string;  // ISO 8601
  reachabilityPct: number;  // 0-100
  avgLatencyMs: number;
  minLatencyMs: number;
  maxLatencyMs: number;
  probeCount: number;
  successCount: number;
  regions: RegionStatus[];
  trend: "improving" | "stable" | "degrading" | "unknown";
}

interface RegionStatus {
  region: string;
  reachable: boolean;
  latencyMs: number;
  lastProbe: string;  // ISO 8601
  successRate: number;  // 0-100
}

Trend Values

Value	Condition
improving	Reachability ↑ or latency ↓ over time
stable	No significant changes
degrading	Reachability ↓ or latency ↑ over time
unknown	Insufficient historical data

Example

{
  "targetId": "cloudflare-dns",
  "target": "1.1.1.1",
  "name": "Cloudflare DNS",
  "lastUpdated": "2025-01-15T12:00:00Z",
  "reachabilityPct": 100,
  "avgLatencyMs": 15,
  "minLatencyMs": 12,
  "maxLatencyMs": 25,
  "probeCount": 60,
  "successCount": 60,
  "regions": [
    {
      "region": "SJC",
      "reachable": true,
      "latencyMs": 15,
      "lastProbe": "2025-01-15T12:00:00Z",
      "successRate": 100
    }
  ],
  "trend": "stable"
}

---

ReachabilitySummary

Overview of all monitored targets.

interface ReachabilitySummary {
  totalTargets: number;
  highPriorityTargets: number;
  normalPriorityTargets: number;
  healthyTargets: number;     // >= 95% reachable
  degradedTargets: number;    // 70-95% reachable
  unreachableTargets: number; // < 70% reachable
}

Health Thresholds

Status	Reachability
Healthy	≥ 95%
Degraded	70% - 95%
Unreachable	< 70%

Example

{
  "totalTargets": 6,
  "highPriorityTargets": 3,
  "normalPriorityTargets": 3,
  "healthyTargets": 6,
  "degradedTargets": 0,
  "unreachableTargets": 0
}