Admin/XMover: Refactor -- util

amotl · amotl · commit 04abce63af45 · 2025-08-20T20:54:20.000+02:00
diff --git a/cratedb_toolkit/admin/xmover/analyze/report.py b/cratedb_toolkit/admin/xmover/analyze/report.py
@@ -7,7 +7,7 @@
 
 from cratedb_toolkit.admin.xmover.analyze.shard import ShardAnalyzer
 from cratedb_toolkit.admin.xmover.model import ShardMoveRecommendation, ShardMoveRequest, SizeCriteria
-from cratedb_toolkit.admin.xmover.util import format_percentage, format_size
+from cratedb_toolkit.admin.xmover.util.format import format_percentage, format_size
 
 console = Console()
 
diff --git a/cratedb_toolkit/admin/xmover/analyze/shard.py b/cratedb_toolkit/admin/xmover/analyze/shard.py
@@ -7,14 +7,14 @@
 from collections import defaultdict
 from typing import Any, Dict, List, Optional, Set, Tuple, Union
 
-from cratedb_toolkit.admin.xmover.database import CrateDBClient
 from cratedb_toolkit.admin.xmover.model import (
     DistributionStats,
     NodeInfo,
     RecommendationConstraints,
     ShardInfo,
     ShardMoveRecommendation,
 )
+from cratedb_toolkit.admin.xmover.util.database import CrateDBClient
 
 logger = logging.getLogger(__name__)
 
diff --git a/cratedb_toolkit/admin/xmover/analyze/zone.py b/cratedb_toolkit/admin/xmover/analyze/zone.py
@@ -6,8 +6,8 @@
 from rich.table import Table
 
 from cratedb_toolkit.admin.xmover.analyze.shard import ShardAnalyzer
-from cratedb_toolkit.admin.xmover.database import CrateDBClient
 from cratedb_toolkit.admin.xmover.model import ShardInfo
+from cratedb_toolkit.admin.xmover.util.database import CrateDBClient
 
 console = Console()
 
diff --git a/cratedb_toolkit/admin/xmover/cli.py b/cratedb_toolkit/admin/xmover/cli.py
@@ -5,11 +5,10 @@
 """
 
 import sys
-from typing import List, Optional, cast
+from typing import Optional
 
 import click
 from rich.console import Console
-from rich.panel import Panel
 
 from cratedb_toolkit.admin.xmover.analyze.report import ShardReporter
 from cratedb_toolkit.admin.xmover.analyze.shard import ShardAnalyzer
@@ -21,8 +20,8 @@
 )
 from cratedb_toolkit.admin.xmover.tune.recommend import Recommender
 from cratedb_toolkit.admin.xmover.tune.recover import RecoveryMonitor, RecoveryOptions
-
-from .database import CrateDBClient
+from cratedb_toolkit.admin.xmover.util.database import CrateDBClient
+from cratedb_toolkit.admin.xmover.util.error import explain_cratedb_error
 
 console = Console()
 
@@ -236,130 +235,7 @@ def explain_error(ctx, error_message: Optional[str]):
 
     Example: xmover explain-error "NO(a copy of this shard is already allocated to this node)"
     """
-    console.print(Panel.fit("[bold blue]CrateDB Error Message Decoder[/bold blue]"))
-    console.print("[dim]Helps decode and troubleshoot CrateDB shard allocation errors[/dim]")
-    console.print()
-
-    if not error_message:
-        console.print("Please paste the CrateDB error message (press Enter twice when done):")
-        lines: List[str] = []
-        while True:
-            try:
-                line = input()
-                if line.strip() == "" and lines:
-                    break
-                lines.append(line)
-            except (EOFError, KeyboardInterrupt):
-                break
-        error_message = "\n".join(lines)
-
-    if not error_message.strip():
-        console.print("[yellow]No error message provided[/yellow]")
-        return
-
-    console.print("[dim]Analyzing error message...[/dim]")
-    console.print()
-
-    # Common CrateDB allocation error patterns and solutions
-    error_patterns = [
-        {
-            "pattern": "a copy of this shard is already allocated to this node",
-            "title": "Node Already Has Shard Copy",
-            "explanation": "The target node already contains a copy (primary or replica) of this shard.",
-            "solutions": [
-                "Choose a different target node that doesn't have this shard",
-                "Use 'xmover zone-analysis --show-shards' to see current distribution",
-                "Verify the shard ID and table name are correct",
-            ],
-            "prevention": "Always check current shard locations before moving",
-        },
-        {
-            "pattern": "there are too many copies of the shard allocated to nodes with attribute",
-            "title": "Zone Allocation Limit Exceeded",
-            "explanation": "CrateDB's zone awareness prevents too many copies in the same zone.",
-            "solutions": [
-                "Move the shard to a different availability zone",
-                "Check zone balance with 'xmover check-balance'",
-                "Ensure target zone doesn't already have copies of this shard",
-            ],
-            "prevention": "Use 'xmover recommend' which respects zone constraints",
-        },
-        {
-            "pattern": "not enough disk space",
-            "title": "Insufficient Disk Space",
-            "explanation": "The target node doesn't have enough free disk space for the shard.",
-            "solutions": [
-                "Free up space on the target node",
-                "Choose a node with more available capacity",
-                "Check available space with 'xmover analyze'",
-            ],
-            "prevention": "Use '--min-free-space' parameter in recommendations",
-        },
-        {
-            "pattern": "shard recovery limit",
-            "title": "Recovery Limit Exceeded",
-            "explanation": "Too many shards are currently being moved/recovered simultaneously.",
-            "solutions": [
-                "Wait for current recoveries to complete",
-                "Check recovery status in CrateDB admin UI",
-                "Reduce concurrent recoveries in cluster settings",
-            ],
-            "prevention": "Move shards gradually, monitor recovery progress",
-        },
-        {
-            "pattern": "allocation is disabled",
-            "title": "Allocation Disabled",
-            "explanation": "Shard allocation is temporarily disabled in the cluster.",
-            "solutions": [
-                "Re-enable allocation: PUT /_cluster/settings "
-                '{"persistent":{"cluster.routing.allocation.enable":"all"}}',
-                "Check if allocation was disabled for maintenance",
-                "Verify cluster health before re-enabling",
-            ],
-            "prevention": "Check allocation status before performing moves",
-        },
-    ]
-
-    # Find matching patterns
-    matches = []
-    error_lower = error_message.lower()
-
-    for pattern_info in error_patterns:
-        if cast(str, pattern_info["pattern"]).lower() in error_lower:
-            matches.append(pattern_info)
-
-    if matches:
-        for i, match in enumerate(matches):
-            if i > 0:
-                console.print("\n" + "─" * 60 + "\n")
-
-            console.print(f"[bold red]🚨 {match['title']}[/bold red]")
-            console.print(f"[yellow]📝 Explanation:[/yellow] {match['explanation']}")
-            console.print()
-
-            console.print("[green]💡 Solutions:[/green]")
-            for j, solution in enumerate(match["solutions"], 1):
-                console.print(f"  {j}. {solution}")
-            console.print()
-
-            console.print(f"[blue]🛡️ Prevention:[/blue] {match['prevention']}")
-    else:
-        console.print("[yellow]⚠ No specific pattern match found[/yellow]")
-        console.print()
-        console.print("[bold]General Troubleshooting Steps:[/bold]")
-        console.print("1. Check current shard distribution: [cyan]xmover analyze[/cyan]")
-        console.print(
-            "2. Validate the specific move: [cyan]xmover validate-move schema.table shard_id from_node to_node[/cyan]"
-        )
-        console.print("3. Check zone conflicts: [cyan]xmover zone-analysis --show-shards[/cyan]")
-        console.print("4. Verify node capacity: [cyan]xmover analyze[/cyan]")
-        console.print("5. Review CrateDB documentation on shard allocation")
-
-    console.print()
-    console.print("[dim]💡 Tip: Use 'xmover validate-move' to check moves before execution[/dim]")
-    console.print(
-        "[dim]📚 For more help: https://crate.io/docs/crate/reference/en/latest/admin/system-information.html[/dim]"
-    )
+    explain_cratedb_error(error_message)
 
 
 @main.command()
diff --git a/cratedb_toolkit/admin/xmover/tune/recommend.py b/cratedb_toolkit/admin/xmover/tune/recommend.py
@@ -6,10 +6,10 @@
 from rich.table import Table
 
 from cratedb_toolkit.admin.xmover.analyze.shard import ShardAnalyzer
-from cratedb_toolkit.admin.xmover.database import CrateDBClient
 from cratedb_toolkit.admin.xmover.model import RecommendationConstraints
 from cratedb_toolkit.admin.xmover.tune.recover import RecoveryMonitor, RecoveryOptions
-from cratedb_toolkit.admin.xmover.util import format_size
+from cratedb_toolkit.admin.xmover.util.database import CrateDBClient
+from cratedb_toolkit.admin.xmover.util.format import format_size
 
 console = Console()
 
diff --git a/cratedb_toolkit/admin/xmover/tune/recover.py b/cratedb_toolkit/admin/xmover/tune/recover.py
@@ -5,9 +5,9 @@
 
 from rich.console import Console
 
-from cratedb_toolkit.admin.xmover.database import CrateDBClient
 from cratedb_toolkit.admin.xmover.model import RecoveryInfo
-from cratedb_toolkit.admin.xmover.util import format_translog_info
+from cratedb_toolkit.admin.xmover.util.database import CrateDBClient
+from cratedb_toolkit.admin.xmover.util.format import format_translog_info
 
 console = Console()
 
diff --git a/cratedb_toolkit/admin/xmover/util/__init__.py b/cratedb_toolkit/admin/xmover/util/__init__.py
diff --git a/cratedb_toolkit/admin/xmover/util/database.py b/cratedb_toolkit/admin/xmover/util/database.py
diff --git a/cratedb_toolkit/admin/xmover/util/error.py b/cratedb_toolkit/admin/xmover/util/error.py
@@ -0,0 +1,133 @@
+from typing import List, Optional, cast
+
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+
+def explain_cratedb_error(error_message: Optional[str]):
+    console.print(Panel.fit("[bold blue]CrateDB Error Message Decoder[/bold blue]"))
+    console.print("[dim]Helps decode and troubleshoot CrateDB shard allocation errors[/dim]")
+    console.print()
+
+    if not error_message:
+        console.print("Please paste the CrateDB error message (press Enter twice when done):")
+        lines: List[str] = []
+        while True:
+            try:
+                line = input()
+                if line.strip() == "" and lines:
+                    break
+                lines.append(line)
+            except (EOFError, KeyboardInterrupt):
+                break
+        error_message = "\n".join(lines)
+
+    if not error_message.strip():
+        console.print("[yellow]No error message provided[/yellow]")
+        return
+
+    console.print("[dim]Analyzing error message...[/dim]")
+    console.print()
+
+    # Common CrateDB allocation error patterns and solutions
+    error_patterns = [
+        {
+            "pattern": "a copy of this shard is already allocated to this node",
+            "title": "Node Already Has Shard Copy",
+            "explanation": "The target node already contains a copy (primary or replica) of this shard.",
+            "solutions": [
+                "Choose a different target node that doesn't have this shard",
+                "Use 'xmover zone-analysis --show-shards' to see current distribution",
+                "Verify the shard ID and table name are correct",
+            ],
+            "prevention": "Always check current shard locations before moving",
+        },
+        {
+            "pattern": "there are too many copies of the shard allocated to nodes with attribute",
+            "title": "Zone Allocation Limit Exceeded",
+            "explanation": "CrateDB's zone awareness prevents too many copies in the same zone.",
+            "solutions": [
+                "Move the shard to a different availability zone",
+                "Check zone balance with 'xmover check-balance'",
+                "Ensure target zone doesn't already have copies of this shard",
+            ],
+            "prevention": "Use 'xmover recommend' which respects zone constraints",
+        },
+        {
+            "pattern": "not enough disk space",
+            "title": "Insufficient Disk Space",
+            "explanation": "The target node doesn't have enough free disk space for the shard.",
+            "solutions": [
+                "Free up space on the target node",
+                "Choose a node with more available capacity",
+                "Check available space with 'xmover analyze'",
+            ],
+            "prevention": "Use '--min-free-space' parameter in recommendations",
+        },
+        {
+            "pattern": "shard recovery limit",
+            "title": "Recovery Limit Exceeded",
+            "explanation": "Too many shards are currently being moved/recovered simultaneously.",
+            "solutions": [
+                "Wait for current recoveries to complete",
+                "Check recovery status in CrateDB admin UI",
+                "Reduce concurrent recoveries in cluster settings",
+            ],
+            "prevention": "Move shards gradually, monitor recovery progress",
+        },
+        {
+            "pattern": "allocation is disabled",
+            "title": "Allocation Disabled",
+            "explanation": "Shard allocation is temporarily disabled in the cluster.",
+            "solutions": [
+                "Re-enable allocation: PUT /_cluster/settings "
+                '{"persistent":{"cluster.routing.allocation.enable":"all"}}',
+                "Check if allocation was disabled for maintenance",
+                "Verify cluster health before re-enabling",
+            ],
+            "prevention": "Check allocation status before performing moves",
+        },
+    ]
+
+    # Find matching patterns
+    matches = []
+    error_lower = error_message.lower()
+
+    for pattern_info in error_patterns:
+        if cast(str, pattern_info["pattern"]).lower() in error_lower:
+            matches.append(pattern_info)
+
+    if matches:
+        for i, match in enumerate(matches):
+            if i > 0:
+                console.print("\n" + "─" * 60 + "\n")
+
+            console.print(f"[bold red]🚨 {match['title']}[/bold red]")
+            console.print(f"[yellow]📝 Explanation:[/yellow] {match['explanation']}")
+            console.print()
+
+            console.print("[green]💡 Solutions:[/green]")
+            for j, solution in enumerate(match["solutions"], 1):
+                console.print(f"  {j}. {solution}")
+            console.print()
+
+            console.print(f"[blue]🛡️ Prevention:[/blue] {match['prevention']}")
+    else:
+        console.print("[yellow]⚠ No specific pattern match found[/yellow]")
+        console.print()
+        console.print("[bold]General Troubleshooting Steps:[/bold]")
+        console.print("1. Check current shard distribution: [cyan]xmover analyze[/cyan]")
+        console.print(
+            "2. Validate the specific move: [cyan]xmover validate-move schema.table shard_id from_node to_node[/cyan]"
+        )
+        console.print("3. Check zone conflicts: [cyan]xmover zone-analysis --show-shards[/cyan]")
+        console.print("4. Verify node capacity: [cyan]xmover analyze[/cyan]")
+        console.print("5. Review CrateDB documentation on shard allocation")
+
+    console.print()
+    console.print("[dim]💡 Tip: Use 'xmover validate-move' to check moves before execution[/dim]")
+    console.print(
+        "[dim]📚 For more help: https://crate.io/docs/crate/reference/en/latest/admin/system-information.html[/dim]"
+    )
diff --git a/cratedb_toolkit/admin/xmover/util/format.py b/cratedb_toolkit/admin/xmover/util/format.py
