medic-cli 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
medic/config.py ADDED
@@ -0,0 +1,199 @@
1
+ """TOML config loader: declare checks (with optional stages) in a file.
2
+
3
+ Example::
4
+
5
+ [settings]
6
+ timeout = 6
7
+ fail_on = "warning" # or "failure" (default)
8
+
9
+ [[check]]
10
+ type = "tcp"
11
+ target = "db:5432"
12
+ stage = 0 # later stages are skipped if an earlier one fails
13
+
14
+ [[check]]
15
+ type = "http"
16
+ name = "API health"
17
+ url = "https://api.example.com/health"
18
+ expect_status = [200]
19
+ stage = 1
20
+ """
21
+
22
+ import sys
23
+ from pathlib import Path
24
+ from typing import Any, Callable, Dict, List, Optional, Tuple
25
+
26
+ if sys.version_info >= (3, 11):
27
+ import tomllib
28
+ else: # pragma: no cover
29
+ import tomli as tomllib
30
+
31
+ from medic.checks.dns import DNSCheck
32
+ from medic.checks.exec import ExecCheck
33
+ from medic.checks.http import HTTPCheck
34
+ from medic.checks.ping import PingCheck
35
+ from medic.checks.ssh import SSHCheck
36
+ from medic.checks.system import SystemCheckGroup
37
+ from medic.checks.tcp import TCPCheck
38
+ from medic.checks.tls import TLSCheck
39
+ from medic.core.base import BaseCheck
40
+
41
+ SETTINGS_KEYS = {"timeout", "concurrency", "fail_on", "stop_on_failure", "parallel"}
42
+
43
+
44
+ class ConfigError(ValueError):
45
+ """Raised for invalid config files."""
46
+
47
+
48
+ def _pair(value: Any, key: str) -> Tuple[float, float]:
49
+ if not (isinstance(value, (list, tuple)) and len(value) == 2):
50
+ raise ConfigError(f"'{key}' must be [warn, crit]")
51
+ return float(value[0]), float(value[1])
52
+
53
+
54
+ def _status_list(value: Any) -> List[int]:
55
+ if isinstance(value, int):
56
+ return [value]
57
+ if isinstance(value, list) and all(isinstance(v, int) for v in value):
58
+ return list(value)
59
+ raise ConfigError("'expect_status' must be an int or a list of ints")
60
+
61
+
62
+ def _build_system(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
63
+ cpu = _pair(o.pop("cpu", [80, 95]), "cpu")
64
+ ram = _pair(o.pop("ram", [85, 95]), "ram")
65
+ disk = _pair(o.pop("disk_threshold", [85, 92]), "disk_threshold")
66
+ return SystemCheckGroup(
67
+ disk_paths=list(o.pop("disks", ["/"])),
68
+ cpu_warn=cpu[0], cpu_crit=cpu[1],
69
+ ram_warn=ram[0], ram_crit=ram[1],
70
+ disk_warn=disk[0], disk_crit=disk[1],
71
+ timeout=timeout,
72
+ )
73
+
74
+
75
+ def _build_ping(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
76
+ return PingCheck(host=o.pop("host"), name=base["name"], count=int(o.pop("count", 3)), timeout_sec=timeout)
77
+
78
+
79
+ def _build_tcp(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
80
+ if "target" in o:
81
+ return TCPCheck.from_target(o.pop("target"), name=base["name"], timeout=timeout)
82
+ return TCPCheck(host=o.pop("host"), port=int(o.pop("port")), name=base["name"], timeout=timeout)
83
+
84
+
85
+ def _build_http(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
86
+ kwargs: Dict[str, Any] = {}
87
+ if "expect_status" in o:
88
+ kwargs["expected_status"] = _status_list(o.pop("expect_status"))
89
+ if "headers" in o:
90
+ kwargs["headers"] = dict(o.pop("headers"))
91
+ return HTTPCheck(
92
+ url=o.pop("url"),
93
+ name=base["name"],
94
+ method=o.pop("method", "GET"),
95
+ verify_ssl=bool(o.pop("verify_ssl", True)),
96
+ contains_text=o.pop("match", None),
97
+ timeout=timeout,
98
+ **kwargs,
99
+ )
100
+
101
+
102
+ def _build_tls(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
103
+ extra: Dict[str, Any] = {"warn_days": int(o.pop("warn_days", 30)), "crit_days": int(o.pop("crit_days", 7))}
104
+ if "target" in o:
105
+ return TLSCheck.from_target(o.pop("target"), name=base["name"], timeout=timeout, **extra)
106
+ return TLSCheck(host=o.pop("host"), port=int(o.pop("port", 443)), name=base["name"], timeout=timeout, **extra)
107
+
108
+
109
+ def _build_ssh(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
110
+ return SSHCheck.from_target(
111
+ o.pop("target"),
112
+ name=base["name"],
113
+ username=o.pop("user", None),
114
+ key_path=o.pop("key", None),
115
+ check_auth=bool(o.pop("auth", False)),
116
+ timeout=timeout,
117
+ )
118
+
119
+
120
+ def _build_exec(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
121
+ return ExecCheck(
122
+ command=o.pop("command"),
123
+ name=base["name"],
124
+ expect_exit=int(o.pop("expect_exit", 0)),
125
+ contains_text=o.pop("match", None),
126
+ shell=bool(o.pop("shell", False)),
127
+ cwd=o.pop("cwd", None),
128
+ timeout=timeout,
129
+ )
130
+
131
+
132
+ def _build_dns(o: Dict[str, Any], timeout: float, base: Dict[str, Any]) -> BaseCheck:
133
+ return DNSCheck(host=o.pop("host"), name=base["name"], expect=o.pop("expect", None), timeout=timeout)
134
+
135
+
136
+ _BUILDERS: Dict[str, Callable[[Dict[str, Any], float, Dict[str, Any]], BaseCheck]] = {
137
+ "system": _build_system,
138
+ "ping": _build_ping,
139
+ "tcp": _build_tcp,
140
+ "http": _build_http,
141
+ "tls": _build_tls,
142
+ "ssh": _build_ssh,
143
+ "exec": _build_exec,
144
+ "dns": _build_dns,
145
+ }
146
+
147
+
148
+ def build_check(entry: Dict[str, Any], default_timeout: float, index: int = 0) -> BaseCheck:
149
+ """Build one check from a config table; raises ConfigError on bad input."""
150
+ where = f"check #{index + 1}"
151
+ o = dict(entry)
152
+ ctype = o.pop("type", None)
153
+ if ctype not in _BUILDERS:
154
+ raise ConfigError(f"{where}: unknown type {ctype!r} (expected one of {', '.join(_BUILDERS)})")
155
+ label = f"{where} ({ctype})"
156
+
157
+ base = {"name": o.pop("name", None)}
158
+ stage = o.pop("stage", 0)
159
+ enabled = o.pop("enabled", True)
160
+ timeout = float(o.pop("timeout", default_timeout))
161
+ if not isinstance(stage, int) or isinstance(stage, bool):
162
+ raise ConfigError(f"{label}: 'stage' must be an integer")
163
+
164
+ try:
165
+ check = _BUILDERS[ctype](o, timeout, base)
166
+ except KeyError as exc:
167
+ raise ConfigError(f"{label}: missing required key {exc.args[0]!r}") from None
168
+ except (TypeError, ValueError) as exc:
169
+ if isinstance(exc, ConfigError):
170
+ raise ConfigError(f"{label}: {exc}") from None
171
+ raise ConfigError(f"{label}: invalid value ({exc})") from None
172
+ if o:
173
+ raise ConfigError(f"{label}: unknown key(s): {', '.join(sorted(o))}")
174
+ check.stage = stage
175
+ check.enabled = bool(enabled)
176
+ return check
177
+
178
+
179
+ def load_config(path: str, timeout_override: Optional[float] = None) -> Tuple[Dict[str, Any], List[BaseCheck]]:
180
+ """Parse a TOML file into (settings, checks)."""
181
+ try:
182
+ data = tomllib.loads(Path(path).read_text(encoding="utf-8"))
183
+ except OSError as exc:
184
+ raise ConfigError(f"cannot read {path}: {exc.strerror or exc}") from None
185
+ except tomllib.TOMLDecodeError as exc:
186
+ raise ConfigError(f"{path}: invalid TOML: {exc}") from None
187
+
188
+ settings = dict(data.get("settings", {}))
189
+ unknown = set(settings) - SETTINGS_KEYS
190
+ if unknown:
191
+ raise ConfigError(f"[settings]: unknown key(s): {', '.join(sorted(unknown))}")
192
+ if settings.get("fail_on", "failure") not in ("failure", "warning"):
193
+ raise ConfigError("[settings]: fail_on must be 'failure' or 'warning'")
194
+
195
+ entries = data.get("check", [])
196
+ if not isinstance(entries, list) or not entries:
197
+ raise ConfigError(f"{path}: no [[check]] entries defined")
198
+ timeout = float(timeout_override if timeout_override is not None else settings.get("timeout", 6.0))
199
+ return settings, [build_check(e, timeout, i) for i, e in enumerate(entries)]
medic/core/__init__.py ADDED
@@ -0,0 +1,18 @@
1
+ """Core interfaces, models, and runner for medic."""
2
+
3
+ from .base import BaseCheck, timed_execution
4
+ from .enums import CheckCategory, CheckStatus, OutputFormat, Severity
5
+ from .models import CheckResult, MedicReport
6
+ from .runner import MedicRunner
7
+
8
+ __all__ = [
9
+ "BaseCheck",
10
+ "timed_execution",
11
+ "CheckCategory",
12
+ "CheckStatus",
13
+ "OutputFormat",
14
+ "Severity",
15
+ "CheckResult",
16
+ "MedicReport",
17
+ "MedicRunner",
18
+ ]
medic/core/base.py ADDED
@@ -0,0 +1,48 @@
1
+ """Abstract base classes and interfaces for medic checks."""
2
+
3
+ import time
4
+ from abc import ABC, abstractmethod
5
+ from contextlib import contextmanager
6
+ from typing import Generator, List, Optional, Union
7
+
8
+ from .enums import CheckCategory
9
+ from .models import CheckResult
10
+
11
+
12
+ @contextmanager
13
+ def timed_execution() -> Generator[dict, None, None]:
14
+ """Context manager to measure execution time in milliseconds."""
15
+ tracker = {"elapsed_ms": 0.0}
16
+ start = time.perf_counter()
17
+ try:
18
+ yield tracker
19
+ finally:
20
+ end = time.perf_counter()
21
+ tracker["elapsed_ms"] = (end - start) * 1000.0
22
+
23
+
24
+ class BaseCheck(ABC):
25
+ """Abstract base class for all health checks."""
26
+
27
+ name: str
28
+ category: CheckCategory
29
+ description: str = ""
30
+ timeout: float = 10.0
31
+ enabled: bool = True
32
+ stage: int = 0
33
+
34
+ def __init__(
35
+ self,
36
+ name: Optional[str] = None,
37
+ timeout: float = 10.0,
38
+ enabled: bool = True,
39
+ ) -> None:
40
+ if name is not None:
41
+ self.name = name
42
+ self.timeout = timeout
43
+ self.enabled = enabled
44
+
45
+ @abstractmethod
46
+ def run(self) -> Union[CheckResult, List[CheckResult]]:
47
+ """Execute the check and return one or more CheckResult objects."""
48
+ raise NotImplementedError("Subclasses must implement run()")
medic/core/enums.py ADDED
@@ -0,0 +1,85 @@
1
+ """Core enumeration types for medic."""
2
+
3
+ from enum import Enum
4
+
5
+
6
+ class CheckStatus(str, Enum):
7
+ """Status of a health check result."""
8
+ PASSED = "passed"
9
+ WARNING = "warning"
10
+ FAILED = "failed"
11
+ SKIPPED = "skipped"
12
+ ERROR = "error"
13
+
14
+ @property
15
+ def is_healthy(self) -> bool:
16
+ """Returns True if the check indicates healthy state."""
17
+ return self in (CheckStatus.PASSED, CheckStatus.WARNING)
18
+
19
+ @property
20
+ def icon(self) -> str:
21
+ """Unicode icon representing the status."""
22
+ return {
23
+ CheckStatus.PASSED: "✔",
24
+ CheckStatus.WARNING: "⚠",
25
+ CheckStatus.FAILED: "✖",
26
+ CheckStatus.SKIPPED: "⊘",
27
+ CheckStatus.ERROR: "⚡",
28
+ }[self]
29
+
30
+ @property
31
+ def color(self) -> str:
32
+ """Rich style color corresponding to status."""
33
+ return {
34
+ CheckStatus.PASSED: "green",
35
+ CheckStatus.WARNING: "yellow",
36
+ CheckStatus.FAILED: "red",
37
+ CheckStatus.SKIPPED: "dim",
38
+ CheckStatus.ERROR: "bold red",
39
+ }[self]
40
+
41
+
42
+ class CheckCategory(str, Enum):
43
+ """Categories of health checks supported by medic."""
44
+ SYSTEM = "system"
45
+ PING = "ping"
46
+ TCP = "tcp"
47
+ HTTP = "http"
48
+ TLS = "tls"
49
+ SSH = "ssh"
50
+ DOCKER = "docker"
51
+ DNS = "dns"
52
+ EXEC = "exec"
53
+
54
+ @property
55
+ def display_name(self) -> str:
56
+ """Human-readable display title for category."""
57
+ return {
58
+ CheckCategory.SYSTEM: "System",
59
+ CheckCategory.PING: "Ping",
60
+ CheckCategory.TCP: "TCP",
61
+ CheckCategory.HTTP: "HTTP",
62
+ CheckCategory.TLS: "TLS/SSL",
63
+ CheckCategory.SSH: "SSH",
64
+ CheckCategory.DOCKER: "Docker",
65
+ CheckCategory.DNS: "DNS",
66
+ CheckCategory.EXEC: "Exec",
67
+ }[self]
68
+
69
+
70
+ class OutputFormat(str, Enum):
71
+ """Supported output formats."""
72
+ RICH = "rich"
73
+ JSON = "json"
74
+ TEXT = "text"
75
+ COMPACT = "compact"
76
+ JUNIT = "junit"
77
+
78
+
79
+ class Severity(str, Enum):
80
+ """Severity levels for checks and warnings."""
81
+ INFO = "info"
82
+ LOW = "low"
83
+ MEDIUM = "medium"
84
+ HIGH = "high"
85
+ CRITICAL = "critical"
medic/core/models.py ADDED
@@ -0,0 +1,116 @@
1
+ """Core data models for check results and reports."""
2
+
3
+ from dataclasses import dataclass, field
4
+ from datetime import datetime, timezone
5
+ from typing import Any, Dict, List, Optional
6
+
7
+ from .enums import CheckCategory, CheckStatus
8
+
9
+
10
+ @dataclass
11
+ class CheckResult:
12
+ """Represents the outcome of an individual check."""
13
+ name: str
14
+ category: CheckCategory
15
+ status: CheckStatus
16
+ message: str
17
+ target: str = ""
18
+ latency_ms: Optional[float] = None
19
+ details: Dict[str, Any] = field(default_factory=dict)
20
+ timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
21
+ remediation: Optional[str] = None
22
+
23
+ @property
24
+ def is_success(self) -> bool:
25
+ """Returns True if status is PASSED."""
26
+ return self.status == CheckStatus.PASSED
27
+
28
+ @property
29
+ def is_warning(self) -> bool:
30
+ """Returns True if status is WARNING."""
31
+ return self.status == CheckStatus.WARNING
32
+
33
+ @property
34
+ def is_failure(self) -> bool:
35
+ """Returns True if status is FAILED or ERROR."""
36
+ return self.status in (CheckStatus.FAILED, CheckStatus.ERROR)
37
+
38
+ def to_dict(self) -> Dict[str, Any]:
39
+ """Convert result to JSON-serializable dictionary."""
40
+ return {
41
+ "name": self.name,
42
+ "category": self.category.value,
43
+ "status": self.status.value,
44
+ "message": self.message,
45
+ "target": self.target,
46
+ "latency_ms": round(self.latency_ms, 2) if self.latency_ms is not None else None,
47
+ "details": self.details,
48
+ "timestamp": self.timestamp.isoformat(),
49
+ "remediation": self.remediation,
50
+ }
51
+
52
+
53
+ @dataclass
54
+ class MedicReport:
55
+ """Aggregated health check report."""
56
+ results: List[CheckResult] = field(default_factory=list)
57
+ timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
58
+ duration_ms: float = 0.0
59
+
60
+ @property
61
+ def total_count(self) -> int:
62
+ return len(self.results)
63
+
64
+ @property
65
+ def passed_count(self) -> int:
66
+ return sum(1 for r in self.results if r.status == CheckStatus.PASSED)
67
+
68
+ @property
69
+ def warning_count(self) -> int:
70
+ return sum(1 for r in self.results if r.status == CheckStatus.WARNING)
71
+
72
+ @property
73
+ def failed_count(self) -> int:
74
+ return sum(1 for r in self.results if r.status == CheckStatus.FAILED)
75
+
76
+ @property
77
+ def skipped_count(self) -> int:
78
+ return sum(1 for r in self.results if r.status == CheckStatus.SKIPPED)
79
+
80
+ @property
81
+ def error_count(self) -> int:
82
+ return sum(1 for r in self.results if r.status == CheckStatus.ERROR)
83
+
84
+ @property
85
+ def is_healthy(self) -> bool:
86
+ """Returns True if no checks failed or errored."""
87
+ return self.failed_count == 0 and self.error_count == 0
88
+
89
+ @property
90
+ def exit_code(self) -> int:
91
+ """Standard CLI exit code: 0 if healthy (or only warnings), 1 if any failure/error."""
92
+ return 0 if self.is_healthy else 1
93
+
94
+ def exit_code_for(self, fail_on: str = "failure") -> int:
95
+ """Exit code under a failure policy: 'failure' (default) or 'warning' (warnings also fail)."""
96
+ if fail_on == "warning" and self.warning_count:
97
+ return 1
98
+ return self.exit_code
99
+
100
+ def to_dict(self) -> Dict[str, Any]:
101
+ """Convert report to JSON-serializable dictionary."""
102
+ return {
103
+ "timestamp": self.timestamp.isoformat(),
104
+ "duration_ms": round(self.duration_ms, 2),
105
+ "summary": {
106
+ "total": self.total_count,
107
+ "passed": self.passed_count,
108
+ "warning": self.warning_count,
109
+ "failed": self.failed_count,
110
+ "skipped": self.skipped_count,
111
+ "error": self.error_count,
112
+ "is_healthy": self.is_healthy,
113
+ "exit_code": self.exit_code,
114
+ },
115
+ "results": [r.to_dict() for r in self.results],
116
+ }
medic/core/runner.py ADDED
@@ -0,0 +1,212 @@
1
+ """Check runner and execution engine."""
2
+
3
+ import concurrent.futures
4
+ import threading
5
+ import time
6
+ import traceback
7
+ from datetime import datetime, timezone
8
+ from typing import Callable, Dict, List, Optional
9
+
10
+ from .base import BaseCheck
11
+ from .enums import CheckCategory, CheckStatus
12
+ from .models import CheckResult, MedicReport
13
+
14
+ # Extra seconds a check gets beyond its own ``timeout`` before the runner
15
+ # gives up on it. Checks enforce their own socket/subprocess timeouts; this
16
+ # is the backstop for anything that hangs regardless.
17
+ TIMEOUT_GRACE_SEC = 2.0
18
+
19
+
20
+ class MedicRunner:
21
+ """Orchestrates execution of health checks.
22
+
23
+ Checks are grouped by ``check.stage`` and stages run in ascending order.
24
+ If any check in a stage fails, every check in later stages is skipped
25
+ (checkpoint semantics). With ``stop_on_failure`` the run is sequential and
26
+ stops at the first failing check.
27
+ """
28
+
29
+ def __init__(
30
+ self,
31
+ checks: Optional[List[BaseCheck]] = None,
32
+ parallel: bool = True,
33
+ max_workers: int = 8,
34
+ stop_on_failure: bool = False,
35
+ on_result: Optional[Callable[[CheckResult], None]] = None,
36
+ ) -> None:
37
+ self.checks: List[BaseCheck] = checks or []
38
+ self.parallel = parallel
39
+ self.max_workers = max_workers
40
+ self.stop_on_failure = stop_on_failure
41
+ self.on_result = on_result
42
+ self._callback_lock = threading.Lock()
43
+
44
+ def add_check(self, check: BaseCheck) -> "MedicRunner":
45
+ """Add a single check to the runner."""
46
+ self.checks.append(check)
47
+ return self
48
+
49
+ def add_checks(self, checks: List[BaseCheck]) -> "MedicRunner":
50
+ """Add multiple checks to the runner."""
51
+ self.checks.extend(checks)
52
+ return self
53
+
54
+ def _emit(self, results: List[CheckResult]) -> None:
55
+ if self.on_result:
56
+ with self._callback_lock:
57
+ for r in results:
58
+ self.on_result(r)
59
+
60
+ @staticmethod
61
+ def _call_with_timeout(check: BaseCheck, timeout: float):
62
+ """Run check.run() in a daemon thread; return (done, value, exc, tb)."""
63
+ box: Dict[str, object] = {}
64
+
65
+ def target() -> None:
66
+ try:
67
+ box["value"] = check.run()
68
+ except BaseException as exc: # noqa: BLE001 - reported as ERROR result
69
+ box["exc"] = exc
70
+ box["tb"] = traceback.format_exc()
71
+
72
+ # Daemon thread: a hung check must not keep the interpreter alive.
73
+ thread = threading.Thread(target=target, name=f"medic-{getattr(check, 'name', 'check')}", daemon=True)
74
+ thread.start()
75
+ thread.join(timeout)
76
+ return (not thread.is_alive()), box
77
+
78
+ def _execute_check_safe(self, check: BaseCheck) -> List[CheckResult]:
79
+ """Safely execute a single check, enforcing its timeout and catching exceptions."""
80
+ name = getattr(check, "name", type(check).__name__)
81
+ category = getattr(check, "category", CheckCategory.SYSTEM)
82
+
83
+ if not check.enabled:
84
+ results = [CheckResult(name=name, category=category, status=CheckStatus.SKIPPED, message="Check is disabled")]
85
+ self._emit(results)
86
+ return results
87
+
88
+ limit = float(getattr(check, "timeout", 10.0)) + TIMEOUT_GRACE_SEC
89
+ start_time = time.perf_counter()
90
+ done, box = self._call_with_timeout(check, limit)
91
+ elapsed_ms = (time.perf_counter() - start_time) * 1000.0
92
+
93
+ if not done:
94
+ results = [
95
+ CheckResult(
96
+ name=name,
97
+ category=category,
98
+ status=CheckStatus.FAILED,
99
+ message=f"Timed out after {limit:.1f}s",
100
+ latency_ms=elapsed_ms,
101
+ details={"timeout_sec": limit},
102
+ remediation="The check hung past its timeout; verify the target is reachable.",
103
+ )
104
+ ]
105
+ elif "exc" in box:
106
+ exc = box["exc"]
107
+ assert isinstance(exc, BaseException)
108
+ results = [
109
+ CheckResult(
110
+ name=name,
111
+ category=category,
112
+ status=CheckStatus.ERROR,
113
+ message=f"Unhandled exception: {str(exc) or exc.__class__.__name__}",
114
+ latency_ms=elapsed_ms,
115
+ details={
116
+ "exception": exc.__class__.__name__,
117
+ "error": str(exc),
118
+ "traceback": box.get("tb", ""),
119
+ },
120
+ )
121
+ ]
122
+ else:
123
+ raw = box.get("value")
124
+ if isinstance(raw, list):
125
+ results = raw
126
+ elif isinstance(raw, CheckResult):
127
+ results = [raw]
128
+ else:
129
+ results = [
130
+ CheckResult(
131
+ name=name,
132
+ category=category,
133
+ status=CheckStatus.ERROR,
134
+ message=f"Check returned invalid result type: {type(raw).__name__}",
135
+ latency_ms=elapsed_ms,
136
+ )
137
+ ]
138
+ # Only a lone result can be attributed the whole check's wall time;
139
+ # multi-result checks report their own per-result latency.
140
+ if len(results) == 1 and results[0].latency_ms is None:
141
+ results[0].latency_ms = elapsed_ms
142
+
143
+ self._emit(results)
144
+ return results
145
+
146
+ def _skipped_for_stage(self, check: BaseCheck, failed_stage: int) -> List[CheckResult]:
147
+ results = [
148
+ CheckResult(
149
+ name=getattr(check, "name", type(check).__name__),
150
+ category=getattr(check, "category", CheckCategory.SYSTEM),
151
+ status=CheckStatus.SKIPPED,
152
+ message=f"Skipped: stage {failed_stage} failed",
153
+ )
154
+ ]
155
+ self._emit(results)
156
+ return results
157
+
158
+ def _run_stage(self, checks: List[BaseCheck]) -> List[CheckResult]:
159
+ """Run one stage's checks; returns results in registration order."""
160
+ if not self.parallel or self.stop_on_failure or len(checks) == 1:
161
+ out: List[CheckResult] = []
162
+ for check in checks:
163
+ results = self._execute_check_safe(check)
164
+ out.extend(results)
165
+ if self.stop_on_failure and any(r.is_failure for r in results):
166
+ break
167
+ return out
168
+
169
+ workers = max(1, min(len(checks), self.max_workers))
170
+ indexed: List[List[CheckResult]] = [[] for _ in checks]
171
+ with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
172
+ future_to_index = {executor.submit(self._execute_check_safe, c): i for i, c in enumerate(checks)}
173
+ for future in concurrent.futures.as_completed(future_to_index):
174
+ idx = future_to_index[future]
175
+ try:
176
+ indexed[idx] = future.result()
177
+ except Exception as e: # _execute_check_safe should not raise
178
+ indexed[idx] = [
179
+ CheckResult(
180
+ name=getattr(checks[idx], "name", f"Check-{idx}"),
181
+ category=getattr(checks[idx], "category", CheckCategory.SYSTEM),
182
+ status=CheckStatus.ERROR,
183
+ message=f"Thread execution failed: {e}",
184
+ )
185
+ ]
186
+ return [r for res in indexed for r in res]
187
+
188
+ def run(self) -> MedicReport:
189
+ """Run all configured checks and produce a MedicReport."""
190
+ start_time = time.perf_counter()
191
+ all_results: List[CheckResult] = []
192
+
193
+ stages: Dict[int, List[BaseCheck]] = {}
194
+ for check in self.checks:
195
+ stages.setdefault(getattr(check, "stage", 0), []).append(check)
196
+
197
+ failed_stage: Optional[int] = None
198
+ for stage in sorted(stages):
199
+ if failed_stage is not None:
200
+ for check in stages[stage]:
201
+ all_results.extend(self._skipped_for_stage(check, failed_stage))
202
+ continue
203
+ results = self._run_stage(stages[stage])
204
+ all_results.extend(results)
205
+ if any(r.is_failure for r in results):
206
+ failed_stage = stage
207
+
208
+ return MedicReport(
209
+ results=all_results,
210
+ timestamp=datetime.now(timezone.utc),
211
+ duration_ms=(time.perf_counter() - start_time) * 1000.0,
212
+ )