@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/libexec/update.py

@@ -14,19 +14,26 @@ catalog — a failure there leaves the installed release running as it was. comm
 installed. Its steps run in this order, each whatever the ones before it returned, each bounded by STEP_TIMEOUT seconds
 (its whole process group is stopped when it does not finish):
   systemctl --user daemon-reload · lanes sync · systemctl --user restart lanes-statusd.service ·
-  systemctl --user try-restart <unit> for each optional service in TRY_RESTART (restarted only when it runs) ·
+  systemctl --user try-restart <unit> for each optional service in TRY_RESTART (restarted only when it runs), and
+  right after lanes-docsd's, `sh install/enable-docs.sh` of the tree (the docs page's pinned Mermaid, plan W10 W8:
+  DOCS_STEP; skipped for a tree that has no such script) ·
   lanes install-container <name> for each container `lanes sync` recorded with a home volume (containers.json) ·
   lanes reload-views (the viewports; sidebars swap by themselves, W9 U5) · lanes ensure --if-layout-changed (W9 U6).
-Step output goes to the log (`update/last.log`); stdout gets one line per step and a summary.
+Step output goes to the log (`update/last.log`); stdout gets one line per step and a summary, which names the Mermaid
+outcome (`mermaid ok`, `mermaid skipped: <reason>`, …) whenever its step ran.
 
 The record, `<state>/update/last.json` (DM-LANES-UPDATE-RECORD), is one JSON object {checked_at, latest, installed,
-previous, result, steps: [{name, rc[, warning]}], log}. result: `ok` every phase and step exited 0 or only warned;
-`partial` the release is installed but a step after the commit failed (also while the post-commit runs: it is written
-before the first step); `refused` a prerequisite, no installed release, or another install holding the install lock
-said no and nothing changed; `failed` nothing was installed. A warning (WARN_RC) is a step's own report of a condition
-the update neither caused nor can mend — `lanes sync` exiting 1 for a board with an error — recorded with its rc and
-`"warning": true`, never a failure. Keys it does not own (a rollback's mark, plan W9 U3) are kept. host-install.sh
-writes `refused`, `failed` and a `partial` commit through `record`; `post-commit` writes its own.
+previous, result, steps: [{name, rc[, warning][, outcome, reason]}], log}. result: `ok` every phase and step exited 0
+or only warned; `partial` the release is installed but a step after the commit failed (also while the post-commit
+runs: it is written before the first step); `refused` a prerequisite, no installed release, or another install holding
+the install lock said no and nothing changed; `failed` nothing was installed. A warning (WARN_RC) is a step's own
+report of a condition the update neither caused nor can mend — `lanes sync` exiting 1 for a board with an error;
+enable-docs exiting 1 (a prerequisite or the download), 3 (refused: no valid pin, a digest mismatch) or not finishing
+in STEP_TIMEOUT (the download) — recorded with its rc and `"warning": true`, never a failure. A step with outcomes
+(STEP_OUTCOMES: enable-docs) that did not exit 0 also records `outcome` (`skipped`, `refused`, or `failed` for any
+other status, which is a failure) and `reason`, the last line it wrote (else what its status says). Keys it does not
+own (a rollback's mark, plan W9 U3) are kept. host-install.sh writes `refused`, `failed` and a `partial` commit through
+`record`; `post-commit` writes its own.
 
 The run lock, `<state>/update/.lock` (fix cycle 1 of W9 U2): every server install and update takes it before it writes
 anything — the log and the record included — and holds it to its end, so two runs never interleave a post-commit or
@@ -77,8 +84,8 @@ STEP_TIMEOUT = 300          # seconds per post-commit step; then its process gro
 STOP_WAIT = 5               # seconds between SIGTERM and SIGKILL of a step's process group, and after it
 # The optional services a post-commit restarts only when they run (`systemctl try-restart`), in this order. Each keeps
 # its enable state: an update never switches on a unit the operator left off (economy, notify, web: operator gates).
-TRY_RESTART = ('lanes-economy.service', 'lanes-notify.service', 'lanes-enrold.service', 'lanes-mobile.service',
-               'lanes-web.service', 'lanes-studio-host.service')
+TRY_RESTART = ('lanes-economy.service', 'lanes-notify.service', 'lanes-enrold.service', 'lanes-docsd.service',
+               'lanes-mobile.service', 'lanes-web.service', 'lanes-studio-host.service')
 RESULTS = ('ok', 'partial', 'refused', 'failed')
 OWNED = ('checked_at', 'latest', 'installed', 'previous', 'result', 'steps', 'log')   # the keys every record rewrites
 PARTIAL = 4                 # post-commit's exit status when a step failed (host-install.sh --update-only's as well)
@@ -90,7 +97,19 @@ REFUSED = 3                 # `lock`'s exit status when another run holds the ru
 # cmd_sync: `return 1 if failed`); counted as a failure, it would make every update `partial` for as long as such a
 # board exists, and `lanes update` re-run the whole post-commit on every tick (fix cycle 1 of W9 U2). Any other status
 # of the step — 124 no answer, 127 could not start, 128+N a signal — is a failure like any other.
-WARN_RC = {'sync': 1}
+# The docs page's pinned Mermaid (plan W10 W8, LNS-109) is the other: install/enable-docs.sh of the tree just installed,
+# run right after lanes-docsd's try-restart (the full install runs it right after lanes-docsd's restart). Never fatal:
+# Mermaid is optional (without it every fence shows its source), so its exit statuses 1 (a prerequisite is missing or
+# the download failed: skipped), 3 (refused: no valid pin in holders.lock, a digest mismatch; nothing installed) and
+# 124 (the download did not finish in STEP_TIMEOUT: skipped) are warnings; any other status (2 usage, 127 could not
+# start, a signal) is a failure like any other step's. An installed file with the pinned digest is kept: no download.
+DOCS_UNIT = 'lanes-docsd.service'
+DOCS_STEP = 'enable-docs'
+DOCS_SCRIPT = 'install/enable-docs.sh'
+WARN_RC = {'sync': (1,), DOCS_STEP: (1, 3, 124)}
+# The steps whose outcome the record and the summary name (any status not listed: `failed`).
+STEP_OUTCOMES = {DOCS_STEP: {0: 'ok', 1: 'skipped', 3: 'refused', 124: 'skipped'}}
+REASON_LIMIT = 300          # characters of a step's last line kept as its `reason` (a refusal names two digests)
 LOCK = 'update/.lock'       # the run lock, under the state directory
 MODES = ('update', 'install')
 RELEASE = re.compile(r'[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.+-]+)?\Z')
@@ -111,11 +130,14 @@ def utc(at=None):
 
 
 def step_entry(step):
-    """A record's step from (name, rc) or (name, rc, warning): {name, rc}, plus `"warning": true` for a warning."""
+    """A record's step from (name, rc), (name, rc, warning) or (name, rc, warning, extra): {name, rc}, plus
+    `"warning": true` for a warning, plus `extra` ({outcome, reason} of a step with outcomes that did not exit 0)."""
     name, rc, *rest = step
     entry = {'name': name, 'rc': int(rc)}
     if rest and rest[0]:
         entry['warning'] = True
+    if len(rest) > 1 and rest[1]:
+        entry.update(rest[1])
     return entry
 
 
@@ -128,6 +150,44 @@ def warned_steps(steps):
     return [entry['name'] for entry in map(step_entry, steps) if entry.get('warning')]
 
 
+def step_outcome(name, rc, said, timeout):
+    """{} for a step without outcomes (STEP_OUTCOMES) or one that exited 0, else {outcome, reason}: the outcome its
+    status names (`failed` when it names none) and `reason`, the last line `said` (its own output) holds, else what
+    the status says (describe)."""
+    outcomes = STEP_OUTCOMES.get(name)
+    if outcomes is None or rc == 0:
+        return {}
+    lines = [line for line in said.splitlines() if line.strip()]
+    reason = printable(lines[-1], REASON_LIMIT) if lines and rc not in (124, 127) else describe(rc, timeout)
+    return {'outcome': outcomes.get(rc, 'failed'), 'reason': reason}
+
+
+def step_said(log, start):
+    """What a step wrote to the log after byte `start`: run_step's `== argv` line and its `-> …` line left out."""
+    try:
+        with open(log, 'rb') as handle:
+            handle.seek(start)
+            text = handle.read().decode('utf-8', 'replace')
+    except OSError:
+        return ''
+    lines = text.splitlines()
+    if lines and lines[0].startswith('== '):
+        lines = lines[1:]
+    if lines and lines[-1].startswith('-> '):
+        lines = lines[:-1]
+    return '\n'.join(lines)
+
+
+def outcome_clause(steps):
+    """The summary's words for the steps with outcomes that ran: `; mermaid ok`, `; mermaid skipped: <reason>`, …"""
+    words = []
+    for entry in map(step_entry, steps):
+        if entry['name'] == DOCS_STEP:
+            outcome = entry.get('outcome') or ('ok' if entry['rc'] == 0 else 'failed')
+            words.append(f"; mermaid {outcome}" + (f": {entry['reason']}" if entry.get('reason') else ''))
+    return ''.join(words)
+
+
 def installed_tree(home=None):
     """The existing tree the `current` link names now (resolved), else None."""
     try:
@@ -252,14 +312,18 @@ def post_commit(tree, state, log, steps=(), before=None, started=None, out=None,
     Path(log).parent.mkdir(parents=True, exist_ok=True)
     with open(log, 'a') as handle:
         def step(name, argv):
+            handle.flush()
+            start = os.fstat(handle.fileno()).st_size     # where this step's lines begin (O_APPEND: the end)
             try:
                 rc = run(argv, handle, timeout)
             except (KeyboardInterrupt, SystemExit) as error:
                 steps.append((name, interrupted_rc(error)))
                 print(f'FAIL  {name} (interrupted)', file=out, flush=True)
                 raise
-            warning = rc != 0 and WARN_RC.get(name) == rc
-            steps.append((name, rc, warning))
+            warning = rc != 0 and rc in WARN_RC.get(name, ())
+            handle.flush()
+            extra = step_outcome(name, rc, step_said(log, start) if rc and name in STEP_OUTCOMES else '', timeout)
+            steps.append((name, rc, warning, extra))
             print('ok    ' + name if rc == 0 else f"{'WARN' if warning else 'FAIL'}  {name} ({describe(rc, timeout)})",
                   file=out, flush=True)
         try:
@@ -268,6 +332,10 @@ def post_commit(tree, state, log, steps=(), before=None, started=None, out=None,
             step('restart lanes-statusd', [systemctl, '--user', 'restart', 'lanes-statusd.service'])
             for unit in TRY_RESTART:
                 step('try-restart ' + unit[:-len('.service')], [systemctl, '--user', 'try-restart', unit])
+                if unit == DOCS_UNIT and (Path(tree) / DOCS_SCRIPT).is_file():
+                    # `sh`, as the RUNBOOK runs it: a tree whose script lost its mode bit still installs Mermaid. A
+                    # tree from before W10 W6 (a rollback's) has no script: nothing to run, no step.
+                    step(DOCS_STEP, ['sh', str(Path(tree) / DOCS_SCRIPT)])
             for container in recorded_containers(state):
                 step('install-container ' + container, [lanes, 'install-container', container])
             step('reload-views', [lanes, 'reload-views'])
@@ -276,16 +344,20 @@ def post_commit(tree, state, log, steps=(), before=None, started=None, out=None,
         finally:
             ok = finished and not failed_steps(steps)
             document = write_record(state, 'ok' if ok else 'partial', steps, tree, before, log, started, environ, home)
-    failed, warned = failed_steps(steps), warned_steps(steps)
+    # A step with outcomes is named by its own clause (`; mermaid skipped: …`), not again among the warnings.
+    failed, warned = failed_steps(steps), [name for name in warned_steps(steps) if name not in STEP_OUTCOMES]
     was = f" (was {document['previous']})" if document['previous'] else ''
     warnings = f"; {count(warned, 'warning')}: {', '.join(warned)}" if warned else ''
-    if ok and not warned:
-        print(f"ok: lanes {document['installed']} installed{was}; every step ran — {record_path(state)}", file=out)
+    outcomes = outcome_clause(steps)
+    if ok and not warned_steps(steps):
+        print(f"ok: lanes {document['installed']} installed{was}; every step ran{outcomes} — {record_path(state)}",
+              file=out)
     elif ok:
-        print(f"ok: lanes {document['installed']} installed{was}; every step ran{warnings} — log {log}", file=out)
+        print(f"ok: lanes {document['installed']} installed{was}; every step ran{warnings}{outcomes} — log {log}",
+              file=out)
     else:
         print(f"partial: lanes {document['installed']} installed{was}; {count(failed, 'step')} failed: "
-              f"{', '.join(failed)}{warnings} — log {log}", file=out)
+              f"{', '.join(failed)}{warnings}{outcomes} — log {log}", file=out)
     return document
 
 
@@ -850,8 +922,8 @@ def update_main(args, key, out=None, environ=None, home=None, clock=None, output
 
 def timer_enabled(units):
     """Whether lanes-update.timer is enabled in one of the unit folders `units`: `<folder>/timers.target.wants/
-    lanes-update.timer`, the link `systemctl --user enable` makes, names an existing unit. A file read, as every other
-    doctor line is (doctor never asks systemctl)."""
+    lanes-update.timer`, the link `systemctl --user enable` makes, names an existing unit. A file read: this line
+    never asks systemctl (the web and docs lines do, one bounded `systemctl --user show` each)."""
     return any((Path(folder) / TIMER_WANTS / TIMER).exists() for folder in units)