gowalk-cicd 1.0.164 → 1.0.167

package/README.md

@@ -210,8 +210,14 @@ it rsyncs the backend dir to `/opt/gowalk-backends/<app>/`, runs
 wires an nginx vhost + Let's Encrypt cert for the API domain, and health-checks.
 Hosts with several existing Let's Encrypt accounts select one deterministically,
 and a domain deploy fails unless its public HTTPS certificate and health route validate.
-Changing a container's published port preserves its existing HTTPS configuration. An existing
-certificate is installed for the requested domain on redeploy, repairing older HTTP-only vhosts too.
+Changing a container's published port preserves its existing HTTPS configuration; nginx must accept
+the change, or the previous vhost is restored and the deploy fails. An existing certificate is
+installed for the requested domain on redeploy, repairing older HTTP-only vhosts too.
+A redeploy whose vhost already holds that certificate behind Certbot's redirect, whose certificate and
+key form a pair, whose running nginx presents it for the domain, and whose name no other server block in
+nginx's loaded configuration declares, skips the install, which would otherwise save a checkpoint copy of
+every nginx file on the host. It still tests and reloads nginx as the install did, and fails the deploy
+when nginx refuses either.
 
 Requirements on the consumer repo:
 
@@ -225,6 +231,13 @@ Requirements on the consumer repo:
 - Repo **secret** `BACKEND_RUNTIME_ENV` (optional): newline-delimited `KEY=value`
   runtime secrets. The action writes it as mode 0600 on the host and passes it
   to Compose without copying values into the repository or action log.
+  Existing quoted values, comments and ordinary dotenv assignments retain their syntax.
+  Raw multiline PEM blocks and JSON objects/arrays
+  are converted to quoted literal values, preserving embedded dollars and backslashes.
+  Already quoted values and single-line JSON retain their existing interpolation semantics.
+  Malformed or ambiguous multiline structures refuse before deployment. Transport is bounded
+  to 1 MiB of UTF-8 input and 512 KiB per value, uses private SSH stdin, and atomically replaces
+  `.runtime.env`; application sync preserves the last installed file if validation fails.
 - Repo **variables** (optional): `BACKEND_API_DOMAIN` (its DNS A record must point
   at the host for the cert; empty = deploy the container only, skip nginx/cert),
   `BACKEND_APP_NAME` (defaults to the repo name), `BACKEND_HEALTH_PATH`

package/android-action/scripts/gradle_wrapper.py

@@ -87,13 +87,14 @@ def _exists(name: str) -> bool | None:
         return None
 
 
-def normalize(version: Version, probe=_exists) -> str:
+def normalize(version: Version, probe=None) -> str:
     """The distribution name to write into distributionUrl.
 
     Probes services.gradle.org so a future naming change corrects itself; falls
     back to the ordering in `candidates` when the network is unavailable, which
     is no worse than not probing at all.
     """
+    probe = probe or _exists
     options = candidates(version)
     for name in options:
         if probe(name) is True:

package/android-action/scripts/test_gradle_wrapper.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 import tempfile
 import unittest
 from pathlib import Path
+from unittest import mock
 
 import gradle_wrapper as gw
 
@@ -29,6 +30,12 @@ def never(_name: str) -> bool:
     return False
 
 
+def setUpModule():
+    patcher = mock.patch.object(gw, "_exists", never)
+    patcher.start()
+    unittest.addModuleCleanup(patcher.stop)
+
+
 class RenderTest(unittest.TestCase):
     def test_eight_x_drops_a_trailing_zero_patch(self):
         self.assertEqual(gw.candidates((8, 14, 0))[0], "8.14")

package/backend-action/action.yml

@@ -149,17 +149,17 @@ runs:
         SSH="ssh -i ~/.ssh/backend_deploy -o IdentitiesOnly=yes"
         DEST="/opt/gowalk-backends/${{ inputs.app-name }}"
         $SSH "${{ inputs.ssh-user }}@${{ inputs.host }}" "mkdir -p '$DEST'"
-        # --delete keeps the mirror true; exclude .env so server-side secrets
-        # (generated DB password, etc.) survive across deploys.
+        # --delete keeps the mirror true; preserve the private server-side env files
+        # until their replacement validates so failed credential updates retain the old file.
         if [ "${COMPOSE_FILE%/*}" = "$BACKEND_DIR" ]; then
-          rsync -az --delete --exclude '.env' --exclude '.git' \
+          rsync -az --delete --exclude '.env' --exclude '.runtime.env' --exclude '.git' \
             --exclude '.backend-edge.json' --exclude '.backend-ingress.conf' --exclude '.backend-public.env' \
             -e "$SSH" "$BACKEND_DIR/" \
             "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/"
         else
           $SSH "${{ inputs.ssh-user }}@${{ inputs.host }}" \
             "mkdir -p '$DEST/$BACKEND_DIR'"
-          rsync -az --delete --exclude '.env' --exclude '.git' \
+          rsync -az --delete --exclude '.env' --exclude '.runtime.env' --exclude '.git' \
             -e "$SSH" "$BACKEND_DIR/" \
             "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/$BACKEND_DIR/"
           rsync -az -e "$SSH" "$COMPOSE_FILE" \
@@ -171,8 +171,11 @@ runs:
           "${{ github.action_path }}/remote_deploy.sh" \
           "${{ github.action_path }}/select_certbot_account.sh" \
           "${{ github.action_path }}/ensure_certificate.sh" \
+          "${{ github.action_path }}/certificate_vhost.py" \
           "${{ github.action_path }}/configure_vhost.py" \
           "${{ github.action_path }}/edge_inputs.py" \
+          "${{ github.action_path }}/runtime_env.py" \
+          "${{ github.action_path }}/runtime_env_parse.py" \
           "${{ github.action_path }}/edge_vhost.py" \
           "${{ github.action_path }}/edge_health.py" \
           "${{ github.action_path }}/identity_diagnostics.py" \
@@ -208,9 +211,9 @@ runs:
           "${{ inputs.ssh-user }}@${{ inputs.host }}" \
           "umask 077; mkdir -p '$EDGE_DIR'; python3 '$DEST/edge_inputs.py' receive '$EDGE_DIR/.backend-edge.json'"
         if [ -n "${RUNTIME_ENV:-}" ]; then
-          printf '%s\n' "$RUNTIME_ENV" | $SSH \
+          python3 "${{ github.action_path }}/runtime_env.py" export | $SSH \
             "${{ inputs.ssh-user }}@${{ inputs.host }}" \
-            "umask 077; cat > '$DEST/.runtime.env'"
+            "python3 '$DEST/runtime_env.py' receive '$DEST/.runtime.env'"
         fi
         BACKEND_DEPLOY_PHASE=remote_deploy
         $SSH "${{ inputs.ssh-user }}@${{ inputs.host }}" \

package/backend-action/certificate_vhost.py

@@ -0,0 +1,259 @@
+"""Tell whether a domain's vhost already serves its lineage exactly as `certbot install --redirect` leaves it.
+
+Every `certbot install --nginx` saves a checkpoint copy of every nginx file on the host, even when it
+changes nothing. The deploy skips that install only when this prints `current`: the managed file holds
+Certbot's TLS block for exactly that lineage behind Certbot's redirect, the lineage's certificate and key
+load as a pair, the running nginx answers the name with that lineage's certificate, and no other server
+block in the whole configuration nginx loads names it. Every other state, including any doubt, keeps the
+install. Only fixed state tokens are printed, never file content.
+
+A skipped install still tests and reloads nginx (`ensure_certificate.sh`), as the install did.
+"""
+import os
+from pathlib import Path
+import re
+import socket
+import ssl
+import subprocess
+import sys
+
+DOMAIN = re.compile(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?")
+TLS_LISTENS = {("443", "ssl"), ("[::]:443", "ssl", "ipv6only=on")}
+HTTP_LISTENS = {("80",), ("[::]:80",)}
+REDIRECT = [("return", ("301", "https://$host$request_uri"), None)]
+WORD_END = " \t\r\n;{"
+# Wherever nginx could start a token spelled `server_name`, bare or quoted, and in comments too.
+SERVER_NAME = re.compile(rb"""(?<![^\s;{}#"'])server_name(?=[\s"'])""")
+# A word nginx reads as one, or whose content a pair of quotes holds whole: no `#` or other quote, and no
+# backslash that could escape the blank or `;` after it. A word holding a backslash is never a domain name.
+READABLE_NAME = re.compile(rb"""(?:[^#"'\\]|\\[^#"'])*|(["'])[^#"'\\]*\1""")
+WORD = re.compile(rb"[^ \t\r\n]+")  # nginx separates words by these four only
+PEM_CERTIFICATE = re.compile(r"-----BEGIN CERTIFICATE-----\n.+?\n-----END CERTIFICATE-----", re.S)
+ORIGIN = ("127.0.0.1", 443)
+LOADED = ("nginx", "-T")
+DUMPED_FILE = re.compile(rb"^# configuration file (.*):$", re.M)
+
+
+class Unparsable(ValueError):
+    pass
+
+
+def tokens(text):
+    """Yield (is_word, value); refuse escapes, variables in braces and stray quotes or braces in words."""
+    index, size = 0, len(text)
+    while index < size:
+        char = text[index]
+        if char in " \t\r\n":
+            index += 1
+        elif char == "#":
+            end = text.find("\n", index)
+            index = size if end < 0 else end
+        elif char in ";{}":
+            yield False, char
+            index += 1
+        elif char in "\"'":
+            end = text.find(char, index + 1)
+            if end < 0 or "\\" in text[index + 1:end] or text[end + 1:end + 2] not in ("",) + tuple(WORD_END):
+                raise Unparsable
+            yield True, text[index + 1:end]
+            index = end + 1
+        else:
+            end = index
+            while end < size and text[end] not in WORD_END:
+                end += 1
+            word = text[index:end]
+            if any(mark in word for mark in ("}", "\"", "'", "\\", "${")):
+                raise Unparsable
+            yield True, word
+            index = end
+
+
+def parse(text):
+    """Return top-level (name, arguments, children) entries; children is None for a simple directive."""
+    stack, words = [[]], []
+    for is_word, value in tokens(text):
+        if is_word:
+            words.append(value)
+        elif value == "}":
+            if words or len(stack) == 1:
+                raise Unparsable
+            stack.pop()
+        elif not words:
+            raise Unparsable
+        else:
+            children = [] if value == "{" else None
+            stack[-1].append((words[0], tuple(words[1:]), children))
+            words = []
+            if children is not None:
+                stack.append(children)
+    if words or len(stack) != 1:
+        raise Unparsable
+    return stack[0]
+
+
+def values(block, name):
+    found = [entry for entry in block if entry[0] == name]
+    if any(children is not None for _, _, children in found):
+        raise Unparsable
+    return [arguments for _, arguments, _ in found]
+
+
+def role(block, domain):
+    """Classify one server block as Certbot leaves it: `tls` on 443, `http` on 80, else `ambiguous`."""
+    listens = values(block, "listen")
+    if values(block, "server_name") != [(domain,)] or values(block, "ssl") or len(set(listens)) != len(listens):
+        return "ambiguous"
+    if listens and set(listens) <= TLS_LISTENS and ("443", "ssl") in listens:
+        return "tls"
+    if listens and set(listens) <= HTTP_LISTENS and ("80",) in listens:
+        return "http"
+    return "ambiguous"
+
+
+def redirected(block, domain):
+    """Certbot's own redirect test: `if ($host = <domain>) { return 301 https://$host$request_uri; }`."""
+    condition = ("($host", "=", domain + ")")
+    return any(name == "if" and arguments == condition and children == REDIRECT
+               for name, arguments, children in block)
+
+
+def loaded_configuration(command=LOADED):
+    """`nginx -T`: every file nginx loads from disk, each after a `# configuration file <path>:` line, and the
+    test's warnings. The dump holds secrets such as ingress tokens, so it stays in this process's memory."""
+    result = subprocess.run(command, capture_output=True, timeout=30, check=True)
+    return result.stdout, result.stderr
+
+
+def named(text, domain):
+    """How many `server_name` words name the domain, or None when that count could be wrong.
+
+    Directives are only scanned, never parsed. nginx loads a `server_name` directive only where a token can start,
+    spelled bare or quoted, and ends it at a `;`; the scan takes every such place, in comments and strings too, so
+    a commented-out name counts, while a reference such as an upstream host is not a server_name. Up to the first
+    `;`, nginx reads exactly the words between blanks, unquoting a word a pair of quotes holds whole, unless a
+    `#`, another quote or a backslash before a blank or that `;` could end the statement later or change a name
+    (`server_name a # b;` goes on to the next line). Any of those is doubt, whatever the statement names, and so is
+    a quoted directive name, whose closing quote stands as a word of its own; a regular expression's own escapes
+    are not. nginx and Certbot take `.<domain>` for the domain itself. Only exact names count: a wildcard or a
+    regular expression that also matches the domain is not a duplicate, because Certbot (like nginx) ranks the
+    exact-name block above it for both the certificate and the port-80 redirect, so the install would edit the
+    managed block anyway and skipping it changes neither.
+    """
+    wanted, count = {domain.encode(), b"." + domain.encode()}, 0
+    for match in SERVER_NAME.finditer(text):
+        end = match.end()
+        stop = text.find(b";", end)
+        if stop < 0:
+            continue  # no directive nginx loads lacks its `;`
+        for word in WORD.findall(text, end, stop):
+            if not READABLE_NAME.fullmatch(word):
+                return None
+            count += word.strip(b"\"'").lower() in wanted
+    return count
+
+
+def named_elsewhere(path, domain, loaded):
+    """Doubt unless the loaded configuration names the domain only in this file, loaded once.
+
+    Certbot weighs every server block nginx loads, whichever `include` reaches it, so this reads the whole
+    configuration as `nginx -T` dumps it, not one directory, and a statement `named` cannot count anywhere in it,
+    this file included, is doubt. The whole dump is counted against this file, so a section line written inside
+    another file cannot hide a name; nginx dumps a file once however often it is included, and warns when a
+    second copy conflicts.
+    """
+    dump, warnings = loaded
+    here = named(path.read_bytes(), domain)
+    return (DUMPED_FILE.findall(dump).count(os.fsencode(path)) != 1 or here is None or here != named(dump, domain)
+            or b'conflicting server name "' + domain.encode() + b'"' in warnings.lower())
+
+
+def configured(servers, domain, fullchain, privkey):
+    roles = [role(block, domain) for block in servers]
+    if not servers or "ambiguous" in roles or roles.count("tls") > 1 or roles.count("http") > 1:
+        return "ambiguous"
+    if "tls" not in roles:
+        return "http_only"
+    tls = servers[roles.index("tls")]
+    certificates, keys = values(tls, "ssl_certificate"), values(tls, "ssl_certificate_key")
+    if len(certificates) != 1 or len(keys) != 1:
+        return "ambiguous"
+    if certificates != [(fullchain,)] or keys != [(privkey,)]:
+        return "other_certificate"
+    if "http" not in roles or not redirected(servers[roles.index("http")], domain):
+        return "no_redirect"
+    return "current"
+
+
+def leaf_certificate(fullchain):
+    """DER of the lineage's first certificate, which nginx presents as the leaf."""
+    match = PEM_CERTIFICATE.search(Path(fullchain).read_text(encoding="ascii"))
+    return ssl.PEM_cert_to_DER_cert(match.group(0)) if match else b""
+
+
+def paired(fullchain, privkey):
+    """Load the lineage as nginx does: a key that does not match the leaf fails the next reload host-wide.
+
+    The empty password refuses an encrypted key at once instead of prompting for one.
+    """
+    try:
+        ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER).load_cert_chain(fullchain, privkey, password=b"")
+    except ssl.SSLError:
+        return False
+    return True
+
+
+def served_certificate(domain, origin=ORIGIN):
+    """DER of the certificate the running nginx presents for this name; the file alone may not be loaded."""
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+    with socket.create_connection(origin, timeout=5) as connection:
+        with context.wrap_socket(connection, server_hostname=domain) as tls:
+            return tls.getpeercert(binary_form=True)
+
+
+def state(vhost, domain, fullchain, privkey, probe=served_certificate, dump=loaded_configuration):
+    path = Path(vhost)
+    if not DOMAIN.fullmatch(domain) or not all(value.startswith("/") for value in (vhost, fullchain, privkey)):
+        return "ambiguous"
+    if path.is_symlink() or (path.exists() and not path.is_file()):
+        return "ambiguous"
+    if not path.exists():
+        return "absent"
+    entries = parse(path.read_text(encoding="utf-8"))
+    if any(name not in ("map", "server") or children is None for name, _, children in entries):
+        return "ambiguous"
+    servers = [children for name, _, children in entries if name == "server"]
+    result = configured(servers, domain, fullchain, privkey)
+    if result != "current":
+        return result
+    leaf = leaf_certificate(fullchain) if os.path.isfile(fullchain) and os.path.isfile(privkey) else b""
+    if not leaf or not paired(fullchain, privkey):
+        return "lineage_unreadable"
+    try:
+        live = probe(domain)
+    except OSError:
+        return "unreachable"
+    if live != leaf:
+        return "not_served"
+    # Last: the handshake is cheap, while the dump loads and tests the host's whole configuration.
+    try:
+        loaded = dump()
+    except (OSError, subprocess.SubprocessError):
+        return "config_unknown"
+    return "duplicate" if named_elsewhere(path, domain, loaded) else "current"
+
+
+def main(arguments, probe=served_certificate, dump=loaded_configuration):
+    if len(arguments) != 4:
+        return "ambiguous"
+    try:
+        return state(*arguments, probe=probe, dump=dump)
+    except ValueError:
+        return "unparsable"
+    except OSError:
+        return "unreadable"
+
+
+if __name__ == "__main__":
+    print(main(sys.argv[1:]))

package/backend-action/configure_vhost.py

@@ -4,10 +4,15 @@ import os
 from pathlib import Path
 import re
 import stat
+import subprocess
 import sys
 import tempfile
 
 
+class NginxRejected(Exception):
+    """nginx refused the updated vhost; the previous file is back in place."""
+
+
 def transport(text, domain):
     variable = "$gowalk_backend_connection_" + hashlib.sha256(domain.encode()).hexdigest()[:16]
     mapping = f"map $http_upgrade {variable} {{\n    default upgrade;\n    '' close;\n}}\n\n"
@@ -59,29 +64,52 @@ def content(previous, domain, port):
 """, domain)
 
 
-def configure(path, domain, port):
-    if path.is_symlink():
-        raise ValueError("managed vhost must not be a symlink")
-    previous = path.read_text() if path.exists() else ""
-    updated = content(previous, domain, port)
-    if previous == updated:
-        return "unchanged"
-    mode = stat.S_IMODE(path.stat().st_mode) if path.exists() else 0o644
+def replace(path, data, mode):
     fd, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
     try:
-        with os.fdopen(fd, "w") as output:
+        with os.fdopen(fd, "wb") as output:
             os.fchmod(output.fileno(), mode)
-            output.write(updated)
+            output.write(data)
             output.flush()
             os.fsync(output.fileno())
         os.replace(temporary, path)
     finally:
         Path(temporary).unlink(missing_ok=True)
+
+
+def configure(path, domain, port, run=subprocess.run):
+    """Write the vhost, then test and reload nginx; on any failure restore the previous file, as edge does.
+
+    A change nginx refuses must not stay on disk: every later `nginx -t` on the host, this deploy's own
+    certificate step included, would fail on it, and the next deploy would find the file unchanged. The test
+    and reload run here, in one process that writes nothing to the deploy's output, so a cancelled deploy's
+    dropped SSH session cannot stop between them.
+    """
+    if path.is_symlink():
+        raise ValueError("managed vhost must not be a symlink")
+    previous = path.read_text() if path.exists() else ""
+    updated = content(previous, domain, port)
+    if previous == updated:
+        return "unchanged"
+    saved = path.read_bytes() if path.exists() else None
+    mode = stat.S_IMODE(path.stat().st_mode) if saved is not None else 0o644
+    replace(path, updated.encode(), mode)
+    try:
+        run(["nginx", "-t"], capture_output=True, timeout=30, check=True)
+        run(["systemctl", "reload", "nginx"], capture_output=True, timeout=30, check=True)
+    except (OSError, subprocess.SubprocessError):
+        if saved is None:
+            path.unlink(missing_ok=True)
+        else:
+            replace(path, saved, mode)
+        raise NginxRejected from None
     return "changed"
 
 
 if __name__ == "__main__":
     try:
         print(configure(Path(sys.argv[1]), sys.argv[2], int(sys.argv[3])))
+    except NginxRejected:
+        sys.exit("nginx rejected the managed vhost update; the previous vhost is restored")
     except (OSError, ValueError):
         sys.exit("Cannot update the managed nginx vhost; its domain and upstream must be unambiguous")

package/backend-action/edge_vhost.py

@@ -1,13 +1,11 @@
 """Protect a distinct edge vhost while retaining an app's released direct-host address."""
-import os
 from pathlib import Path
 import re
 import stat
 import subprocess
 import sys
-import tempfile
 
-from configure_vhost import content
+from configure_vhost import content, replace
 from edge_inputs import load
 
 NGINX_DIR = Path("/etc/nginx/conf.d")
@@ -71,19 +69,6 @@ def edge_content(text, domain, port, include):
     return updated
 
 
-def replace(path, data, mode):
-    fd, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
-    try:
-        with os.fdopen(fd, "wb") as output:
-            os.fchmod(output.fileno(), mode)
-            output.write(data)
-            output.flush()
-            os.fsync(output.fileno())
-        os.replace(temporary, path)
-    finally:
-        Path(temporary).unlink(missing_ok=True)
-
-
 def planned(config, app, domain, port, nginx_dir=NGINX_DIR):
     value = validate(config, app, domain, nginx_dir)
     if value["ingress_required"] != "true":

package/backend-action/ensure_certificate.sh

@@ -54,6 +54,23 @@ certbot_attempt() {
   return "$status"
 }
 
+# A skipped install still does to nginx what the install did on every deploy: test the configuration, then
+# reload it, so a change on disk the running nginx never loaded is loaded now. The commands' own output stays
+# private; a failure ends the deploy as a failed install did, with its status and the fixed cause Certbot
+# reports for a failed nginx test or reload.
+nginx_attempt() {
+  local phase="$1" attempt="$2" status
+  shift 2
+  if "$@" > "$CERTBOT_WORK/stdout" 2> "$CERTBOT_WORK/stderr"; then
+    log "certificate phase=$phase attempt=$attempt state=ok exit=0"
+    return 0
+  else
+    status=$?
+  fi
+  log "certificate phase=$phase attempt=$attempt state=error exit=$status cause=nginx_restart"
+  return "$status"
+}
+
 certificate_present() {
   # 0=present, 1=confirmed absent, 2=unrecognized/partial inventory; preserve other awk failures.
   awk -v domain="$1" -v emit_name="${2:-}" '
@@ -109,6 +126,41 @@ certificate_present() {
   ' "$CERTBOT_WORK/stdout"
 }
 
+# Print the lineage's certificate and key paths, one per line, exactly as `certbot install` deploys them.
+certificate_paths() {
+  awk -v name="$1" '
+    $1 == "Certificate" && $2 == "Name:" {
+      current = $0; sub(/^[[:space:]]*Certificate Name:[[:space:]]*/, "", current)
+      if (current == name) records++
+      next
+    }
+    current != name { next }
+    $1 == "Certificate" && $2 == "Path:" { chains++; chain = NF == 3 ? $3 : "" }
+    $1 == "Private" && $2 == "Key" && $3 == "Path:" { keys++; key = NF == 4 ? $4 : "" }
+    END {
+      if (records != 1 || chains != 1 || keys != 1 || chain == "" || key == "") exit 1
+      print chain; print key
+    }
+  ' "$CERTBOT_WORK/stdout"
+}
+
+# A repeated `install --nginx` saves a checkpoint of every nginx file on the host even when it changes
+# nothing. Only `current` skips it: the vhost holds exactly this lineage behind Certbot's redirect, the
+# running nginx presents that certificate for the name, and no other loaded server block names it.
+certificate_vhost_state() {
+  local domain="$1" name="$2" vhost="$3" paths state
+  [ -n "$vhost" ] || { printf 'no_vhost'; return 0; }
+  paths="$(certificate_paths "$name")" || { printf 'lineage_unknown'; return 0; }
+  state="$(python3 "$(dirname "${BASH_SOURCE[0]}")/certificate_vhost.py" "$vhost" "$domain" \
+    "${paths%%$'\n'*}" "${paths#*$'\n'}" 2>/dev/null)" || state=check_failed
+  case "$state" in
+    current|absent|http_only|other_certificate|no_redirect|lineage_unreadable|duplicate) ;;
+    config_unknown|not_served|unreachable|ambiguous|unparsable|unreadable) ;;
+    *) state=check_failed ;;
+  esac
+  printf '%s' "$state"
+}
+
 request_certificate() {
   local domain="$1" email="$2" attempt="$3" account
   # Certbot tells the CA to validate one second after reloading nginx by default. A host with
@@ -125,7 +177,7 @@ request_certificate() {
 }
 
 ensure_certificate() (
-  local domain="$1" email="$2" delay name attempt=0 status=1 CERTBOT_WORK
+  local domain="$1" email="$2" vhost="${3:-}" delay name vhost_state attempt=0 status=1 CERTBOT_WORK
   CERTBOT_WORK="$(mktemp -d "${TMPDIR:-/tmp}/gowalk-certbot.XXXXXXXX")" || return $?
   trap 'rm -rf -- "$CERTBOT_WORK"' EXIT
   trap 'exit 130' INT
@@ -140,6 +192,14 @@ ensure_certificate() (
     if certbot_attempt inventory "$attempt" certificates; then
       if name="$(certificate_present "$domain" name)"; then
         log "cert for $domain already present"
+        vhost_state="$(certificate_vhost_state "$domain" "$name" "$vhost")"
+        if [ "$vhost_state" = current ]; then
+          log "certificate phase=installation attempt=$attempt state=skipped vhost=current"
+          nginx_attempt nginx_test "$attempt" nginx -t || return $?
+          nginx_attempt nginx_reload "$attempt" systemctl reload nginx || return $?
+          return 0
+        fi
+        log "certificate phase=installation attempt=$attempt state=required vhost=$vhost_state"
         # Inventory proves possession, not nginx installation. Repair an HTTP-only legacy vhost too.
         if certbot_attempt installation "$attempt" install --nginx --cert-name "$name" \
             -d "$domain" --non-interactive --redirect; then

package/backend-action/remote_deploy.sh

@@ -26,8 +26,9 @@ log "host $(python3 --version)"
 
 # Refuse a missing ingress token or an older unprotected workflow before Compose changes.
 EDGE_CONFIG="/opt/gowalk-backend-ingress/$APP/.backend-edge.json"
+EDGE_VHOST="/etc/nginx/conf.d/backend-$APP-edge.conf"
 EDGE_MODE=legacy
-if [ -f "$EDGE_CONFIG" ] || [ -e "/etc/nginx/conf.d/backend-$APP-edge.conf" ]; then
+if [ -f "$EDGE_CONFIG" ] || [ -e "$EDGE_VHOST" ]; then
   python3 "$DIR/edge_vhost.py" validate "$EDGE_CONFIG" "$APP" "$DOMAIN"
   EDGE_MODE="$(python3 "$DIR/edge_inputs.py" mode "$EDGE_CONFIG")"
   python3 "$DIR/edge_inputs.py" runtime "$EDGE_CONFIG"
@@ -101,19 +102,23 @@ fi
 # ── nginx vhost → proxy the domain to the published port
 BACKEND_DEPLOY_PHASE=configure_vhost
 VHOST="/etc/nginx/conf.d/backend-$APP.conf"
+CERT_VHOST="$VHOST"
 if [ "${EDGE_MODE:-legacy}" = edge ]; then
+  CERT_VHOST="$EDGE_VHOST"
   python3 "$DIR/edge_vhost.py" configure "$EDGE_CONFIG" "$APP" "$DOMAIN" "$PORT"
 else
+  # Tests and reloads nginx itself after a change, restoring the previous file on failure, so a change nginx
+  # refuses never stays on disk to fail the host's next test.
   VHOST_STATE="$(python3 "$DIR/configure_vhost.py" "$VHOST" "$DOMAIN" "$PORT")"
   if [ "$VHOST_STATE" = changed ]; then
     log "updated nginx upstream for $DOMAIN → 127.0.0.1:$PORT"
-    nginx -t && systemctl reload nginx
   fi
 fi
 
 # ── Let's Encrypt cert: failed inventory is never absence; only lock contention retries.
+# The domain's own vhost tells whether `certbot install` would change anything.
 BACKEND_DEPLOY_PHASE=certificate
-if ensure_certificate "$DOMAIN" "$CERT_EMAIL"; then
+if ensure_certificate "$DOMAIN" "$CERT_EMAIL" "$CERT_VHOST"; then
   log "certificate ready for $DOMAIN"
 else
   status=$?