feat: add archive client foundation

src/archive_clients/probes.py

@@ -0,0 +1,54 @@
+"""Fail-fast root and filesystem capability probes."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ProbeError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class FilesystemProbe:
+    root: Path
+    readable: bool
+    writable: bool
+    hard_link: bool
+    sparse_files: bool
+
+
+def probe_root(root: Path) -> FilesystemProbe:
+    if not root.is_absolute() or not root.is_dir():
+        raise ProbeError(f"configured root is not an existing absolute directory: {root}")
+    if not os.access(root, os.R_OK | os.X_OK | os.W_OK):
+        raise ProbeError(f"configured root permissions are insufficient: {root}")
+    source: Path | None = None
+    linked: Path | None = None
+    try:
+        descriptor, raw_path = tempfile.mkstemp(prefix=".archive-control-probe-", dir=root)
+        source = Path(raw_path)
+        with os.fdopen(descriptor, "wb") as probe:
+            probe.seek(1024 * 1024)
+            probe.write(b"x")
+            probe.flush()
+            os.fsync(probe.fileno())
+        allocated = source.stat().st_blocks * 512
+        sparse = allocated < source.stat().st_size
+        linked = source.with_name(f"{source.name}.link")
+        try:
+            os.link(source, linked)
+            hard_link = linked.stat().st_ino == source.stat().st_ino
+        except OSError:
+            hard_link = False
+        return FilesystemProbe(root, True, True, hard_link, sparse)
+    except OSError as exc:
+        raise ProbeError(f"filesystem capability probe failed for {root}") from exc
+    finally:
+        if linked is not None:
+            linked.unlink(missing_ok=True)
+        if source is not None:
+            source.unlink(missing_ok=True)