gea-program 0.17.0__tar.gz → 0.18.0__tar.gz

{gea_program-0.17.0/gea_program.egg-info → gea_program-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.17.0
+Version: 0.18.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -125,7 +125,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (340 checks)
+gea accept                     # the product gate (342 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -722,6 +722,14 @@ headers on every response, and `gea housekeeping --workspace C:\site --apply`
 than truncating them and prunes finished job folders and old recordings. `gea
 loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
 machine carries the patches it will be given, with the page still answering.
+`gea backup --workspace C:\site --out D:\gea-backups --keep 14` copies the
+whole site into one dated archive with a manifest of every file's hash, onto
+another disk or a share; schedule it daily from Audit / Update, verify an
+archive with `--verify`, and restore one onto an empty folder with
+`--restore ... --to` and open it once before the first well is live - the
+records are the product, and a backup nobody has restored is a hope. The
+doctor warns when there has never been a backup or the last is more than a
+day old. `gea help backup`.
 
 ## The standalone install kit
 

{gea_program-0.17.0 → gea_program-0.18.0}/README.md

@@ -86,7 +86,7 @@ gea dashboard --catalog-well volve_f12_f14_production_excerpt:15/9-F-12:10000 --
 gea client-report --report accuracy --out client_report
 gea model-cards --out model_cards
 gea sbom --out sbom
-gea accept                     # the product gate (340 checks)
+gea accept                     # the product gate (342 checks)
 gea help drift                 # the help library, by the job (16 pages; the same text is on every dashboard page)
 gea guide                      # the click-by-click tester guide (docs/TESTER_GUIDE.md)
 gea gui                        # the desktop window (pip install "gea-program[desktop]")
@@ -683,6 +683,14 @@ headers on every response, and `gea housekeeping --workspace C:\site --apply`
 than truncating them and prunes finished job folders and old recordings. `gea
 loadtest --patches 16 --seconds 60 --with-service` tells you whether the site
 machine carries the patches it will be given, with the page still answering.
+`gea backup --workspace C:\site --out D:\gea-backups --keep 14` copies the
+whole site into one dated archive with a manifest of every file's hash, onto
+another disk or a share; schedule it daily from Audit / Update, verify an
+archive with `--verify`, and restore one onto an empty folder with
+`--restore ... --to` and open it once before the first well is live - the
+records are the product, and a backup nobody has restored is a hope. The
+doctor warns when there has never been a backup or the last is more than a
+day old. `gea help backup`.
 
 ## The standalone install kit
 

{gea_program-0.17.0 → gea_program-0.18.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.17.0 → gea_program-0.18.0}/gea/__main__.py

@@ -411,6 +411,16 @@ def main(argv=None) -> int:
     p_es.add_argument("--frames", type=int, default=600)
     p_es.add_argument("--interval", type=float, default=1.0, help="seconds between samples")
     p_es.add_argument("--seed", type=int, default=1)
+    p_bk = sub.add_parser("backup", help="the site copied off the machine: one dated archive with a manifest; --verify an archive; --restore one onto an empty folder; --status")
+    p_bk.add_argument("--workspace", type=str, default=None, help="the site folder (for a backup, or --status)")
+    p_bk.add_argument("--out", type=str, default=None, help="the folder the archive goes to - another disk or a share, never inside the workspace")
+    p_bk.add_argument("--keep", type=int, default=None, help="keep only the newest N archives of this site in --out")
+    p_bk.add_argument("--label", type=str, default="", help="a note carried in the manifest (e.g. 'before the gauge swap')")
+    p_bk.add_argument("--verify", type=str, default=None, help="check this archive against its manifest and its .sha256")
+    p_bk.add_argument("--restore", type=str, default=None, help="restore this archive ...")
+    p_bk.add_argument("--to", type=str, default=None, help="... onto this empty folder")
+    p_bk.add_argument("--status", action="store_true", help="when the last backup of --workspace was taken, and whether that is too long ago")
+    p_bk.add_argument("--actor", type=str, default="cli")
     p_sl = sub.add_parser("seedlink", help="the seismic leg's live port: a SeedLink (3 / 4.0) station's records as it writes them, byte for byte into day files; --selftest against the simulator")
     p_sl.add_argument("--config", type=str, default=None, help="the SeedLink config JSON (host, port, streams)")
     p_sl.add_argument("--write-example-config", type=str, default=None, help="write an example config here and exit")
@@ -2017,6 +2027,24 @@ def main(argv=None) -> int:
             stop.set()
             print("wits0-sim: stopped")
         return 0
+    elif a.cmd == "backup":
+        from . import backup as _B
+        try:
+            if a.verify:
+                r = _B.verify(a.verify); print(_B.report_text(r, "verify")); return 0 if r["status"] == "OK" else 1
+            if a.restore:
+                if not a.to:
+                    raise SystemExit("backup --restore needs --to <empty folder>")
+                print(_B.report_text(_B.restore(a.restore, a.to, a.actor), "restore")); return 0
+            if not a.workspace:
+                raise SystemExit("backup needs --workspace <site folder> (with --out <another disk>), or --verify / --restore an archive")
+            if a.status:
+                r = _B.status(a.workspace); print(_B.report_text(r, "status")); return 0 if not (r["never"] or r["stale"]) else 1
+            if not a.out:
+                raise SystemExit("backup needs --out <a folder on another disk or a share>")
+            print(_B.report_text(_B.make(a.workspace, a.out, a.actor, keep=a.keep, label=a.label), "make")); return 0
+        except (ValueError, OSError) as e:
+            raise SystemExit(f"backup: {e}")
     elif a.cmd == "seedlink":
         import json as _json
         from . import seedlink as _L

{gea_program-0.17.0 → gea_program-0.18.0}/gea/acceptance_tests.py

@@ -5719,6 +5719,159 @@ def section_bk_seedlink(tmp: str) -> None:
        "names the simulator to start; the help page says a gap is counted, never bridged"
        + (f" [failed: {', '.join(failed)}; row={json.dumps({k: row.get(k) for k in ('status', 'protocol', 'records', 'latency_p95_s', 'last_error')})}]" if failed else ""))
 
+
+def section_bl_backup(tmp: str) -> None:
+    """Section BL - the site copied off the machine: the archive and its manifest, verify, a tampered archive named,
+    restore onto an empty folder and the workspace that comes back, the refusals, the doctor's line, the page's
+    card, the job and the daily schedule."""
+    import http.cookiejar
+    import subprocess as _sp
+    import urllib.request
+    import urllib.error
+    import zipfile
+    from . import backup as B
+    from . import doctor as D
+    from . import helplib as H
+    from .telemetry import TelemetryRecorder, TelemetryConfig
+    from .downhole_engine import DownholeEngine, SimulatorConfig
+    from .workspace import Workspace
+    from .service import Service, Users
+    pkg = Path(__file__).parent
+    d = Path(tmp, "bl"); d.mkdir()
+    hist = str(d / "hist.csv")
+    TelemetryRecorder(engine=DownholeEngine(SimulatorConfig()), config=TelemetryConfig(duration_hours=0.5, seed=5)).run().export_csv(hist)
+    wsp = str(d / "ws"); ws = Workspace.create(wsp, "Pad 3", actor="tester")
+    w = ws.add_well_file(hist, display="SWD 1", actor="tester")
+    users = Users(str(Path(wsp, "users.json"))); users.add("op", "operator-pass-1", "operator"); users.add("adm", "admin-pass-1", "admin")
+    (Path(wsp) / "jobs" / "run-0001").mkdir(parents=True); (Path(wsp) / "jobs" / "run-0001" / "log.txt").write_text("a finished run")
+    (Path(wsp) / "jobs" / "_uploads").mkdir(); (Path(wsp) / "jobs" / "_uploads" / "x.bin").write_bytes(b"scratch")
+    (Path(wsp) / "jobs" / "schedule.json").write_text(json.dumps({"entries": []}))
+
+    # -- make, verify, status, restore; the refusals; the pruning ---------------------------------------------------
+    never = B.status(wsp)
+    out = str(d / "off-disk")
+    r1 = B.make(wsp, out, "tester", keep=2, label="first")
+    v1 = B.verify(r1["path"])
+    side1 = os.path.isfile(r1["path"] + ".sha256")           # before the later --keep prunes this first archive and its hash file
+    st1 = B.status(wsp)
+    with zipfile.ZipFile(r1["path"]) as z:
+        names = z.namelist(); man = json.loads(z.read("MANIFEST.json"))
+    inside_refused = None
+    try:
+        B.make(wsp, os.path.join(wsp, "records", "bk"), "tester")
+    except ValueError as e:
+        inside_refused = str(e)
+    rr = B.restore(r1["path"], str(d / "restored"), "tester")
+    ws2 = Workspace(str(d / "restored"))
+    nonempty_refused = None
+    try:
+        B.restore(r1["path"], str(d / "restored"), "tester")
+    except ValueError as e:
+        nonempty_refused = str(e)
+    # tamper: rewrite one member in a copy; verify names it and restore refuses it
+    bad = str(d / "tampered.zip")
+    with zipfile.ZipFile(r1["path"]) as zin, zipfile.ZipFile(bad, "w") as zout:
+        for info in zin.infolist():
+            data = zin.read(info.filename)
+            if info.filename == "workspace.json":
+                data = data.replace(b"Pad 3", b"Pad 4")
+            zout.writestr(info, data)
+    vbad = B.verify(bad)
+    tampered_refused = None
+    try:
+        B.restore(bad, str(d / "restored2"), "tester")
+    except ValueError as e:
+        tampered_refused = str(e)
+    r2 = B.make(wsp, out, "tester", keep=2); r3 = B.make(wsp, out, "tester", keep=2)
+    left = sorted(n for n in os.listdir(out) if n.endswith(".zip"))
+    rec_files = [n for n in names if n.startswith(f"wells/{w['id']}/")]
+    c1 = {
+        "never_then_current": never["never"] and never["stale"] and st1["never"] is False and st1["stale"] is False and st1["present"] is True and st1["count"] == 1,
+        "manifest": r1["n_files"] == man["n_files"] and man["protocol"] == "gea.backup/1" and man["site"] == "Pad 3" and man["wells"] == [w["id"]] and man["users_json"] is True,
+        "members": "users.json" in names and "records/audit.jsonl" in names and "workspace.json" in names and "jobs/schedule.json" in names and bool(rec_files)
+                   and not any(n.startswith("jobs/run-") or "_uploads" in n for n in names),
+        "verify_ok": v1["status"] == "OK" and v1["n_files"] == r1["n_files"] and v1["archive_sha256_matches"] is True and side1,
+        "inside_refused": bool(inside_refused) and "inside the workspace" in inside_refused,
+        "restored_site": rr["site"] == "Pad 3" and rr["wells"] == [w["id"]] and rr["users_json"] is True and ws2.manifest["name"] == "Pad 3" and ws2.wells()[0]["id"] == w["id"],
+        "restored_note_audit": os.path.isfile(d / "restored" / "restored_from.json") and any(a["action"] == "backup.restore" for a in ws2.audit_log()),
+        "restored_accounts": Users(str(d / "restored" / "users.json")).check("op", "operator-pass-1") is not None,
+        "nonempty_refused": bool(nonempty_refused) and "empty folder" in nonempty_refused,
+        "tampered": vbad["status"] == "FAIL" and vbad["mismatched"] == ["workspace.json"] and bool(tampered_refused) and "does not verify" in tampered_refused,
+        "pruned": len(left) == 2 and os.path.basename(r3["path"]) in left and os.path.basename(r1["path"]) not in left and r3["pruned"] == [os.path.basename(r1["path"])],
+        "audited": any(a["action"] == "backup.make" for a in ws.audit_log()),
+    }
+    failed1 = [k for k, v in c1.items() if not v]
+    ok(not failed1,
+       "BL1 the site copied off the machine: one dated archive carrying every well's source and records, users.json, the audit log, the manifest "
+       "and the schedule - never the job run folders or the upload scratch - with MANIFEST.json (site, version, every file's SHA-256) inside and the "
+       "archive's own hash beside it; verify reads OK; status turns from NEVER to current; a folder inside the workspace is refused; the archive "
+       "restored onto an empty folder opens as the same site with the same well, the same accounts and a restored_from note, and a second restore "
+       "onto it is refused; a tampered archive fails verify naming the file and is refused by restore; --keep prunes the oldest; both in the audit"
+       + (f" [failed: {', '.join(failed1)}]" if failed1 else ""))
+
+    # -- the doctor, the service, the page, the CLI ------------------------------------------------------------------
+    wsp2 = str(d / "ws2"); ws3 = Workspace.create(wsp2, "Pad 3", actor="tester")
+    users3 = Users(str(Path(wsp2, "users.json"))); users3.add("adm", "admin-pass-1", "admin"); users3.add("op", "operator-pass-1", "operator")
+    f_never = [x for x in D.check_workspace(wsp2, port=0) if "backup" in x["what"]]
+    svc = Service(wsp2, port=0, scheduler=False).start()
+    base = svc.url.rstrip("/")
+    opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+
+    def call(method, path, body=None):
+        req = urllib.request.Request(base + path, method=method, data=(json.dumps(body).encode() if body is not None else None))
+        req.add_header("Content-Type", "application/json"); req.add_header("X-GEA-Action", "1")
+        try:
+            with opener.open(req, timeout=120) as rr_:
+                return rr_.status, json.loads(rr_.read())
+        except urllib.error.HTTPError as e:
+            return e.code, json.loads(e.read())
+    try:
+        call("POST", "/api/login", {"name": "op", "password": "operator-pass-1"})
+        st_op = call("GET", "/api/backup")[0]
+        call("POST", "/api/login", {"name": "adm", "password": "admin-pass-1"})
+        st_v0, v0 = call("GET", "/api/backup")
+        st_run0 = call("POST", "/api/backup/run", {})[0]
+        st_in = call("POST", "/api/backup/config", {"out_dir": os.path.join(wsp2, "records", "bk")})[0]
+        st_bad_t = call("POST", "/api/backup/config", {"out_dir": str(d / "off2"), "daily_at": "2:30"})[0]
+        st_cfg, cfg = call("POST", "/api/backup/config", {"out_dir": str(d / "off2"), "keep": 7, "daily_at": "02:30"})
+        st_run, job = call("POST", "/api/backup/run", {})
+        done = svc.app.runner.wait(job["id"], 120)
+        st_v1, v1s = call("GET", "/api/backup")
+        st_sch, sch = call("POST", "/api/backup/schedule", {})
+        st_v2, v2s = call("GET", "/api/backup")
+    finally:
+        svc.stop()
+    f_after = [x for x in D.check_workspace(wsp2, port=0) if "backup" in x["what"]]
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    help_md = (pkg / "help" / "backup.md").read_text(encoding="utf-8")
+    r_st0 = _sp.run([sys.executable, "-m", "gea", "backup", "--workspace", str(d / "ws3-none"), "--status"], capture_output=True, text=True)
+    r_st = _sp.run([sys.executable, "-m", "gea", "backup", "--workspace", wsp2, "--status"], capture_output=True, text=True)
+    r_v = _sp.run([sys.executable, "-m", "gea", "backup", "--verify", v1s["status"]["last"]["path"]], capture_output=True, text=True)
+    r_vbad = _sp.run([sys.executable, "-m", "gea", "backup", "--verify", bad], capture_output=True, text=True)
+    r_rs = _sp.run([sys.executable, "-m", "gea", "backup", "--restore", v1s["status"]["last"]["path"], "--to", str(d / "restored3")], capture_output=True, text=True)
+    c2 = {
+        "doctor_never": len(f_never) == 1 and f_never[0]["level"] == "warn" and "no backup has ever been taken" in f_never[0]["what"] and "gea backup" in f_never[0]["fix"],
+        "api_admin_only_and_empty": st_op == 403 and st_v0 == 200 and v0["status"]["never"] is True and v0["schedule"] is None and v0["config"]["out_dir"] == "",
+        "config_refusals": st_run0 == 400 and st_in == 400 and st_bad_t == 400 and st_cfg == 200 and cfg["keep"] == 7,
+        "job_ran": st_run == 200 and done["status"] == "DONE" and st_v1 == 200 and v1s["status"]["never"] is False and v1s["status"]["present"] is True
+                   and os.path.isfile(v1s["status"]["last"]["path"]) and v1s["status"]["last"]["actor"] == "adm",
+        "scheduled": st_sch == 200 and sch["name"] == "backup-daily" and sch["daily_at"] == "02:30" and sch["args"][0] == "backup" and "--keep" in sch["args"]
+                     and v2s["schedule"] is not None and v2s["schedule"]["name"] == "backup-daily",
+        "doctor_after": len(f_after) == 1 and f_after[0]["level"] == "ok" and "last backup" in f_after[0]["what"],
+        "page": "The backup" in page_src and "/api/backup/run" in page_src and "/api/backup/schedule" in page_src,
+        "cli_status": r_st0.returncode == 1 and "NEVER" in r_st0.stdout and r_st.returncode == 0 and "current" in r_st.stdout,
+        "cli_verify": r_v.returncode == 0 and "OK" in r_v.stdout and r_vbad.returncode == 1 and "workspace.json" in r_vbad.stdout,
+        "cli_restore": r_rs.returncode == 0 and "users.json present" in r_rs.stdout,
+        "help": any(t["topic"] == "backup" for t in H.topics()) and not H.check("backup") and "never restored" in help_md.split("will not call a measurement")[1],
+    }
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       "BL2 the doctor warns NEVER until a backup exists and says when the last one was afterwards; the Audit / Update page's backup card (admin only) "
+       "refuses a folder inside the workspace and a malformed hour, saves the folder and the keep count, runs the backup as a job that the status then "
+       "shows with its actor, and schedules it daily as the `backup-daily` entry; `gea backup --status` exits 1 on NEVER and 0 when current, "
+       "`--verify` says OK or names the tampered file, `--restore` brings the accounts back; the help page says a backup never restored is a hope"
+       + (f" [failed: {', '.join(failed2)}; r_st0={r_st0.stdout[-120:]!r} {r_st0.stderr[-120:]!r}]" if failed2 else ""))
+
 def main() -> int:
     print("GEA-Program - ACCEPTANCE SUITE (the product gate)")
     # a handle a job subprocess still holds at the end must not turn a finished gate into a traceback on Windows:
@@ -5785,6 +5938,7 @@ def main() -> int:
         section_bi_conformance(tmp)
         section_bj_etp(tmp)
         section_bk_seedlink(tmp)
+        section_bl_backup(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

gea_program-0.18.0/gea/backup.py

@@ -0,0 +1,262 @@
+"""backup - the site, copied off the machine, and proven to come back.
+
+The records are the product. Nothing in housekeeping, the workspace or the service copied the site anywhere;
+the doctor told a person to restore users.json "from a backup" that no command wrote. This module writes it.
+
+`make` zips the workspace - every well's source and records, the seismic stations with their source and live
+day files, the configuration store, the monitor, the reports, users.json, the audit log, the patches, the
+schedule - into one dated archive in a folder that should be on another disk or a share, with a manifest
+(program version, site name, every file's SHA-256 and size) and the manifest's own hash beside it. The job
+folders of finished runs and the upload scratch are left out: they are reproducible, and they are what grows.
+`verify` opens an archive and checks every file against its manifest. `restore` extracts one into an empty
+folder, verifies, opens it as a workspace and says what came back - a backup nobody has restored is a hope.
+`status` says when the last backup was taken and whether that is too long ago; the doctor prints it.
+
+What it will not do: back up into the workspace itself (refused - a lost disk loses both); restore over a
+folder that has anything in it; call an archive good whose manifest does not match its files.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import time
+import zipfile
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+STALE_AFTER_H = 26.0                      # a daily backup that is more than a day and change old
+EXCLUDE_TOP = ('jobs',)                   # taken selectively: schedule.json only
+EXCLUDE_NAMES = ('_uploads', '__pycache__')
+LOG_NAME = 'backups.jsonl'                # records/backups.jsonl: one line per backup taken from this workspace
+
+
+def _utc() -> str:
+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+
+def _sha256(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, 'rb') as f:
+        for chunk in iter(lambda: f.read(1 << 20), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _sha256_bytes(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def _inside(child: str, parent: str) -> bool:
+    c, p = os.path.realpath(child), os.path.realpath(parent)
+    return c == p or c.startswith(p + os.sep)
+
+
+def site_files(workspace_path: str) -> List[str]:
+    """The relative paths a backup carries, sorted: everything but the job run folders and the upload scratch."""
+    out: List[str] = []
+    for root, dirs, files in os.walk(workspace_path):
+        rel_root = os.path.relpath(root, workspace_path)
+        top = rel_root.split(os.sep)[0] if rel_root != '.' else ''
+        dirs[:] = sorted(d for d in dirs if d not in EXCLUDE_NAMES and not (rel_root == '.' and d in EXCLUDE_TOP))
+        for name in sorted(files):
+            if name.endswith(('.tmp', '.lock')) or name in EXCLUDE_NAMES:
+                continue
+            rel = os.path.normpath(os.path.join(rel_root, name)) if rel_root != '.' else name
+            out.append(rel.replace(os.sep, '/'))
+    # the schedule is the one thing under jobs/ worth carrying: it is what a person set, not what a run left
+    sched = os.path.join(workspace_path, 'jobs', 'schedule.json')
+    if os.path.isfile(sched):
+        out.append('jobs/schedule.json')
+    return sorted(set(out))
+
+
+def make(workspace_path: str, out_dir: str, actor: str = 'backup', keep: Optional[int] = None, label: str = '') -> dict:
+    """Write `gea-site-<slug>-<UTC>.zip` into out_dir with MANIFEST.json inside and <zip>.sha256 beside it; prune to
+    the newest `keep` archives of this site when asked; log the backup in records/backups.jsonl and the audit."""
+    from . import __version__
+    from .workspace import Workspace
+    ws = Workspace(workspace_path)
+    if _inside(out_dir, ws.path):
+        raise ValueError(f'the backup folder {out_dir} is inside the workspace - a lost disk would lose both; use another disk or a share')
+    os.makedirs(out_dir, exist_ok=True)
+    slug = ''.join(c if c.isalnum() or c in '-_' else '-' for c in ws.manifest['name']).strip('-') or 'site'
+    stamp = datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')
+    name = f'gea-site-{slug}-{stamp}.zip'
+    k = 2
+    while os.path.exists(os.path.join(out_dir, name)):      # two in one second: the second is numbered, never overwrites
+        name = f'gea-site-{slug}-{stamp}-{k}.zip'; k += 1
+    path = os.path.join(out_dir, name)
+    files = site_files(ws.path)
+    entries: Dict[str, dict] = {}
+    total = 0
+    t0 = time.time()
+    with zipfile.ZipFile(path + '.part', 'w', compression=zipfile.ZIP_DEFLATED, compresslevel=6) as z:
+        for rel in files:
+            src = os.path.join(ws.path, *rel.split('/'))
+            try:
+                data = open(src, 'rb').read()
+            except OSError as e:                              # a file that vanished between the walk and the read (a rotated log)
+                entries[rel] = {'skipped': str(e)}
+                continue
+            z.writestr(zipfile.ZipInfo.from_file(src, arcname=rel), data)
+            entries[rel] = {'sha256': _sha256_bytes(data), 'bytes': len(data)}
+            total += len(data)
+        manifest = {'protocol': 'gea.backup/1', 'program_version': __version__, 'site': ws.manifest['name'], 'workspace': ws.path,
+                    'generated_utc': _utc(), 'actor': actor, 'label': label, 'files': entries,
+                    'n_files': sum(1 for v in entries.values() if 'sha256' in v), 'bytes': total,
+                    'excluded': ['jobs/<run folders>', 'jobs/_uploads', '*.tmp', '*.lock'],
+                    'wells': list(ws.manifest.get('wells', [])), 'seismic': list(ws.manifest.get('seismic', [])),
+                    'users_json': 'users.json' in entries}
+        z.writestr('MANIFEST.json', json.dumps(manifest, indent=1))
+    os.replace(path + '.part', path)
+    digest = _sha256(path)
+    with open(path + '.sha256', 'w', encoding='utf-8') as f:
+        f.write(f'{digest}  {name}\n')
+    pruned = []
+    if keep is not None and keep > 0:
+        def _order(n: str):                                  # by the stamp, then the same-second number: a lexical sort puts '-2' before '.zip'
+            m = re.match(rf'gea-site-{re.escape(slug)}-(\d{{8}}T\d{{6}}Z)(?:-(\d+))?\.zip$', n)
+            return (m.group(1), int(m.group(2) or 1)) if m else ('', 0)
+        mine = sorted((n for n in os.listdir(out_dir) if n.startswith(f'gea-site-{slug}-') and n.endswith('.zip')), key=_order)
+        for old in mine[:-keep]:
+            for p in (os.path.join(out_dir, old), os.path.join(out_dir, old + '.sha256')):
+                if os.path.isfile(p):
+                    os.remove(p)
+            pruned.append(old)
+    rec = {'utc': manifest['generated_utc'], 'path': path, 'sha256': digest, 'bytes_archive': os.path.getsize(path), 'bytes_files': total,
+           'n_files': manifest['n_files'], 'seconds': round(time.time() - t0, 2), 'pruned': pruned, 'actor': actor, 'program_version': __version__}
+    with open(os.path.join(ws.dir('records'), LOG_NAME), 'a', encoding='utf-8') as f:
+        f.write(json.dumps(rec) + '\n')
+    ws.audit(actor, 'backup.make', {'path': path, 'n_files': manifest['n_files'], 'bytes': total, 'sha256': digest, 'pruned': pruned})
+    return rec
+
+
+def verify(zip_path: str) -> dict:
+    """Every file in the archive against MANIFEST.json, the archive against its .sha256 when that is beside it."""
+    out = {'path': zip_path, 'status': 'OK', 'n_files': 0, 'mismatched': [], 'missing': [], 'extra': [], 'archive_sha256': None, 'archive_sha256_matches': None,
+           'manifest': None}
+    if not os.path.isfile(zip_path):
+        out.update({'status': 'FAIL', 'error': 'no such file'})
+        return out
+    try:
+        with zipfile.ZipFile(zip_path) as z:
+            bad = z.testzip()
+            if bad is not None:
+                out.update({'status': 'FAIL', 'error': f'corrupt member {bad}'})
+                return out
+            if 'MANIFEST.json' not in z.namelist():
+                out.update({'status': 'FAIL', 'error': 'no MANIFEST.json - not a gea backup'})
+                return out
+            man = json.loads(z.read('MANIFEST.json'))
+            out['manifest'] = {k: man.get(k) for k in ('protocol', 'program_version', 'site', 'generated_utc', 'n_files', 'bytes', 'wells', 'seismic', 'users_json')}
+            names = set(n for n in z.namelist() if n != 'MANIFEST.json' and not n.endswith('/'))
+            for rel, meta in man['files'].items():
+                if 'sha256' not in meta:
+                    continue
+                if rel not in names:
+                    out['missing'].append(rel)
+                    continue
+                if _sha256_bytes(z.read(rel)) != meta['sha256']:
+                    out['mismatched'].append(rel)
+                out['n_files'] += 1
+            out['extra'] = sorted(names - set(man['files']))
+    except (zipfile.BadZipFile, KeyError, ValueError) as e:
+        out.update({'status': 'FAIL', 'error': f'unreadable archive: {e}'})
+        return out
+    side = zip_path + '.sha256'
+    out['archive_sha256'] = _sha256(zip_path)
+    if os.path.isfile(side):
+        with open(side, encoding='utf-8') as f:
+            out['archive_sha256_matches'] = f.read().split()[0] == out['archive_sha256']
+    if out['mismatched'] or out['missing'] or out['extra'] or out['archive_sha256_matches'] is False:
+        out['status'] = 'FAIL'
+    return out
+
+
+def restore(zip_path: str, target: str, actor: str = 'restore') -> dict:
+    """Into an empty (or absent) folder only; verified first; opened as a workspace afterwards and described."""
+    from .workspace import Workspace
+    v = verify(zip_path)
+    if v['status'] != 'OK':
+        raise ValueError(f"the archive does not verify: {v.get('error') or (v['mismatched'] + v['missing'] + v['extra'])}")
+    if os.path.exists(target) and (not os.path.isdir(target) or os.listdir(target)):
+        raise ValueError(f'the restore target must be an empty folder: {target}')
+    os.makedirs(target, exist_ok=True)
+    with zipfile.ZipFile(zip_path) as z:
+        for info in z.infolist():
+            if info.filename == 'MANIFEST.json' or info.filename.endswith('/'):
+                continue
+            rel = os.path.normpath(info.filename)
+            if rel.startswith('..') or os.path.isabs(rel):
+                raise ValueError(f'refusing a path outside the target: {info.filename}')
+            dst = os.path.join(target, rel)
+            os.makedirs(os.path.dirname(dst), exist_ok=True)
+            with z.open(info) as src, open(dst, 'wb') as out:
+                shutil.copyfileobj(src, out)
+        man = json.loads(z.read('MANIFEST.json'))
+    back = [rel for rel, meta in man['files'].items() if 'sha256' in meta and _sha256(os.path.join(target, *rel.split('/'))) != meta['sha256']]
+    if back:
+        raise ValueError(f'{len(back)} file(s) differ after extraction: {back[:5]}')
+    ws = Workspace(target)
+    note = {'protocol': 'gea.restore/1', 'restored_utc': _utc(), 'from': zip_path, 'archive_sha256': v['archive_sha256'], 'backup_generated_utc': man['generated_utc'],
+            'backup_program_version': man['program_version'], 'actor': actor}
+    with open(os.path.join(target, 'restored_from.json'), 'w', encoding='utf-8') as f:
+        json.dump(note, f, indent=1)
+    ws.audit(actor, 'backup.restore', {'from': zip_path, 'archive_sha256': v['archive_sha256'], 'n_files': v['n_files']})
+    s = ws.summary()
+    return {'target': target, 'site': ws.manifest['name'], 'n_files': v['n_files'], 'wells': list(ws.manifest.get('wells', [])), 'seismic': list(ws.manifest.get('seismic', [])),
+            'users_json': os.path.isfile(os.path.join(target, 'users.json')), 'backup_generated_utc': man['generated_utc'], 'summary': s}
+
+
+def status(workspace_path: str, stale_after_h: float = STALE_AFTER_H) -> dict:
+    """The last backup logged from this workspace, its age, whether it is still where the log says, and the verdict."""
+    p = os.path.join(workspace_path, 'records', LOG_NAME)
+    out = {'last': None, 'age_h': None, 'stale': True, 'never': True, 'present': None, 'count': 0, 'stale_after_h': stale_after_h}
+    if not os.path.isfile(p):
+        return out
+    last = None
+    n = 0
+    with open(p, encoding='utf-8') as f:
+        for line in f:
+            if line.strip():
+                try:
+                    last = json.loads(line); n += 1
+                except ValueError:
+                    continue
+    out['count'] = n
+    if last is None:
+        return out
+    t = datetime.strptime(last['utc'], '%Y-%m-%dT%H:%M:%SZ').replace(tzinfo=timezone.utc)
+    age_h = (datetime.now(timezone.utc) - t).total_seconds() / 3600.0
+    out.update({'last': last, 'age_h': round(age_h, 2), 'stale': age_h > stale_after_h, 'never': False, 'present': os.path.isfile(last['path'])})
+    return out
+
+
+def report_text(r: dict, kind: str) -> str:
+    if kind == 'make':
+        return (f"backup: {r['path']}\n  {r['n_files']} files, {r['bytes_files'] / 1048576:.1f} MB of site in a {r['bytes_archive'] / 1048576:.1f} MB archive, "
+                f"sha256 {r['sha256'][:16]}..., {r['seconds']} s" + (f"\n  pruned: {', '.join(r['pruned'])}" if r['pruned'] else '')
+                + "\n  verify it once with --verify, and restore it once onto an empty folder before trusting it")
+    if kind == 'verify':
+        m = r.get('manifest') or {}
+        head = f"verify: {r['path']} - {r['status']}"
+        if r.get('error'):
+            return head + f"\n  {r['error']}"
+        return (head + f"\n  site {m.get('site')!r}, taken {m.get('generated_utc')} by gea-program {m.get('program_version')}: {r['n_files']} files checked"
+                + (f", archive hash {'matches' if r['archive_sha256_matches'] else 'DOES NOT MATCH'} its .sha256" if r['archive_sha256_matches'] is not None else ', no .sha256 beside it')
+                + (f"\n  mismatched: {r['mismatched']}" if r['mismatched'] else '') + (f"\n  missing: {r['missing']}" if r['missing'] else '')
+                + (f"\n  extra: {r['extra']}" if r['extra'] else ''))
+    if kind == 'restore':
+        return (f"restored: {r['target']}\n  site {r['site']!r} from the backup of {r['backup_generated_utc']}: {r['n_files']} files, "
+                f"{len(r['wells'])} well(s) {r['wells']}, {len(r['seismic'])} station(s), users.json {'present' if r['users_json'] else 'ABSENT'}"
+                "\n  open it: gea serve --workspace <that folder> --port 8766, and look before you trust the copy")
+    if kind == 'status':
+        if r['never']:
+            return 'backup: NEVER - no backup has been taken from this workspace (gea backup --workspace ... --out <another disk>)'
+        l = r['last']
+        return (f"backup: last {l['utc']} ({r['age_h']} h ago) -> {l['path']} ({'present' if r['present'] else 'NOT FOUND where the log says'}); "
+                f"{r['count']} on record; {'STALE' if r['stale'] else 'current'} (stale after {r['stale_after_h']:g} h)")
+    return json.dumps(r, indent=1)

{gea_program-0.17.0 → gea_program-0.18.0}/gea/doctor.py

@@ -225,8 +225,23 @@ def check_workspace(path: str, host: str = '127.0.0.1', port: int = 8765) -> Lis
         try:
             n_users = len(json.load(open(users, encoding='utf-8')).get('users', []))
         except (OSError, json.JSONDecodeError):
-            f.append(_finding('block', 'users.json is not valid JSON', 'restore it from a backup, or move it aside to start with a fresh administrator'))
+            f.append(_finding('block', 'users.json is not valid JSON', 'restore it from a backup (gea backup --restore <archive> --to <empty folder>), or move it aside to start with a fresh administrator'))
     f.append(_finding('info', f'{n_users} account(s)' + ('' if n_users else ' - the first visit to the page creates the administrator')))
+    try:
+        from . import backup as BK
+        bs = BK.status(ws.path)
+        if bs['never']:
+            f.append(_finding('warn', 'no backup has ever been taken from this workspace - a lost disk is a lost month, and the records are the product',
+                              'gea backup --workspace <this> --out <a folder on another disk or a share>; then schedule it daily on the Audit / Update page'))
+        elif bs['stale']:
+            f.append(_finding('warn', f"the last backup is {bs['age_h']:.0f} h old ({bs['last']['utc']}); daily means under {bs['stale_after_h']:g} h",
+                              'run the backup, and check the daily schedule entry is enabled'))
+        elif bs['present'] is False:
+            f.append(_finding('warn', f"the last backup ({bs['last']['utc']}) is not where the log says: {bs['last']['path']}", 'the backup disk or share is not mounted, or the file was moved'))
+        else:
+            f.append(_finding('ok', f"last backup {bs['last']['utc']} ({bs['age_h']:.1f} h ago), present at {bs['last']['path']}"))
+    except Exception as e:
+        f.append(_finding('warn', f'backup status could not be read: {e}'))
     try:
         from .patches import PatchStore
         ps = PatchStore(ws).list()

gea_program-0.18.0/gea/help/backup.md

@@ -0,0 +1,11 @@
+# The backup
+
+> The records are the product. A lost disk is a lost month unless the site is copied off the machine every day - and a copy nobody has restored is a hope, not a backup. This page is the command that copies, the one that checks, and the one that brings it back.
+
+**The command**: `gea backup --workspace C:\site --out D:\gea-backups --keep 14` writes one dated archive, `gea-site-<name>-<UTC>.zip`, into a folder that must be on another disk or a share (a folder inside the workspace is refused). On the dashboard, Audit / Update -> The backup: set the folder, Back up now (a job), Schedule daily (a schedule entry, `backup-daily`, at the hour given, UTC). `gea backup --verify <archive>` checks every file in it against its manifest and the archive against its `.sha256`. `gea backup --restore <archive> --to C:\site-restored` extracts onto an empty folder, verifies every file again, opens the result as a workspace and says what came back; then `gea serve --workspace C:\site-restored --port 8766` and look. `gea backup --workspace C:\site --status` prints when the last one was taken; the doctor prints the same line and warns when there has never been one or the last is more than 26 hours old.
+
+**What it writes**: the whole site - every well's source files and records, every seismic station's source and live day files, `config/`, `monitor/`, `reports/`, `users.json`, `records/` (the audit log, the notifications, the patches, the certificates, the swaps), `workspace.json` and `jobs/schedule.json` - with `MANIFEST.json` inside (the program version, the site name, the time, every file's SHA-256 and size, the wells and stations by id) and `<archive>.sha256` beside it. Left out: the job run folders and the upload scratch, which are reproducible and are what grows. Each backup is logged in `records/backups.jsonl` and in the audit log (`backup.make`); a restore writes `restored_from.json` in the restored folder and `backup.restore` in its audit log. `--keep N` prunes the older archives of this site in that folder.
+
+**The number to check**: on the card and in the doctor, `current` with the hours since the last backup, or `NEVER` / `STALE`; on `--verify`, `OK` with the file count and "archive hash matches"; on `--restore`, the well and station counts and `users.json present`.
+
+**What this page will not call a measurement**: a backup that was never restored - run the restore once onto an empty folder and open the page. An archive whose manifest does not match its files - `--verify` says FAIL and names them, and `--restore` refuses it. A copy on the same disk - the folder inside the workspace is refused; a second folder on the same drive is not refused, and is not a backup either. The job run folders - they are not in the archive, by design.

{gea_program-0.17.0 → gea_program-0.18.0}/gea/helplib.py

@@ -46,6 +46,7 @@ INDEX: List[tuple] = [
     ('conformance', 'Conformity, in the standards\' words', 'certificates against ISO/IEC 17025 7.8 and the bias against its class under a named ILAC-G8 decision rule'),
     ('etp', 'WITSML 2.x over ETP', 'the live port on Energistics ETP v1.2: subscribe to the store\'s channels and it pushes'),
     ('seedlink', 'Live stations (SeedLink)', 'the seismic leg\'s live port: a station\'s records as it writes them, resumed by sequence number, folded into its record list'),
+    ('backup', 'The backup', 'the site copied off the machine, verified, and restored once before it is trusted'),
     ('doctor', 'Which code is running', 'gea doctor and the serve start-up gate'),
     ('audit-update', 'Audit / Update', 'the whole audit log with filters, the program against PyPI, every report against its source'),
     ('upkeep', 'Upkeep', 'housekeeping, sessions, the TLS proxy, the load test'),