@le-space/rootfs 0.9.5 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@le-space/rootfs",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Shared rootfs contract parsing, reference profile assets, and build helpers.",
   "license": "MIT",
   "type": "module",

package/reference/orbitdb-relay/rootfs/orbitdb-relay-setup-server.py

@@ -5,6 +5,7 @@ import ipaddress
 import json
 import os
 import subprocess
+import sys
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -92,6 +93,28 @@ def _parse_env_file(path: str) -> dict[str, str]:
     return values
 
 
+def _log(message: str) -> None:
+    """Say it once, on stderr, where journalctl picks it up.
+
+    This file had no logging and the HTTP handler silenced its own, so a relay
+    that never configured itself left a journal with one "Started" line in it.
+    That silence is what made "the guest never acknowledged" an unexplainable
+    failure rather than a readable one.
+    """
+    print(f"[bootstrap] {message}", file=sys.stderr, flush=True)
+
+
+_LOGGED_ONCE: set[str] = set()
+
+
+def _log_once(key: str, message: str) -> None:
+    """For states that repeat every few seconds and are worth saying once."""
+    if key in _LOGGED_ONCE:
+        return
+    _LOGGED_ONCE.add(key)
+    _log(message)
+
+
 def _extract_guest_bootstrap_locator() -> tuple[str | None, str | None]:
     """Read the deployment locator the deployer left in our SSH key.
 
@@ -112,9 +135,15 @@ def _extract_guest_bootstrap_locator() -> tuple[str | None, str | None]:
                         deployment_token = deployment_token.strip()
                         if owner_address and deployment_token:
                             return owner_address, deployment_token
-    except (FileNotFoundError, ValueError):
+    except (FileNotFoundError, ValueError) as error:
+        _log_once("locator-error", f"cannot read {AUTHORIZED_KEYS_FILE}: {error!r}")
         return None, None
 
+    _log_once(
+        "locator-missing",
+        f"no aleph-bootstrap-config marker in {AUTHORIZED_KEYS_FILE}; "
+        "nothing to poll for, the relay will stay unconfigured",
+    )
     return None, None
 
 
@@ -374,6 +403,10 @@ def _load_vm_bootstrap_record() -> tuple[str | None, str | None, dict | None]:
 
 
 def _poll_bootstrap_config_loop() -> None:
+    _log(
+        f"waiting for bootstrap config, polling every {BOOTSTRAP_CONFIG_POLL_SECONDS}s "
+        f"against {ALEPH_API_HOST}"
+    )
     while not os.path.exists(READY_FILE):
         _, deployment_token, record = _load_vm_bootstrap_record()
         if deployment_token and isinstance(record, dict):
@@ -381,12 +414,20 @@ def _poll_bootstrap_config_loop() -> None:
             if status == "pending":
                 try:
                     args = _build_configure_args_from_record(record)
-                except ValueError:
+                except ValueError as error:
+                    # The record arrived and was unusable — which used to look
+                    # exactly like never having received one.
+                    _log_once("record-invalid", f"record cannot be turned into a config: {error}")
                     time.sleep(BOOTSTRAP_CONFIG_POLL_SECONDS)
                     continue
-                ok, _ = _run_configure_process(args, record)
+                _log("record found and pending, configuring the relay now")
+                ok, detail = _run_configure_process(args, record)
                 if ok:
+                    _log("relay configured, setup endpoint is done")
                     return
+                _log(f"configure failed, will retry: {detail}")
+            else:
+                _log_once(f"status-{status}", f"record status is {status!r}, not acting on it")
         time.sleep(BOOTSTRAP_CONFIG_POLL_SECONDS)
 
 

package/reference/uc-go-peer/rootfs/uc-go-peer-autotls-refresh.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 import os
 import re
+import sys
 import subprocess
 import time
 from typing import Iterable
@@ -93,6 +94,57 @@ def wait_for_exact_hosts(ws_port: str) -> tuple[str, list[str], list[str]]:
     raise RuntimeError(last_error)
 
 
+def resolve_external_ws_port(env_values: dict[str, str], ws_port: str) -> str:
+    """Port the AutoTLS websocket should be *announced* on.
+
+    `ws_port` is where the relay actually listens inside the guest. On Aleph
+    every port is published under a different number, so announcing the
+    internal one hands out an address the internet cannot reach.
+    """
+    external = env_values.get("EXTERNAL_RELAY_WS_PORT", "").strip()
+    if external:
+        return external
+    print(
+        f"[autotls] EXTERNAL_RELAY_WS_PORT is missing from the environment file; "
+        f"announcing the backend port {ws_port}, which is unreachable from "
+        f"outside the guest whenever the port is mapped",
+        file=sys.stderr,
+    )
+    return ws_port
+
+
+def build_announce_addrs(
+    existing_announce: Iterable[str],
+    logged_addrs: Iterable[str],
+    ws_port: str,
+    external_ws_port: str,
+    proxy_hostname: str = "",
+) -> list[str]:
+    """Announce list for the concrete AutoTLS hostnames.
+
+    The relay logs its listeners on the internal port, which is what the log
+    scan had to match to find them. Re-announcing those strings verbatim was
+    the defect: `uc-go-peer-configure.sh` translates the port for every other
+    family, so tcp, quic, webtransport and webrtc-direct all advertised the
+    mapped port while the websocket — rewritten here, later — kept the
+    internal one. Measured on a live relay: `/tcp/9097/tls/sni/…/ws` was
+    announced and filtered, while the same listener answered on `/tcp/24013`.
+    Browsers dropped the address, `direct-wss` was left without a candidate,
+    and js-peer refused to bake a bootstrap list it could not verify.
+    """
+    wildcard_filtered = [entry for entry in existing_announce if "/tls/sni/*." not in entry]
+    exact_announces = [
+        addr.replace(f"/tcp/{ws_port}/", f"/tcp/{external_ws_port}/", 1)
+        for addr in logged_addrs
+    ]
+
+    if proxy_hostname:
+        exact_announces.append(f"/dns4/{proxy_hostname}/tcp/443/tls/ws")
+        exact_announces.append(f"/dns6/{proxy_hostname}/tcp/443/tls/ws")
+
+    return dedupe(list(wildcard_filtered) + exact_announces)
+
+
 def main() -> None:
     if not os.path.exists(READY_FILE):
         raise SystemExit(f"missing ready file: {READY_FILE}")
@@ -109,14 +161,13 @@ def main() -> None:
         raise RuntimeError("no AutoTLS websocket hostnames found in logs")
 
     existing = [entry.strip() for entry in env_values.get("LIBP2P_ANNOUNCE_ADDRS", "").split(",") if entry.strip()]
-    wildcard_filtered = [entry for entry in existing if "/tls/sni/*." not in entry]
-    exact_announces: list[str] = list(exact_logged_addrs)
-
-    if proxy_hostname:
-        exact_announces.append(f"/dns4/{proxy_hostname}/tcp/443/tls/ws")
-        exact_announces.append(f"/dns6/{proxy_hostname}/tcp/443/tls/ws")
-
-    merged = dedupe(wildcard_filtered + exact_announces)
+    merged = build_announce_addrs(
+        existing,
+        exact_logged_addrs,
+        ws_port,
+        resolve_external_ws_port(env_values, ws_port),
+        proxy_hostname,
+    )
     announce_value = ",".join(merged)
     write_env_var(ENV_FILE, "LIBP2P_ANNOUNCE_ADDRS", announce_value)
     if zone:

package/reference/uc-go-peer/rootfs/uc-go-peer-setup-server.py

@@ -5,6 +5,7 @@ import ipaddress
 import json
 import os
 import subprocess
+import sys
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -85,6 +86,29 @@ def _validate_proxy_hostname(value: object) -> str | None:
     return parsed.hostname
 
 
+def _log(message: str) -> None:
+    """Say it once, on stderr, where journalctl picks it up.
+
+    This file had no logging at all, and the HTTP handler silenced its own.
+    That is how a relay can sit for hours doing nothing while `journalctl -u
+    uc-go-peer-bootstrap` shows a single "Started" line — which is what it did
+    on 2026-09-02, leaving no way to tell whether the guest had found its
+    locator, asked Aleph and been told nothing, or never looked.
+    """
+    print(f"[bootstrap] {message}", file=sys.stderr, flush=True)
+
+
+_LOGGED_ONCE: set[str] = set()
+
+
+def _log_once(key: str, message: str) -> None:
+    """For states that repeat every few seconds and are worth saying once."""
+    if key in _LOGGED_ONCE:
+        return
+    _LOGGED_ONCE.add(key)
+    _log(message)
+
+
 def _extract_guest_bootstrap_locator() -> tuple[str | None, str | None]:
     try:
         with open(AUTHORIZED_KEYS_FILE, encoding="utf-8") as handle:
@@ -98,10 +122,25 @@ def _extract_guest_bootstrap_locator() -> tuple[str | None, str | None]:
                         owner_address = owner_address.strip()
                         deployment_token = deployment_token.strip()
                         if owner_address and deployment_token:
+                            _log_once(
+                                "locator",
+                                f"locator found in authorized_keys: owner={owner_address} "
+                                f"token={deployment_token}",
+                            )
                             return owner_address, deployment_token
-    except (FileNotFoundError, ValueError):
+    except (FileNotFoundError, ValueError) as error:
+        _log_once("locator-error", f"cannot read {AUTHORIZED_KEYS_FILE}: {error!r}")
         return None, None
 
+    # Without this the guest can never find its record, and every deployment
+    # spends its full config window before failing over. The browser appends
+    # the marker to the SSH key it puts in the instance message; if it is not
+    # here, either no key was configured or something stripped the comment.
+    _log_once(
+        "locator-missing",
+        f"no aleph-bootstrap-config marker in {AUTHORIZED_KEYS_FILE}; "
+        "nothing to poll for, the relay will stay unconfigured",
+    )
     return None, None
 
 
@@ -415,10 +454,13 @@ def _load_vm_bootstrap_record() -> tuple[str | None, str | None, dict | None]:
         with urlopen(request_url, timeout=10) as response:
             payload = json.loads(response.read().decode("utf-8") or "{}")
     except HTTPError as error:
-        if error.code == 404:
-            return owner_address, deployment_token, None
+        # A 404 is ordinary early on: the browser publishes the aggregate only
+        # once the runtime is up. Anything else is worth naming.
+        key = "aggregate-404" if error.code == 404 else f"aggregate-{error.code}"
+        _log_once(key, f"aggregate query returned HTTP {error.code} for {owner_address}")
         return owner_address, deployment_token, None
-    except (URLError, json.JSONDecodeError, TimeoutError):
+    except (URLError, json.JSONDecodeError, TimeoutError) as error:
+        _log_once("aggregate-unreachable", f"aggregate query failed: {error!r}")
         return owner_address, deployment_token, None
 
     aggregate = payload.get("data", {}).get(BOOTSTRAP_CONFIG_KEY, {})
@@ -426,25 +468,47 @@ def _load_vm_bootstrap_record() -> tuple[str | None, str | None, dict | None]:
         return owner_address, deployment_token, None
 
     record = aggregate.get(deployment_token)
-    return owner_address, deployment_token, record if isinstance(record, dict) else None
+    if not isinstance(record, dict):
+        _log_once(
+            "record-missing",
+            f"aggregate has no record for token {deployment_token} "
+            f"({len(aggregate)} record(s) present)",
+        )
+        return owner_address, deployment_token, None
+
+    return owner_address, deployment_token, record
 
 
 def _poll_bootstrap_config_loop() -> None:
+    _log(
+        f"waiting for bootstrap config, polling every {BOOTSTRAP_CONFIG_POLL_SECONDS}s "
+        f"against {ALEPH_API_HOST}"
+    )
     while not os.path.exists(READY_FILE):
         _, deployment_token, record = _load_vm_bootstrap_record()
         if deployment_token and isinstance(record, dict):
             status = str(record.get("status") or "").strip().lower()
             if status != "pending":
+                # Somebody else's turn, or already done. Worth saying once per
+                # status: a record stuck on "applied" while the relay is down
+                # means something very different from no record at all.
+                _log_once(f"status-{status}", f"record status is {status!r}, not acting on it")
                 time.sleep(BOOTSTRAP_CONFIG_POLL_SECONDS)
                 continue
             try:
                 args = _build_configure_args(record)
-            except ValueError:
+            except ValueError as error:
+                # The record arrived and was unusable. Before this, that was
+                # indistinguishable from never having received one.
+                _log_once("record-invalid", f"record cannot be turned into a config: {error}")
                 time.sleep(BOOTSTRAP_CONFIG_POLL_SECONDS)
                 continue
-            ok, _ = _run_configure_process(args, record)
+            _log("record found and pending, configuring the relay now")
+            ok, detail = _run_configure_process(args, record)
             if ok:
+                _log("relay configured, setup endpoint is done")
                 return
+            _log(f"configure failed, will retry: {detail}")
         time.sleep(BOOTSTRAP_CONFIG_POLL_SECONDS)