"""
db_snapshot.py — WAL-safe snapshot / restore helpers for seismo_relay.db and
the waveform store, backing the /db/snapshot, /db/waveforms/recent.zip and
/db/restore endpoints in server.py. Kept out of server.py so the logic is
unit-testable without HTTP.
"""
from __future__ import annotations
import sqlite3
from pathlib import Path


def snapshot_db(src_path: Path, dest_path: Path) -> Path:
    """WAL-safe copy of a live SQLite DB via the SQLite online backup API.
    Consistent even while the source is being written under WAL, and never
    blocks the source's writers."""
    src = sqlite3.connect(str(src_path))
    dest = sqlite3.connect(str(dest_path))
    try:
        with dest:
            src.backup(dest)
    finally:
        src.close()
        dest.close()
    return Path(dest_path)