pingerplot 1.6.0__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.
pingerplot/updater.py ADDED
@@ -0,0 +1,499 @@
1
+ """In-app updates: a signed release manifest, a verified download, an install.
2
+
3
+ Each release carries ``latest.json``:
4
+
5
+ {"payload": base64(JSON), "signature": base64(Ed25519 over the payload)}
6
+
7
+ payload = {"app": "pingerplot", "version": "1.4.0", "published": "...",
8
+ "installer": {"file": "PingerPlot-Setup.exe", "size": N, "sha256": "..."},
9
+ "portable": {"file": "PingerPlot-win64.zip", "size": N, "sha256": "..."}}
10
+
11
+ The app checks the signature against the public key built into it
12
+ (update_key.py), and only then trusts the sizes and hashes; a download that
13
+ doesn't match them is deleted. Nothing is downloaded without a click.
14
+
15
+ Installed copies (Setup.exe; Inno Setup's unins000.exe beside the program) run
16
+ the new installer silently, which waits for this copy to exit and starts the
17
+ new one. Portable copies unzip the new version to a temporary folder and start
18
+ *that* copy with --finish-update: it waits for this one to exit, swaps the
19
+ program files in place (never settings.json beside them), and starts the
20
+ updated app. If the swap fails, everything is put back and the old version is
21
+ started again. Running from source, it only says what's new.
22
+
23
+ What this reads from a release can never change, as every installed copy
24
+ reads it: the asset names, the manifest's shape, the tag ``vX.Y.Z``. It never
25
+ goes back a version, so a bad release is fixed by publishing a higher one.
26
+
27
+ Adapted from UniFi Stock Watcher (same author, same scheme), with urllib in
28
+ place of requests: PingerPlot has no third-party dependencies.
29
+ """
30
+ from __future__ import annotations
31
+
32
+ import base64
33
+ import hashlib
34
+ import json
35
+ import logging
36
+ import os
37
+ import re
38
+ import shutil
39
+ import subprocess
40
+ import sys
41
+ import tempfile
42
+ import time
43
+ import urllib.error
44
+ import urllib.request
45
+ import zipfile
46
+ from dataclasses import dataclass
47
+ from pathlib import Path
48
+ from typing import Callable, Optional
49
+ from urllib.parse import urljoin, urlsplit
50
+
51
+ from . import __version__, ed25519, settings
52
+ from .update_key import UPDATE_PUBLIC_KEY
53
+
54
+ log = logging.getLogger("pingerplot.update")
55
+
56
+ REPO = "jamesccupps/PingerPlot"
57
+ APP_KEY = "pingerplot"
58
+ MANIFEST_NAME = "latest.json"
59
+ INSTALLER_NAME = "PingerPlot-Setup.exe"
60
+ PORTABLE_NAME = "PingerPlot-win64.zip"
61
+ GUI_EXE = "PingerPlot.exe"
62
+ DEFAULT_SOURCE = f"https://github.com/{REPO}/releases/latest/download/{MANIFEST_NAME}"
63
+ RELEASES_URL = f"https://github.com/{REPO}/releases"
64
+ LOG_NAME = "update.log"
65
+
66
+ MAX_MANIFEST = 64 * 1024
67
+ MAX_DOWNLOAD = 300 * 1024 * 1024
68
+
69
+ _VERSION_RE = re.compile(r"^(\d{1,4})\.(\d{1,4})\.(\d{1,6})$")
70
+ STAGING_PREFIX = "PingerPlot-update-" # + the version: a download's folder in %TEMP%
71
+ _STAGING_RE = re.compile(re.escape(STAGING_PREFIX) + r"\d{1,4}\.\d{1,4}\.\d{1,6}")
72
+ _FILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$")
73
+ _SHA_RE = re.compile(r"^[0-9a-f]{64}$")
74
+ _GITHUB_LATEST = re.compile(
75
+ r"^https://github\.com/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+)/releases/latest/download/latest\.json$")
76
+
77
+
78
+ class UpdateError(Exception):
79
+ """Anything that stops an update: a bad signature, a short download..."""
80
+
81
+
82
+ class RollbackIncomplete(UpdateError):
83
+ """A swap failed and some of the old program couldn't be put back."""
84
+
85
+
86
+ # What a release puts beside the exe (the zip's top level, packaging/
87
+ # build_windows.py): the only names a swap renames to <name>.old, and so the
88
+ # only .old names cleanup may remove. A portable folder also holds the
89
+ # user's own files.
90
+ PROGRAM_FILES = (GUI_EXE, "pingerplot-headless.exe", "_internal", "portable.txt",
91
+ "LICENSE", "THIRD-PARTY-NOTICES.md")
92
+ SPARE_BYTES = 50 * 1024 * 1024
93
+
94
+
95
+ def parse_version(v):
96
+ m = _VERSION_RE.match(v) if isinstance(v, str) else None
97
+ return tuple(int(x) for x in m.groups()) if m else None
98
+
99
+
100
+ def update_source() -> str:
101
+ """Where latest.json comes from: PINGERPLOT_UPDATE_URL (a URL or a folder,
102
+ for testing and for anyone mirroring releases) or this repo's latest
103
+ release."""
104
+ return os.environ.get("PINGERPLOT_UPDATE_URL") or DEFAULT_SOURCE
105
+
106
+
107
+ def program_dir() -> Path:
108
+ return Path(sys.executable).resolve().parent
109
+
110
+
111
+ def install_kind() -> str:
112
+ """'source' (a checkout: main.py beside the package), 'pip' (installed
113
+ with pip or pipx, the Linux way), 'installed' (Setup.exe), 'portable'
114
+ (the zip), or 'folder' (a frozen build that is neither, e.g. copied by
115
+ hand)."""
116
+ if not getattr(sys, "frozen", False):
117
+ here = Path(__file__).resolve().parent.parent
118
+ return "source" if (here / "main.py").is_file() else "pip"
119
+ if settings.portable_dir() is not None:
120
+ return "portable"
121
+ if (program_dir() / "unins000.exe").exists():
122
+ return "installed"
123
+ return "folder"
124
+
125
+
126
+ # --- the manifest -----------------------------------------------------------------
127
+
128
+ def _check_asset(asset, name):
129
+ if asset is None:
130
+ return None
131
+ if not isinstance(asset, dict):
132
+ raise UpdateError(f"{name}: not an object")
133
+ f, size, sha = asset.get("file"), asset.get("size"), asset.get("sha256")
134
+ # A bare file name: the manifest says what to fetch, never from where.
135
+ if not (isinstance(f, str) and _FILE_RE.match(f)):
136
+ raise UpdateError(f"{name}: bad file name {f!r}")
137
+ if not (isinstance(size, int) and not isinstance(size, bool) and 0 < size <= MAX_DOWNLOAD):
138
+ raise UpdateError(f"{name}: bad size {size!r}")
139
+ if not (isinstance(sha, str) and _SHA_RE.match(sha)):
140
+ raise UpdateError(f"{name}: bad sha256")
141
+ return {"file": f, "size": size, "sha256": sha}
142
+
143
+
144
+ def verify_manifest(text: str, public_key: Optional[str] = None) -> dict:
145
+ """The manifest's payload, if and only if it is signed by ``public_key``
146
+ (base64 of the raw 32-byte key; the one built into the app by default)
147
+ and well-formed."""
148
+ public_key = public_key or UPDATE_PUBLIC_KEY
149
+ try:
150
+ outer = json.loads(text)
151
+ payload = base64.b64decode(outer["payload"], validate=True)
152
+ signature = base64.b64decode(outer["signature"], validate=True)
153
+ key = base64.b64decode(public_key, validate=True)
154
+ except (ValueError, KeyError, TypeError) as e:
155
+ raise UpdateError(f"latest.json is malformed: {e}") from e
156
+ if not ed25519.verify(key, payload, signature):
157
+ raise UpdateError("latest.json isn't signed with the key this app trusts")
158
+ try:
159
+ m = json.loads(payload)
160
+ except ValueError as e:
161
+ raise UpdateError("latest.json's payload isn't JSON") from e
162
+ if not isinstance(m, dict) or m.get("app") != APP_KEY:
163
+ raise UpdateError("latest.json is for another app")
164
+ if parse_version(m.get("version")) is None:
165
+ raise UpdateError(f"latest.json has a bad version {m.get('version')!r}")
166
+ return {
167
+ "version": m["version"],
168
+ "published": m.get("published") if isinstance(m.get("published"), str) else None,
169
+ "installer": _check_asset(m.get("installer"), "installer"),
170
+ "portable": _check_asset(m.get("portable"), "portable"),
171
+ }
172
+
173
+
174
+ # --- fetching ------------------------------------------------------------------------
175
+
176
+ def _is_url(source: str) -> bool:
177
+ return urlsplit(source).scheme in ("http", "https")
178
+
179
+
180
+ def asset_location(source: str, version: str, name: str) -> str:
181
+ """Where a release file lives, next to its manifest.
182
+
183
+ For GitHub's /releases/latest/ URL the file comes from that version's own
184
+ tag instead: a release published between reading the manifest and the
185
+ download would otherwise hand over the next version's file (refused by its
186
+ hash, but a failed update nonetheless).
187
+ """
188
+ m = _GITHUB_LATEST.match(source)
189
+ if m:
190
+ return f"https://github.com/{m.group(1)}/{m.group(2)}/releases/download/v{version}/{name}"
191
+ if _is_url(source):
192
+ return urljoin(source, name)
193
+ p = Path(source)
194
+ return str((p.parent if p.suffix.lower() == ".json" else p) / name)
195
+
196
+
197
+ def _open(url: str, timeout: float):
198
+ req = urllib.request.Request(url, headers={"User-Agent": f"PingerPlot/{__version__}"})
199
+ return urllib.request.urlopen(req, timeout=timeout)
200
+
201
+
202
+ def _read_manifest(source: str) -> Optional[str]:
203
+ if _is_url(source):
204
+ try:
205
+ with _open(source, 20) as r:
206
+ data = r.read(MAX_MANIFEST + 1)
207
+ except urllib.error.HTTPError as e:
208
+ if e.code == 404:
209
+ # The latest release has no latest.json: one from before 1.4,
210
+ # or a release made by hand without it. Nothing to install.
211
+ return None
212
+ raise
213
+ else:
214
+ p = Path(source)
215
+ if p.is_dir():
216
+ p = p / MANIFEST_NAME
217
+ with open(p, "rb") as fh:
218
+ data = fh.read(MAX_MANIFEST + 1)
219
+ if len(data) > MAX_MANIFEST:
220
+ raise UpdateError("latest.json is too big")
221
+ return data.decode("utf-8")
222
+
223
+
224
+ @dataclass
225
+ class Update:
226
+ version: str
227
+ published: Optional[str]
228
+ kind: str # install_kind() at check time
229
+ asset: Optional[dict] # what this copy would download; None for source runs
230
+ source: str
231
+
232
+ @property
233
+ def can_install(self) -> bool:
234
+ return self.asset is not None
235
+
236
+
237
+ def check(current: str = __version__, source: Optional[str] = None) -> Optional[Update]:
238
+ """The newer release, or None when this copy is up to date. Raises
239
+ UpdateError (or an OSError from the network) when it can't tell."""
240
+ source = source or update_source()
241
+ text = _read_manifest(source)
242
+ if text is None:
243
+ log.info("no latest.json at %s; nothing to install", source)
244
+ return None
245
+ m = verify_manifest(text)
246
+ if parse_version(m["version"]) <= (parse_version(current) or (0, 0, 0)):
247
+ return None
248
+ kind = install_kind()
249
+ asset = {"installed": m["installer"], "portable": m["portable"], "folder": m["portable"]}.get(kind)
250
+ return Update(m["version"], m["published"], kind, asset, source)
251
+
252
+
253
+ def download(update: Update, dest_dir: Optional[Path] = None,
254
+ progress: Optional[Callable[[int, int], None]] = None) -> Path:
255
+ """Fetch the update's file, check its size and SHA-256, return its path.
256
+ progress(done_bytes, total_bytes) is called as it arrives."""
257
+ if not update.can_install:
258
+ raise UpdateError("nothing to download for this kind of copy")
259
+ a = update.asset
260
+ dest_dir = Path(dest_dir or Path(tempfile.gettempdir()) / f"{STAGING_PREFIX}{update.version}")
261
+ dest_dir.mkdir(parents=True, exist_ok=True)
262
+ final, part = dest_dir / a["file"], dest_dir / (a["file"] + ".part")
263
+ where = asset_location(update.source, update.version, a["file"])
264
+ digest, done = hashlib.sha256(), 0
265
+ try:
266
+ src = _open(where, 60) if _is_url(where) else open(where, "rb")
267
+ with src, open(part, "wb") as out:
268
+ for chunk in iter(lambda: src.read(256 * 1024), b""):
269
+ done += len(chunk)
270
+ if done > a["size"]:
271
+ raise UpdateError(f"{a['file']} is bigger than latest.json says")
272
+ digest.update(chunk)
273
+ out.write(chunk)
274
+ if progress:
275
+ progress(done, a["size"])
276
+ if done != a["size"] or digest.hexdigest() != a["sha256"]:
277
+ raise UpdateError(f"{a['file']} doesn't match latest.json "
278
+ f"({done} bytes, sha256 {digest.hexdigest()[:12]}…)")
279
+ os.replace(part, final)
280
+ except BaseException:
281
+ part.unlink(missing_ok=True)
282
+ raise
283
+ log.info("%s %s downloaded and verified (%d bytes)", update.version, a["file"], done)
284
+ return final
285
+
286
+
287
+ # --- installing ------------------------------------------------------------------------
288
+
289
+ _DETACHED = 0x00000008 | 0x00000200 # DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP
290
+
291
+
292
+ def _spawn(args, cwd) -> subprocess.Popen:
293
+ kwargs = {"cwd": str(cwd), "close_fds": True, "stdin": subprocess.DEVNULL,
294
+ "stdout": subprocess.DEVNULL, "stderr": subprocess.DEVNULL}
295
+ if sys.platform == "win32":
296
+ kwargs["creationflags"] = _DETACHED
297
+ return subprocess.Popen([str(a) for a in args], **kwargs)
298
+
299
+
300
+ def folder_is_writable(folder: Optional[Path] = None) -> bool:
301
+ folder = Path(folder or program_dir())
302
+ probe = folder / f".write-test-{os.getpid()}"
303
+ try:
304
+ probe.write_bytes(b"")
305
+ probe.unlink()
306
+ return True
307
+ except OSError:
308
+ return False
309
+
310
+
311
+ def _safe_extract(zip_path: Path, dest: Path) -> None:
312
+ dest = Path(dest).resolve()
313
+ with zipfile.ZipFile(zip_path) as z:
314
+ for info in z.infolist():
315
+ target = (dest / info.filename).resolve()
316
+ if target != dest and dest not in target.parents:
317
+ raise UpdateError(f"{info.filename}: outside the update folder")
318
+ z.extractall(dest)
319
+
320
+
321
+ def stage(path: Path) -> Path:
322
+ """Unzip a portable update and return the folder holding its exe."""
323
+ staged = path.parent / "staged"
324
+ if staged.exists():
325
+ shutil.rmtree(staged, ignore_errors=True)
326
+ _safe_extract(path, staged)
327
+ for exe in [staged / GUI_EXE, *staged.glob(f"*/{GUI_EXE}")]:
328
+ if exe.is_file():
329
+ return exe.parent
330
+ raise UpdateError(f"{path.name} has no {GUI_EXE}")
331
+
332
+
333
+ def apply(update: Update, path: Path) -> None:
334
+ """Start installing ``path``. The caller must exit straight away after."""
335
+ if update.kind == "installed":
336
+ log.info("starting the %s installer", update.version)
337
+ _spawn([path, "/VERYSILENT", "/SUPPRESSMSGBOXES", "/NORESTART", "/relaunch=1"], cwd=path.parent)
338
+ return
339
+ if not folder_is_writable():
340
+ raise UpdateError(f"{program_dir()} can't be written to. Move PingerPlot to a folder of "
341
+ "your own, or download the new version by hand.")
342
+ staged = stage(path)
343
+ log.info("starting the staged %s to swap it in", update.version)
344
+ # The helper's working folder is the staging area's parent, never the
345
+ # program folder, which it is about to rename.
346
+ _spawn([staged / GUI_EXE, "--finish-update", program_dir(), os.getpid()], cwd=staged.parent)
347
+
348
+
349
+ def ulog(msg: str, path: Optional[Path] = None) -> None:
350
+ path = path or settings.config_dir() / LOG_NAME
351
+ try:
352
+ path.parent.mkdir(parents=True, exist_ok=True)
353
+ with open(path, "a", encoding="utf-8") as fh:
354
+ fh.write(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {msg}\n")
355
+ except OSError:
356
+ pass
357
+
358
+
359
+ def _wait_for_exit(pid: int, timeout: float = 60) -> bool:
360
+ if sys.platform != "win32":
361
+ end = time.monotonic() + timeout
362
+ while time.monotonic() < end:
363
+ try:
364
+ os.kill(pid, 0)
365
+ except OSError:
366
+ return True
367
+ time.sleep(0.2)
368
+ return False
369
+ import ctypes
370
+ k32 = ctypes.windll.kernel32
371
+ h = k32.OpenProcess(0x00100000, False, pid) # SYNCHRONIZE
372
+ if not h:
373
+ return True # already gone
374
+ try:
375
+ return k32.WaitForSingleObject(h, int(timeout * 1000)) == 0
376
+ finally:
377
+ k32.CloseHandle(h)
378
+
379
+
380
+ def _retry(fn, tries: int = 40, delay: float = 0.25):
381
+ for i in range(tries):
382
+ try:
383
+ return fn()
384
+ except OSError:
385
+ if i == tries - 1:
386
+ raise
387
+ time.sleep(delay)
388
+
389
+
390
+ def _remove(p: Path) -> None:
391
+ if p.is_dir() and not p.is_symlink():
392
+ shutil.rmtree(p)
393
+ elif p.exists():
394
+ p.unlink()
395
+
396
+
397
+ def swap_in(app_dir: Path, staged: Path) -> None:
398
+ """Replace app_dir's program files with staged's. Data files stay put.
399
+
400
+ Each item is renamed to <name>.old first and only then copied in; on any
401
+ failure the copies are removed and the .old items renamed back.
402
+ """
403
+ app_dir, staged = Path(app_dir), Path(staged)
404
+ names = [e.name for e in staged.iterdir()
405
+ if not (e.name == settings.PORTABLE_MARKER
406
+ and not (app_dir / settings.PORTABLE_MARKER).exists())]
407
+ # The old files stay beside the new ones until the new version has
408
+ # started, so the new copy needs room of its own: a nearly full USB
409
+ # stick is refused before anything is touched.
410
+ need = sum(f.stat().st_size for n in names for f in
411
+ ([staged / n] if (staged / n).is_file() else (staged / n).rglob("*"))
412
+ if f.is_file())
413
+ free = shutil.disk_usage(app_dir).free
414
+ if free < need + SPARE_BYTES:
415
+ raise UpdateError(f"not enough free space in {app_dir}: the update needs "
416
+ f"{(need + SPARE_BYTES) // 2**20} MB, there are {free // 2**20} MB")
417
+ renamed, placed = [], []
418
+ try:
419
+ for n in names:
420
+ target, old = app_dir / n, app_dir / (n + ".old")
421
+ if old.exists():
422
+ _retry(lambda: _remove(old))
423
+ if target.exists():
424
+ _retry(lambda: target.rename(old))
425
+ renamed.append(n)
426
+ src = staged / n
427
+ # Recorded before the copy: a copy that fails half way leaves a
428
+ # half-new folder, which the rollback has to remove too.
429
+ placed.append(n)
430
+ if src.is_dir():
431
+ shutil.copytree(src, target)
432
+ else:
433
+ shutil.copy2(src, target)
434
+ except BaseException as exc:
435
+ stuck = []
436
+ for n in placed:
437
+ try:
438
+ if (app_dir / n).exists():
439
+ _retry(lambda: _remove(app_dir / n), tries=10)
440
+ except OSError:
441
+ stuck.append(n)
442
+ for n in renamed:
443
+ try:
444
+ _retry(lambda: (app_dir / (n + ".old")).rename(app_dir / n), tries=10)
445
+ except OSError:
446
+ stuck.append(n + ".old")
447
+ if stuck and isinstance(exc, Exception):
448
+ raise RollbackIncomplete(f"{exc!r}; couldn't put back: {', '.join(stuck)}") from exc
449
+ raise
450
+
451
+
452
+ def finish_update(app_dir, pid) -> int:
453
+ """Run by the staged copy: swap it into app_dir, then start it there.
454
+ Returns the process exit code."""
455
+ app_dir, staged = Path(app_dir), program_dir()
456
+ # This copy runs from the staging folder, whose own portable.txt would
457
+ # point its data folder there; the log belongs with the app's.
458
+ logfile = (app_dir if (app_dir / settings.PORTABLE_MARKER).exists()
459
+ else settings.config_dir()) / LOG_NAME
460
+ ulog(f"update: {__version__} waiting for {pid} to exit", logfile)
461
+ if not _wait_for_exit(int(pid)):
462
+ ulog("update: the old copy didn't exit; giving up", logfile)
463
+ return 1
464
+ try:
465
+ swap_in(app_dir, staged)
466
+ except RollbackIncomplete as e:
467
+ ulog(f"update: FAILED, and the old version couldn't be fully put back: {e}. "
468
+ f"Download the release again from {RELEASES_URL}", logfile)
469
+ _spawn([app_dir / GUI_EXE, "--update-failed"], cwd=app_dir)
470
+ return 1
471
+ except Exception as e: # whatever went wrong, the old copy comes back
472
+ ulog(f"update: failed, old version restored: {e!r}", logfile)
473
+ _spawn([app_dir / GUI_EXE, "--update-failed"], cwd=app_dir)
474
+ return 1
475
+ ulog(f"update: done, starting {__version__}", logfile)
476
+ _spawn([app_dir / GUI_EXE, "--updated"], cwd=app_dir)
477
+ return 0
478
+
479
+
480
+ def cleanup_after_update(remove_old: bool = True) -> None:
481
+ """Remove what a swap leaves behind: the program's own <name>.old beside
482
+ it (only those: a portable folder holds the user's files too, and only
483
+ after a successful update, when the .old items are the version being
484
+ replaced, never a rollback's leftovers) and the staging folders in %TEMP%.
485
+ Anything still locked is left for next time."""
486
+ if remove_old and getattr(sys, "frozen", False):
487
+ for name in PROGRAM_FILES:
488
+ p = program_dir() / (name + ".old")
489
+ try:
490
+ if p.exists():
491
+ _remove(p)
492
+ except OSError:
493
+ pass
494
+ # Exactly the folders download() makes. Not glob("PingerPlot-update-*"):
495
+ # on Windows that matches without regard to case, and it once deleted a
496
+ # test's own pingerplot-update-test-NNN folder, the updated copy in it.
497
+ for p in Path(tempfile.gettempdir()).iterdir():
498
+ if _STAGING_RE.fullmatch(p.name) and p.is_dir():
499
+ shutil.rmtree(p, ignore_errors=True)