@ebowwa/terminal 0.2.0

package/src/network-error-detector.ts

@@ -0,0 +1,121 @@
+/**
+ * Network Error Detection
+ * Detects and provides helpful messages for common network issues
+ */
+
+export interface NetworkErrorDetails {
+  type: "SERVER_NOT_READY" | "NETWORK_BLOCKED" | "AUTH_FAILED" | "UNKNOWN";
+  message: string;
+  troubleshooting: string[];
+  isLikelyNetworkBlock: boolean;
+}
+
+/**
+ * Analyzes SSH connection error and provides detailed diagnosis
+ */
+export function detectNetworkError(
+  error: Error | string,
+  host: string,
+  serverStatus?: string
+): NetworkErrorDetails {
+  const errorMessage = typeof error === "string" ? error : error.message;
+
+  // Pattern 1: Network blocking (ECONNREFUSED on specific IPs)
+  const isConnectionRefused =
+    errorMessage.includes("ECONNREFUSED") ||
+    errorMessage.includes("Connection refused") ||
+    errorMessage.includes("connect ECONNREFUSED");
+
+  const isHetznerOrDatacenterIP =
+    host.startsWith("195.") ||
+    host.startsWith("148.") ||
+    host.startsWith("116.") ||
+    host.startsWith("138.") ||
+    host.includes("hetzner") ||
+    host.includes("fsn1") ||
+    host.includes("nbg1") ||
+    host.includes("hel1");
+
+  const serverIsRunning = serverStatus === "running";
+
+  // Network blocking pattern:
+  // - ECONNREFUSED (not timeout)
+  // - Server is running (per API)
+  // - Hetzner/datacenter IP
+  if (isConnectionRefused && serverIsRunning && isHetznerOrDatacenterIP) {
+    return {
+      type: "NETWORK_BLOCKED",
+      message: "Network appears to be blocking this server",
+      troubleshooting: [
+        "✓ Server is running and responding to API",
+        "✗ Your network is refusing connections to this IP",
+        "",
+        "⚠️  COMMON CAUSES:",
+        "• Corporate/public WiFi blocks datacenter IPs",
+        "• ISP firewall filtering VPS providers",
+        "• Router content filtering",
+        "",
+        "🔧 SOLUTIONS:",
+        "1. Try a different network (hotspot, home WiFi, VPN)",
+        "2. Check router firewall settings",
+        "3. Contact ISP about blocking Hetzner IPs",
+        "",
+        "💡 TEST: Works from other networks? = Network block confirmed",
+      ],
+      isLikelyNetworkBlock: true,
+    };
+  }
+
+  // Pattern 2: Server still booting
+  if (isConnectionRefused && !serverIsRunning) {
+    return {
+      type: "SERVER_NOT_READY",
+      message: "Server is not ready yet",
+      troubleshooting: [
+        "Server is still starting up",
+        "SSH daemon hasn't started yet",
+        "",
+        "⏳ Wait 1-2 minutes and try again",
+      ],
+      isLikelyNetworkBlock: false,
+    };
+  }
+
+  // Pattern 3: Authentication failure
+  if (
+    errorMessage.includes("All configured authentication") ||
+    errorMessage.includes("Authentication failed")
+  ) {
+    return {
+      type: "AUTH_FAILED",
+      message: "SSH authentication failed",
+      troubleshooting: [
+        "SSH key issue or wrong credentials",
+        "Check that the SSH key is configured correctly",
+      ],
+      isLikelyNetworkBlock: false,
+    };
+  }
+
+  // Default: Unknown error
+  return {
+    type: "UNKNOWN",
+    message: errorMessage,
+    troubleshooting: [
+      "Check if server is running",
+      "Verify network connectivity",
+      "Check SSH key configuration",
+    ],
+    isLikelyNetworkBlock: false,
+  };
+}
+
+/**
+ * Format network error for WebSocket/UI display
+ */
+export function formatNetworkError(diagnosis: NetworkErrorDetails): string {
+  if (diagnosis.isLikelyNetworkBlock) {
+    return `⚠️  ${diagnosis.message}\n\n${diagnosis.troubleshooting.join("\n")}`;
+  }
+  return diagnosis.message;
+}