gowalk-cicd 1.0.175 → 1.0.176

package/README.md

@@ -521,6 +521,9 @@ The backend message is `gowalk-cicd/backend-deploy-failed.v1 phase=<phase> exit_
 fixed fields without JSON braces, which GitHub can mask when a multiline secret has brace-only lines.
 Consumers validate the complete envelope, the known phase and exit code 1–255; older JSON messages
 remain readable by the panel. Masked fields are never reconstructed and credential masking stays enabled.
+Protected vhost failures add `backend_vhost_failed` (`gowalk-cicd/backend-vhost-failed.v1`) with fixed
+brace-free `operation`, `stage`, `reason`, `child_exit` and `signals`; see `docs/BACKEND_EDGE.md`.
+It preserves the existing refusal and records only bounded observed facts, never private child output.
 An interrupted locked Pod fetch can retry once within the existing 900-second install budget.
 `native_pods_retry` (`gowalk-cicd/native-pods-retry.v1`) reports `attempt:2` and `reason:partial_transfer`;
 successful preparation reports `pod_attempts`. Dependency locks, relay and TLS checks remain enforced.

package/backend-action/action.yml

@@ -207,6 +207,7 @@ runs:
           "${{ github.action_path }}/runtime_env.py" \
           "${{ github.action_path }}/runtime_env_parse.py" \
           "${{ github.action_path }}/edge_vhost.py" \
+          "${{ github.action_path }}/vhost_diagnostics.py" \
           "${{ github.action_path }}/edge_health.py" \
           "${{ github.action_path }}/deploy_evidence.sh" \
           "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/"

package/backend-action/edge_vhost.py

@@ -7,6 +7,7 @@ import sys
 
 from configure_vhost import content, replace
 from edge_inputs import load
+from vhost_diagnostics import observing
 
 NGINX_DIR = Path("/etc/nginx/conf.d")
 
@@ -70,56 +71,67 @@ def edge_content(text, domain, port, include, stage="update"):
 
 
 def planned(config, app, domain, port, nginx_dir=NGINX_DIR, stage="update"):
-    value = validate(config, app, domain, nginx_dir)
-    if value["ingress_required"] != "true":
-        raise ValueError("backend_ingress_configuration_required")
-    legacy, edge, include = paths(config, app, nginx_dir)
-    token = value["ingress_token"]
-    guard = (f'if ($http_x_app_robot_backend_token != "{token}") {{ return 403; }}\n'
-             'proxy_set_header X-App-Robot-Backend-Token "";\n')
-    files = {include: (guard.encode(), 0o600),
-             edge: (edge_content(previous(edge), domain, port, include, stage).encode(), 0o644)}
-    old_domain = recorded_domain(legacy)
-    if old_domain:
-        files[legacy] = (content(previous(legacy), old_domain, port).encode(),
-                         stat.S_IMODE(legacy.stat().st_mode))
-    return files
+    with observing("validate", stage):
+        value = validate(config, app, domain, nginx_dir)
+    with observing("plan", stage):
+        if value["ingress_required"] != "true":
+            raise ValueError("backend_ingress_configuration_required")
+        legacy, edge, include = paths(config, app, nginx_dir)
+        token = value["ingress_token"]
+        guard = (f'if ($http_x_app_robot_backend_token != "{token}") {{ return 403; }}\n'
+                 'proxy_set_header X-App-Robot-Backend-Token "";\n')
+        files = {include: (guard.encode(), 0o600),
+                 edge: (edge_content(previous(edge), domain, port, include, stage).encode(), 0o644)}
+        old_domain = recorded_domain(legacy)
+        if old_domain:
+            files[legacy] = (content(previous(legacy), old_domain, port).encode(),
+                             stat.S_IMODE(legacy.stat().st_mode))
+        return files
 
 
 def configure(config, app, domain, port, nginx_dir=NGINX_DIR, run=subprocess.run, stage="update"):
     files = planned(config, app, domain, port, nginx_dir, stage)
-    saved = {path: ((path.read_bytes(), stat.S_IMODE(path.stat().st_mode)) if path.exists() else None)
-             for path in files}
-    changes = {path: value for path, value in files.items() if saved[path] != value}
+    with observing("plan", stage):
+        saved = {path: ((path.read_bytes(), stat.S_IMODE(path.stat().st_mode)) if path.exists() else None)
+                 for path in files}
+        changes = {path: value for path, value in files.items() if saved[path] != value}
     if not changes:
         return "unchanged"
     try:
-        for path, (data, mode) in changes.items():
-            replace(path, data, mode)
-        run(["nginx", "-t"], capture_output=True, timeout=30, check=True)
-        run(["systemctl", "reload", "nginx"], capture_output=True, timeout=30, check=True)
+        with observing("write", stage):
+            for path, (data, mode) in changes.items():
+                replace(path, data, mode)
+        with observing("nginx_test", stage):
+            run(["nginx", "-t"], capture_output=True, timeout=30, check=True)
+        with observing("nginx_reload", stage):
+            run(["systemctl", "reload", "nginx"], capture_output=True, timeout=30, check=True)
     except (OSError, subprocess.SubprocessError):
-        for path in changes:
-            if saved[path] is None:
-                path.unlink(missing_ok=True)
-            else:
-                replace(path, *saved[path])
+        with observing("rollback", stage):
+            for path in changes:
+                if saved[path] is None:
+                    path.unlink(missing_ok=True)
+                else:
+                    replace(path, *saved[path])
         raise ValueError("backend_edge_nginx_failed") from None
     return "changed"
 
 
 def main():
-    operation, config, app, domain = sys.argv[1:5]
+    stage = (sys.argv[6:7] or ["update"])[0]
+    with observing("validate", stage):
+        operation, config, app, domain = sys.argv[1:5]
+        if operation not in {"validate", "configure"}:
+            raise ValueError("backend_edge_operation_invalid")
+        port = int(sys.argv[5]) if operation == "configure" else None
     if operation == "validate":
-        validate(config, app, domain)
+        with observing("validate", stage):
+            validate(config, app, domain)
     elif operation == "configure":
-        print(configure(config, app, domain, int(sys.argv[5]), stage=(sys.argv[6:7] or ["update"])[0]))
-    else:
-        raise ValueError("backend_edge_operation_invalid")
+        print(configure(config, app, domain, port, stage=stage))
 
 
 if __name__ == "__main__":
     try:
         main()
-    except (OSError, ValueError):
+    except (OSError, ValueError, IndexError):
         sys.exit("backend_edge_vhost_refused")

package/backend-action/vhost_diagnostics.py

@@ -0,0 +1,90 @@
+"""Fixed vhost failure facts; private child output and exception text never leave this process."""
+from contextlib import contextmanager
+import errno
+import subprocess
+import sys
+
+OPERATIONS = frozenset({"validate", "plan", "write", "nginx_test", "nginx_reload", "rollback"})
+STAGES = frozenset({"update", "acme", "tls"})
+REFUSALS = frozenset({
+    "backend_app_invalid", "backend_vhost_symlink", "backend_vhost_identity_invalid",
+    "backend_ingress_downgrade_refused", "backend_edge_domain_must_be_distinct", "backend_edge_domain_changed",
+    "backend_ingress_path_invalid", "backend_edge_vhost_invalid", "backend_edge_location_invalid",
+    "backend_ingress_configuration_required", "backend_edge_operation_invalid", "backend_edge_inputs_invalid",
+    "backend_ingress_required_invalid", "backend_build_sha_invalid", "backend_public_health_invalid",
+    "backend_public_base_invalid", "backend_public_health_base_mismatch", "backend_edge_config_symlink",
+    "backend_edge_config_invalid",
+})
+CONTENT_REFUSALS = {
+    "invalid domain, port or stage": "input_invalid",
+    "vhost belongs to another domain": "vhost_identity_invalid",
+    "managed transport directive is not unique": "transport_ambiguous",
+    "managed connection map is not recognized": "connection_map_invalid",
+    "managed upstream is not unique": "upstream_ambiguous",
+}
+FILESYSTEM = {
+    errno.ENOENT: "file_missing", errno.EACCES: "permission_denied", errno.EPERM: "permission_denied",
+    errno.EROFS: "filesystem_readonly", errno.ENOSPC: "storage_full", errno.EIO: "io_failure",
+}
+NGINX_SIGNALS = (
+    ("certificate_load", ("cannot load certificate",)),
+    ("certificate_key_mismatch", ("key values mismatch",)),
+    ("configuration_syntax", ("unknown directive", "unexpected end of file", "invalid number of arguments",
+                              "is not allowed here", "unexpected \"}", "unexpected \";")),
+    ("listener_in_use", ("address already in use",)),
+    ("permission_denied", ("permission denied",)),
+    ("upstream_resolution", ("host not found in upstream",)),
+)
+OUTPUT_LIMIT = 16 * 1024
+
+
+def classify(error):
+    if isinstance(error, subprocess.TimeoutExpired):
+        return "timeout", "none"
+    if isinstance(error, subprocess.CalledProcessError):
+        code = error.returncode
+        return "command_failed", str(code) if type(code) is int and -255 <= code <= 255 and code else "none"
+    if isinstance(error, OSError):
+        code = error.errno
+        return FILESYSTEM.get(code, "unclassified") if type(code) is int else "unclassified", "none"
+    message = error.args[0] if len(error.args) == 1 and type(error.args[0]) is str else ""
+    message = message if len(message) <= 96 else ""
+    return message if message in REFUSALS else CONTENT_REFUSALS.get(message, "unclassified"), "none"
+
+
+def nginx_signals(error, operation):
+    if operation != "nginx_test" or not isinstance(error, subprocess.CalledProcessError):
+        return "none"
+    output = error.stderr
+    if type(output) is bytes:
+        output = output[:OUTPUT_LIMIT].decode("utf-8", errors="replace")
+    elif type(output) is str:
+        output = output[:OUTPUT_LIMIT].encode("utf-8", errors="replace")[:OUTPUT_LIMIT]
+        output = output.decode("utf-8", errors="replace")
+    else:
+        return "none"
+    output = output.lower()
+    signals = [code for code, patterns in NGINX_SIGNALS if any(pattern in output for pattern in patterns)]
+    return ",".join(signals) or "none"
+
+
+def report(operation, stage, error):
+    operation = operation if type(operation) is str and operation in OPERATIONS else "unclassified"
+    stage = stage if type(stage) is str and stage in STAGES else "unclassified"
+    reason, child_exit = classify(error)
+    signals = nginx_signals(error, operation)
+    message = ("::error title=backend_vhost_failed::gowalk-cicd/backend-vhost-failed.v1 "
+               "operation={} stage={} reason={} child_exit={} signals={}\n")
+    try:
+        sys.stderr.write(message.format(operation, stage, reason, child_exit, signals))
+    except (OSError, ValueError):
+        pass  # Diagnostic delivery must not replace the original refusal.
+
+
+@contextmanager
+def observing(operation, stage):
+    try:
+        yield
+    except (OSError, ValueError, IndexError, subprocess.SubprocessError) as error:
+        report(operation, stage, error)
+        raise

package/docs/BACKEND_EDGE.md

@@ -44,3 +44,16 @@ while preserving their domains, TLS settings and ingress checks.
 These options are also named backend settings in `.gowalk-cicd.yml`: `public-base-url`,
 `public-health-url`, `expected-build-sha`, `ingress-required` and `ingress-token`. Reference secrets
 by name. Deployments without these options retain public origin access, certificate handling and health checks.
+
+Edge-vhost refusals also emit the fixed stderr annotation `backend_vhost_failed` with schema
+`gowalk-cicd/backend-vhost-failed.v1`. Its brace-free fields are `operation`, `stage`, `reason`,
+`child_exit` and `signals`. Operations are validate, plan, write, nginx_test, nginx_reload and rollback;
+stages are update, acme and tls. Unknown metadata or reasons remain unclassified. `child_exit` is the
+observed nonzero child status (-255 to 255), or `none`; it does not change the CLI's failed exit 1.
+Reasons retain allowlisted planning refusals or fixed filesystem, timeout and command-failure facts.
+Signals inspect only the first 16 KiB of failed nginx-test stderr and emit certificate_load,
+certificate_key_mismatch, configuration_syntax, listener_in_use, permission_denied or upstream_resolution.
+They are observed patterns, not a unique cause or retry permission. No raw error, command, host, path,
+token or child output is included. A failed restoration adds a separate rollback refusal while keeping
+the original failure visible; absence of that extra line alone does not prove successful restoration.
+The generic `backend_edge_vhost_refused`, changed/unchanged stdout, ingress, TLS and deploy gates remain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.175",
+  "version": "1.0.176",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {