declarative-data-backup 0.3.0__tar.gz → 0.4.0__tar.gz

{declarative_data_backup-0.3.0/src/declarative_data_backup.egg-info → declarative_data_backup-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: declarative-data-backup
-Version: 0.3.0
+Version: 0.4.0
 Summary: Declarative Borg-based data backups
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -149,7 +149,7 @@ Optional variables:
 | --- | --- |
 | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
 | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
-| `BACKUP_PROGRESS` | Set to `true` to enable Borg's live progress output during archive creation. Defaults to `false` to limit log volume. |
+| `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
 | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
 
 Provide credentials through a secret manager or protected files; do not put
@@ -167,6 +167,21 @@ the run fails and pruning is skipped. Logs include group and source start/end
 messages, while Borg's per-file and per-archive output is disabled by default.
 Set `BACKUP_VERBOSE=true` for detailed Borg output or `BACKUP_PROGRESS=true`
 for live progress during archive creation; either can increase log volume.
+Progress is logged as plain status lines, not a terminal progress bar. Each
+line includes the group, source, elapsed time, and latest reported file/byte
+counters or Borg phase. Unchanged counters do not prove forward progress;
+before Borg reports a phase, the status only indicates that the process is
+running. Warnings and statistics are not throttled.
+
+On SIGTERM (including normal Kubernetes pod termination) or Ctrl+C, the
+wrapper asks Borg to stop and waits up to 20 seconds for cleanup before
+releasing its coordination lock. No further sources or pruning are started.
+The exit status is 143 for SIGTERM or 130 for Ctrl+C. Repeated termination
+signals are ignored during cleanup. If Borg does not stop within the timeout,
+its process group is killed and an error warns that Borg locks may remain.
+Use a pod termination grace period of at least 30 seconds (60 recommended);
+forced deletion or SIGKILL cannot be handled gracefully. Never break Borg
+locks without first confirming that no repository operation is still running.
 
 ## Configuration reference
 

declarative_data_backup-0.3.0/PKG-INFO → declarative_data_backup-0.4.0/README.md

@@ -1,11 +1,3 @@
-Metadata-Version: 2.4
-Name: declarative-data-backup
-Version: 0.3.0
-Summary: Declarative Borg-based data backups
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: PyYAML<7,>=6
-
 # Declarative Data Backup
 
 Declarative Data Backup creates encrypted Borg archives for configured source
@@ -149,7 +141,7 @@ Optional variables:
 | --- | --- |
 | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
 | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
-| `BACKUP_PROGRESS` | Set to `true` to enable Borg's live progress output during archive creation. Defaults to `false` to limit log volume. |
+| `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
 | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
 
 Provide credentials through a secret manager or protected files; do not put
@@ -167,6 +159,21 @@ the run fails and pruning is skipped. Logs include group and source start/end
 messages, while Borg's per-file and per-archive output is disabled by default.
 Set `BACKUP_VERBOSE=true` for detailed Borg output or `BACKUP_PROGRESS=true`
 for live progress during archive creation; either can increase log volume.
+Progress is logged as plain status lines, not a terminal progress bar. Each
+line includes the group, source, elapsed time, and latest reported file/byte
+counters or Borg phase. Unchanged counters do not prove forward progress;
+before Borg reports a phase, the status only indicates that the process is
+running. Warnings and statistics are not throttled.
+
+On SIGTERM (including normal Kubernetes pod termination) or Ctrl+C, the
+wrapper asks Borg to stop and waits up to 20 seconds for cleanup before
+releasing its coordination lock. No further sources or pruning are started.
+The exit status is 143 for SIGTERM or 130 for Ctrl+C. Repeated termination
+signals are ignored during cleanup. If Borg does not stop within the timeout,
+its process group is killed and an error warns that Borg locks may remain.
+Use a pod termination grace period of at least 30 seconds (60 recommended);
+forced deletion or SIGKILL cannot be handled gracefully. Never break Borg
+locks without first confirming that no repository operation is still running.
 
 ## Configuration reference
 

{declarative_data_backup-0.3.0 → declarative_data_backup-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "declarative-data-backup"
-version = "0.3.0"
+version = "0.4.0"
 description = "Declarative Borg-based data backups"
 readme = "README.md"
 requires-python = ">=3.11"

{declarative_data_backup-0.3.0 → declarative_data_backup-0.4.0}/src/declarative_data_backup/backup.py

@@ -1,8 +1,10 @@
 import logging
 import os
+import signal
 import uuid
 from collections.abc import Mapping
 from datetime import UTC, datetime
+from types import FrameType
 
 from .borg import (
     backup_folder,
@@ -14,7 +16,7 @@ from .borg.borg_cli import ensure_borg_binary
 from .config import configure_logging, load_yaml, parse_backup_definitions
 from .config.backup_config.models import BackupDefinition
 from .environment import Environment
-from .errors import BackupError, BorgWarningError
+from .errors import BackupError, BackupInterrupted, BorgWarningError
 
 logger = logging.getLogger(__name__)
 
@@ -90,6 +92,15 @@ def run_backup(
 
 def main(environ: Mapping[str, str] | None = None) -> int:
     configure_logging()
+
+    def interrupt(signum: int, frame: FrameType | None) -> None:
+        # Repeated signals must not interrupt Borg cleanup or lock release.
+        signal.signal(signal.SIGTERM, signal.SIG_IGN)
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+        raise BackupInterrupted(signum)
+
+    previous_sigterm = signal.signal(signal.SIGTERM, interrupt)
+    previous_sigint = signal.signal(signal.SIGINT, interrupt)
     try:
         settings = Environment.from_env(environ)
         logger.info("Starting backup using configuration %s", settings.config_path)
@@ -114,6 +125,15 @@ def main(environ: Mapping[str, str] | None = None) -> int:
             exc.strerror or "I/O error",
         )
         return 1
+    except BackupInterrupted as exc:
+        logger.error(
+            "Interrupted by %s; no further backups or pruning will run.",
+            signal.Signals(exc.signum).name,
+        )
+        return 128 + exc.signum
     except KeyboardInterrupt:
         logger.error("Interrupted.")
         return 130
+    finally:
+        signal.signal(signal.SIGTERM, previous_sigterm)
+        signal.signal(signal.SIGINT, previous_sigint)

declarative_data_backup-0.4.0/src/declarative_data_backup/borg/borg_cli.py

@@ -0,0 +1,193 @@
+import json
+import logging
+import os
+import selectors
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from ..environment import Environment
+from ..errors import BorgWarningError, fail
+
+logger = logging.getLogger(__name__)
+PROGRESS_INTERVAL_SECONDS = 30
+SHUTDOWN_TIMEOUT_SECONDS = 20
+
+
+@contextmanager
+def borg_process(
+    command: list[str],
+    environment: dict[str, str],
+    *,
+    capture_stderr: bool = False,
+) -> Generator[subprocess.Popen[bytes], None, None]:
+    with subprocess.Popen(
+        command,
+        env=environment,
+        start_new_session=True,
+        stderr=subprocess.PIPE if capture_stderr else None,
+    ) as process:
+        try:
+            yield process
+        except BaseException:
+            if process.poll() is None:
+                logger.warning(
+                    "Stopping Borg (pid=%d); waiting up to %d seconds for cleanup.",
+                    process.pid,
+                    SHUTDOWN_TIMEOUT_SECONDS,
+                )
+                process.terminate()
+                try:
+                    _, stderr = process.communicate(timeout=SHUTDOWN_TIMEOUT_SECONDS)
+                except subprocess.TimeoutExpired:
+                    logger.error(
+                        "Borg did not stop in time; killing its process group. "
+                        "Stale Borg locks may require inspection before retrying."
+                    )
+                    os.killpg(process.pid, signal.SIGKILL)
+                    _, stderr = process.communicate()
+                if stderr:
+                    sys.stderr.write(stderr.decode("utf-8", errors="replace"))
+                    sys.stderr.flush()
+                logger.warning("Borg stopped (exit code %d).", process.returncode)
+            raise
+
+
+def run_without_progress(command: list[str], environment: dict[str, str]) -> int:
+    with borg_process(command, environment) as process:
+        return process.wait()
+
+
+def run_with_progress(
+    command: list[str], environment: dict[str, str], context: str
+) -> int:
+    started_at = time.monotonic()
+    next_report = started_at + PROGRESS_INTERVAL_SECONDS
+    latest_progress = "Waiting for Borg progress (process running)."
+
+    def handle_line(line: bytes) -> None:
+        nonlocal latest_progress
+        text = line.decode("utf-8", errors="replace")
+        try:
+            event = json.loads(text)
+        except json.JSONDecodeError:
+            print(text, file=sys.stderr, flush=True)
+            return
+        if not isinstance(event, dict):
+            print(text, file=sys.stderr, flush=True)
+            return
+        kind = event.get("type")
+        if kind in ("archive_progress", "progress_message", "progress_percent"):
+            if event.get("finished"):
+                return
+            if kind == "archive_progress":
+                latest_progress = (
+                    f"files={event.get('nfiles')} "
+                    f"original_bytes={event.get('original_size')} "
+                    f"compressed_bytes={event.get('compressed_size')} "
+                    f"deduplicated_bytes={event.get('deduplicated_size')}"
+                )
+            else:
+                latest_progress = str(event.get("message", text))
+            return
+        if kind == "log_message":
+            print(event.get("message", text), file=sys.stderr, flush=True)
+        else:
+            print(text, file=sys.stderr, flush=True)
+
+    with borg_process(command, environment, capture_stderr=True) as process:
+        assert process.stderr is not None
+        with selectors.DefaultSelector() as selector:
+            selector.register(process.stderr, selectors.EVENT_READ)
+            pending = b""
+            while selector.get_map():
+                for key, _ in selector.select(max(0, next_report - time.monotonic())):
+                    chunk = os.read(key.fd, 65536)
+                    if not chunk:
+                        selector.unregister(key.fileobj)
+                        if pending:
+                            handle_line(pending)
+                        break
+                    pending += chunk
+                    while b"\n" in pending:
+                        line, pending = pending.split(b"\n", 1)
+                        handle_line(line)
+                now = time.monotonic()
+                if now >= next_report and selector.get_map():
+                    logger.info(
+                        "Borg progress for %s (elapsed_seconds=%.0f; "
+                        "latest reported: %s).",
+                        context,
+                        now - started_at,
+                        latest_progress,
+                    )
+                    next_report = now + PROGRESS_INTERVAL_SECONDS
+        return process.wait()
+
+
+def ensure_borg_binary() -> None:
+    if shutil.which("borg") is None:
+        fail("Required executable 'borg' was not found on PATH.")
+
+
+def borg_environment(settings: Environment) -> dict[str, str]:
+    environment = os.environ.copy()
+    environment.update(
+        {
+            "BORG_REPO": settings.borg_repo,
+            "BORG_BASE_DIR": str(settings.borg_base_dir),
+            "BORG_KEY_FILE": str(settings.key_file),
+            "BORG_RSH": settings.borg_rsh,
+            "BORG_PASSCOMMAND": settings.borg_passcommand,
+        }
+    )
+    if settings.borg_exit_codes is not None:
+        environment["BORG_EXIT_CODES"] = settings.borg_exit_codes
+    return environment
+
+
+def run_borg(
+    args: list[str],
+    settings: Environment,
+    operation: str,
+    context: str,
+) -> None:
+    logger.info("Running Borg %s for %s.", operation, context)
+    command = ["borg"]
+    remote_path = settings.borg_remote_path
+    if remote_path is not None:
+        if not remote_path.strip() or "\0" in remote_path:
+            fail("BORG_REMOTE_PATH must be a nonempty Borg executable path.")
+        command.extend(("--remote-path", remote_path))
+    command.extend(args)
+
+    try:
+        if settings.backup_progress and operation == "create":
+            command.insert(1, "--log-json")
+            returncode = run_with_progress(
+                command,
+                borg_environment(settings),
+                context,
+            )
+        else:
+            returncode = run_without_progress(command, borg_environment(settings))
+    except FileNotFoundError:
+        fail("Required executable 'borg' could not be started.")
+    except OSError as exc:
+        fail(
+            f"Unable to start Borg {operation} for {context}: {exc.strerror or 'I/O error'}."
+        )
+
+    if returncode == 0:
+        return
+
+    if returncode == 1:
+        message = f"Borg {operation} reported warnings for {context} (exit code 1)."
+        logger.warning("%s", message)
+        raise BorgWarningError(message)
+
+    fail(f"Borg {operation} failed for {context} (exit code {returncode}).")

{declarative_data_backup-0.3.0 → declarative_data_backup-0.4.0}/src/declarative_data_backup/errors.py

@@ -9,5 +9,11 @@ class BorgWarningError(BackupError):
     """Raised when Borg completes with warnings that make the run unsafe."""
 
 
+class BackupInterrupted(KeyboardInterrupt):
+    def __init__(self, signum: int) -> None:
+        self.signum = signum
+        super().__init__(f"Interrupted by signal {signum}.")
+
+
 def fail(message: str) -> NoReturn:
     raise BackupError(message)

declarative_data_backup-0.3.0/README.md → declarative_data_backup-0.4.0/src/declarative_data_backup.egg-info/PKG-INFO

@@ -1,3 +1,11 @@
+Metadata-Version: 2.4
+Name: declarative-data-backup
+Version: 0.4.0
+Summary: Declarative Borg-based data backups
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: PyYAML<7,>=6
+
 # Declarative Data Backup
 
 Declarative Data Backup creates encrypted Borg archives for configured source
@@ -141,7 +149,7 @@ Optional variables:
 | --- | --- |
 | `BORG_REMOTE_PATH` | Remote Borg executable path, passed as Borg's `--remote-path`. Leave unset to use Borg's default. |
 | `BORG_EXIT_CODES` | Borg exit-code mode: `legacy` or `modern`. |
-| `BACKUP_PROGRESS` | Set to `true` to enable Borg's live progress output during archive creation. Defaults to `false` to limit log volume. |
+| `BACKUP_PROGRESS` | Set to `true` to log the latest Borg progress every 30 seconds during archive creation. Defaults to `false`. |
 | `BACKUP_VERBOSE` | Set to `true` to show Borg's per-file create and per-archive prune output. Defaults to `false` for concise logs. |
 
 Provide credentials through a secret manager or protected files; do not put
@@ -159,6 +167,21 @@ the run fails and pruning is skipped. Logs include group and source start/end
 messages, while Borg's per-file and per-archive output is disabled by default.
 Set `BACKUP_VERBOSE=true` for detailed Borg output or `BACKUP_PROGRESS=true`
 for live progress during archive creation; either can increase log volume.
+Progress is logged as plain status lines, not a terminal progress bar. Each
+line includes the group, source, elapsed time, and latest reported file/byte
+counters or Borg phase. Unchanged counters do not prove forward progress;
+before Borg reports a phase, the status only indicates that the process is
+running. Warnings and statistics are not throttled.
+
+On SIGTERM (including normal Kubernetes pod termination) or Ctrl+C, the
+wrapper asks Borg to stop and waits up to 20 seconds for cleanup before
+releasing its coordination lock. No further sources or pruning are started.
+The exit status is 143 for SIGTERM or 130 for Ctrl+C. Repeated termination
+signals are ignored during cleanup. If Borg does not stop within the timeout,
+its process group is killed and an error warns that Borg locks may remain.
+Use a pod termination grace period of at least 30 seconds (60 recommended);
+forced deletion or SIGKILL cannot be handled gracefully. Never break Borg
+locks without first confirming that no repository operation is still running.
 
 ## Configuration reference
 

declarative_data_backup-0.3.0/src/declarative_data_backup/borg/borg_cli.py

@@ -1,69 +0,0 @@
-import logging
-import os
-import shutil
-import subprocess
-
-from ..environment import Environment
-from ..errors import BorgWarningError, fail
-
-logger = logging.getLogger(__name__)
-
-
-def ensure_borg_binary() -> None:
-    if shutil.which("borg") is None:
-        fail("Required executable 'borg' was not found on PATH.")
-
-
-def borg_environment(settings: Environment) -> dict[str, str]:
-    environment = os.environ.copy()
-    environment.update(
-        {
-            "BORG_REPO": settings.borg_repo,
-            "BORG_BASE_DIR": str(settings.borg_base_dir),
-            "BORG_KEY_FILE": str(settings.key_file),
-            "BORG_RSH": settings.borg_rsh,
-            "BORG_PASSCOMMAND": settings.borg_passcommand,
-        }
-    )
-    if settings.borg_exit_codes is not None:
-        environment["BORG_EXIT_CODES"] = settings.borg_exit_codes
-    return environment
-
-
-def run_borg(
-    args: list[str],
-    settings: Environment,
-    operation: str,
-    context: str,
-) -> None:
-    logger.info("Running Borg %s for %s.", operation, context)
-    command = ["borg"]
-    remote_path = settings.borg_remote_path
-    if remote_path is not None:
-        if not remote_path.strip() or "\0" in remote_path:
-            fail("BORG_REMOTE_PATH must be a nonempty Borg executable path.")
-        command.extend(("--remote-path", remote_path))
-    command.extend(args)
-
-    try:
-        result = subprocess.run(
-            command,
-            env=borg_environment(settings),
-            check=False,
-        )
-    except FileNotFoundError:
-        fail("Required executable 'borg' could not be started.")
-    except OSError as exc:
-        fail(
-            f"Unable to start Borg {operation} for {context}: {exc.strerror or 'I/O error'}."
-        )
-
-    if result.returncode == 0:
-        return
-
-    if result.returncode == 1:
-        message = f"Borg {operation} reported warnings for {context} (exit code 1)."
-        logger.warning("%s", message)
-        raise BorgWarningError(message)
-
-    fail(f"Borg {operation} failed for {context} (exit code {result.returncode}).")