From 47499031426702cc81a20f349d48800a1c9ca90e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 16 Oct 2026 04:13:45 +0000 Subject: [PATCH 01/12] ci: smoke the gateway /healthz probe on Intel Mac Build the native elastos binary on macos-15-intel and require GET /healthz to return OK. Record why that smoke is not yet a signed x86_64-darwin release. Co-authored-by: Sash --- .github/workflows/ci.yml | 42 ++++++++++ docs/MAC.md | 37 +++++++++ scripts/ci-release-policy-test.py | 3 + scripts/gateway-healthz-smoke-test.py | 113 ++++++++++++++++++++++++++ scripts/gateway-healthz-smoke.sh | 84 +++++++++++++++++++ scripts/test-source-gate.sh | 1 + 6 files changed, 280 insertions(+) create mode 100644 scripts/gateway-healthz-smoke-test.py create mode 100755 scripts/gateway-healthz-smoke.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c9a83ad7f..c29f63ce6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1560,6 +1560,48 @@ jobs: retention-days: 7 if-no-files-found: ignore + # Native Intel Mac proof of the launcher readiness probe. This job builds + # the gateway binary and requires GET /healthz to return OK. It is not a + # signed release. docs/MAC.md records the signer and installer gates. + gateway-smoke-macos-intel: + name: gateway-smoke-macos-intel + runs-on: macos-15-intel + timeout-minutes: 90 + needs: source-gate + env: + CARGO_BUILD_JOBS: "2" + steps: + - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5 + with: + ref: ${{ github.event_name == 'workflow_dispatch' && inputs.ref || github.sha }} + - uses: dtolnay/rust-toolchain@72504271e02fb719eb4eb3eaece3a8e3d06f57c0 # 1.91.0 + - name: require an Intel Mac with room to compile + run: | + set -euo pipefail + [[ "$RUNNER_OS/$RUNNER_ARCH" == macOS/X64 ]] + df -Pk . + df -Pk . | awk 'NR == 2 { if ($4 < 8 * 1024 * 1024) { print "Intel runner has under 8 GiB free"; exit 1 } }' + - name: build the gateway binary + timeout-minutes: 70 + run: | + set -euo pipefail + echo "CARGO_TARGET_DIR=$RUNNER_TEMP/gateway-intel-target" >> "$GITHUB_ENV" + cargo build --locked --release --manifest-path elastos/Cargo.toml -p elastos-server --bin elastos + - name: gateway /healthz returns OK + timeout-minutes: 10 + run: | + set -euo pipefail + export ELASTOS_GATEWAY_LOG="$RUNNER_TEMP/gateway.log" + scripts/gateway-healthz-smoke.sh "$CARGO_TARGET_DIR/release/elastos" + - name: upload gateway log + if: failure() + uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5 + with: + name: gateway-smoke-macos-intel-log + path: ${{ runner.temp }}/gateway.log + retention-days: 7 + if-no-files-found: ignore + # A pull request run stops at its first failed job, so the macOS and Linux # journeys do not run on for 30+ minutes after a decisive failure. Pushes, # merge queues and dispatches keep running every job to the end. This job diff --git a/docs/MAC.md b/docs/MAC.md index aa4e005fe..f1b43bdd6 100644 --- a/docs/MAC.md +++ b/docs/MAC.md @@ -4,6 +4,43 @@ The public installer looks up Apple silicon (`aarch64-darwin`) releases. This runbook is the source-home staging path for local Mac verification, Browser VM artifacts, and `.dmg` packaging work. +## Intel Mac + +An Intel Mac is `x86_64` (`darwin-x64` in launcher platform names, +`x86_64-darwin` in the release platform id, `darwin-amd64` in +`scripts/release-platforms.json`). The signed installer still stops on that +host with `macOS release lookup requires Apple silicon`. + +CI job `gateway-smoke-macos-intel` runs on the GitHub-hosted `macos-15-intel` +runner. It builds the native `elastos` binary, runs +`elastos gateway --addr 127.0.0.1:8090`, and requires `GET /healthz` to return +the body `OK`. That job is a readiness smoke. It does not publish a signed +release, and `ci.yml` still withholds release tarballs from GitHub Releases. + +A native build on `macos-15-intel` does not need a cross compiler. GitHub +keeps that Intel image through the macOS 15 runner retirement. Admitting the +same host to the stable channel needs the signed release path opened together: + +- `scripts/release-signer.py` admits `x86_64-linux`, `aarch64-linux`, and + `aarch64-darwin`. An Intel platform id is refused there. +- `scripts/prepare-release-platform.sh` prepares Linux x86_64, Linux ARM64, and + macOS ARM64. On Mac it requires the Rust host to be `aarch64-apple-darwin`. +- `scripts/install.sh` selects `aarch64-darwin` and stops for every other Mac + architecture. +- `components.json` publishes `darwin-arm64` payloads. An Intel install needs + its own payload set. +- The Mac Browser engine host is Apple silicon Virtualization.framework. An + Intel release needs an explicit remote-engine decision, the same shape as + Linux AMD64, before anyone claims a local engine. See + [Browser support](BROWSER_SUPPORT.md). +- `scripts/package-release-binaries.sh` accepts `Darwin-arm64` and rejects + `Darwin-x86_64`. +- `scripts/ci-release-policy-test.py` keeps the release-package matrix on the + three signed platforms above. + +Until those gates move together, the launcher treats Intel Mac as outside the +stable install set and uses the Apple silicon or Linux build. + ## From Fresh Mac To Home Install the host tools first: diff --git a/scripts/ci-release-policy-test.py b/scripts/ci-release-policy-test.py index 4d670a620..387739645 100644 --- a/scripts/ci-release-policy-test.py +++ b/scripts/ci-release-policy-test.py @@ -1658,6 +1658,9 @@ def test_github_runners_and_check_names_stay_fixed(self): "source-home-linux": ("source-home-linux (${{ matrix.os }})", "${{ matrix.os }}"), "source-home-linux-arm64": ("source-home-linux (${{ matrix.check_name || matrix.os }})", "${{ matrix.os }}"), "source-home-macos": ("source-home-macos", "macos-14"), + # Intel gateway /healthz smoke. Signed x86_64-darwin admission is + # still the signer and installer gate in docs/MAC.md. + "gateway-smoke-macos-intel": ("gateway-smoke-macos-intel", "macos-15-intel"), "cancel-on-failure": ("cancel-on-failure", "ubuntu-24.04"), # Anders decides whether this becomes a required check (#320). "update-hop-linux": ("update-hop-linux", "ubuntu-24.04"), diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py new file mode 100644 index 000000000..c771e56c0 --- /dev/null +++ b/scripts/gateway-healthz-smoke-test.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python3 +"""The gateway smoke script accepts a loopback probe and rejects the other cases.""" + +import os +import socket +import stat +import subprocess +import tempfile +import textwrap +import unittest +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SMOKE = ROOT / "scripts" / "gateway-healthz-smoke.sh" + +STUB = textwrap.dedent( + """\ + #!/usr/bin/env python3 + import os, sys + from http.server import BaseHTTPRequestHandler, HTTPServer + mode = os.environ.get("SMOKE_STUB", "ok") + if mode == "exit": + sys.exit(1) + if mode == "sleep": + import time + time.sleep(30) + sys.exit(0) + args = sys.argv[1:] + if args[:1] != ["gateway"] or "--addr" not in args: + sys.exit(2) + host, port = args[args.index("--addr") + 1].rsplit(":", 1) + class Handler(BaseHTTPRequestHandler): + def do_GET(self): + body = b"OK" if mode == "ok" else b"NO" + self.send_response(200) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + def log_message(self, *args): + return + HTTPServer((host, int(port)), Handler).serve_forever() + """ +) + + +class GatewayHealthzSmokeTest(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.addCleanup(self.tmp.cleanup) + self.binary = Path(self.tmp.name) / "elastos" + self.binary.write_text(STUB) + self.binary.chmod(self.binary.stat().st_mode | stat.S_IEXEC) + self.port = self.free_port() + + @staticmethod + def free_port(): + with socket.socket() as sock: + sock.bind(("127.0.0.1", 0)) + return sock.getsockname()[1] + + def run_smoke(self, stub, addr=None, deadline="3"): + env = os.environ.copy() + env["SMOKE_STUB"] = stub + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = deadline + if addr is not None: + env["ELASTOS_GATEWAY_ADDR"] = addr + else: + env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + return subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, + capture_output=True, + text=True, + timeout=15, + ) + + def test_ok_body_exits_zero(self): + result = self.run_smoke("ok") + self.assertEqual(result.returncode, 0, result.stderr) + + def test_other_body_exits_one(self): + result = self.run_smoke("other") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("body is not OK", result.stderr) + + def test_early_exit_exits_one(self): + result = self.run_smoke("exit", deadline="5") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("exited before", result.stderr) + + def test_timeout_exits_one(self): + result = self.run_smoke("sleep", deadline="1") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("did not return OK", result.stderr) + + def test_non_loopback_addr_exits_two(self): + result = self.run_smoke("ok", addr="0.0.0.0:9") + self.assertEqual(result.returncode, 2, result.stderr) + self.assertIn("loopback", result.stderr) + + def test_missing_binary_exits_one(self): + missing = Path(self.tmp.name) / "missing" + result = subprocess.run( + ["bash", str(SMOKE), str(missing)], + capture_output=True, + text=True, + timeout=10, + ) + self.assertEqual(result.returncode, 1, result.stderr) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/gateway-healthz-smoke.sh b/scripts/gateway-healthz-smoke.sh new file mode 100755 index 000000000..c765047de --- /dev/null +++ b/scripts/gateway-healthz-smoke.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +# Start one elastos gateway and require the launcher readiness probe. +# The probe is GET /healthz with body OK. See docs/LAUNCHER_CONTRACT.md. +set -euo pipefail + +if [[ $# -ne 1 || -z "${1:-}" ]]; then + echo "usage: gateway-healthz-smoke.sh /path/to/elastos" >&2 + exit 2 +fi + +binary=$1 +addr=${ELASTOS_GATEWAY_ADDR:-127.0.0.1:8090} +deadline=${ELASTOS_GATEWAY_HEALTH_DEADLINE:-120} + +case "$addr" in + 127.0.0.1:*|localhost:*) ;; + *) + echo "gateway smoke binds loopback only: $addr" >&2 + exit 2 + ;; +esac +if [[ ! -x "$binary" ]]; then + echo "elastos binary is missing or is not executable: $binary" >&2 + exit 1 +fi + +root=$(mktemp -d) +pid= +log= +stop_gateway() { + if [[ -z "$pid" ]]; then + return 0 + fi + kill -TERM "$pid" 2>/dev/null || true + local i + for i in 1 2 3 4 5 6 7 8 9 10; do + kill -0 "$pid" 2>/dev/null || return 0 + sleep 0.2 + done + kill -KILL "$pid" 2>/dev/null || true + wait "$pid" 2>/dev/null || true +} +cleanup() { + local status=$? + stop_gateway + if [[ -n "${ELASTOS_GATEWAY_LOG:-}" && -f "$log" ]]; then + cp "$log" "$ELASTOS_GATEWAY_LOG" 2>/dev/null || true + fi + rm -rf "$root" + exit "$status" +} +trap cleanup EXIT + +export HOME="$root/home" +export XDG_DATA_HOME="$root/home/.local/share" +mkdir -p "$HOME" "$XDG_DATA_HOME" +log="$root/gateway.log" + +"$binary" gateway --addr "$addr" >"$log" 2>&1 & +pid=$! + +url="http://${addr}/healthz" +end=$((SECONDS + deadline)) +while true; do + if ! kill -0 "$pid" 2>/dev/null; then + echo "gateway exited before /healthz returned OK" >&2 + cat "$log" >&2 || true + exit 1 + fi + if body=$(curl -fsS --max-time 2 "$url" 2>/dev/null); then + if [[ "$body" == "OK" ]]; then + exit 0 + fi + echo "GET $url body is not OK" >&2 + printf '%s\n' "$body" >&2 + exit 1 + fi + if (( SECONDS >= end )); then + echo "GET $url did not return OK within ${deadline}s" >&2 + cat "$log" >&2 || true + exit 1 + fi + sleep 1 +done diff --git a/scripts/test-source-gate.sh b/scripts/test-source-gate.sh index d1998f6e5..171d2a5ea 100755 --- a/scripts/test-source-gate.sh +++ b/scripts/test-source-gate.sh @@ -34,6 +34,7 @@ release() { python3 scripts/prepare-release-platform-test.py python3 scripts/media-tools-build-test.py python3 scripts/verify-linux-arm64-package-test.py + python3 scripts/gateway-healthz-smoke-test.py python3 scripts/verify-linux-engine-test.py python3 scripts/update-hop-compare-test.py python3 .github/scripts/release-mac-capacity-test.py From b011f79dbdb2aac1b61227e9a8a37eda0cf9f10b Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 16 Oct 2026 05:11:20 +0000 Subject: [PATCH 02/12] ci: probe the Intel gateway binary the job just built GITHUB_ENV applies on the next step, so the release build wrote elastos into the workspace target dir and the /healthz probe looked in an empty runner directory. The build step now exports that directory and checks the binary is executable before the probe runs. Co-authored-by: Sash --- .github/workflows/ci.yml | 6 +++++- scripts/ci-release-policy-test.py | 10 ++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c29f63ce6..63afef588 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1585,8 +1585,12 @@ jobs: timeout-minutes: 70 run: | set -euo pipefail - echo "CARGO_TARGET_DIR=$RUNNER_TEMP/gateway-intel-target" >> "$GITHUB_ENV" + # GITHUB_ENV applies on the next step. Export it here so this build + # writes the binary the /healthz probe executes. + export CARGO_TARGET_DIR="$RUNNER_TEMP/gateway-intel-target" + echo "CARGO_TARGET_DIR=$CARGO_TARGET_DIR" >> "$GITHUB_ENV" cargo build --locked --release --manifest-path elastos/Cargo.toml -p elastos-server --bin elastos + test -x "$CARGO_TARGET_DIR/release/elastos" - name: gateway /healthz returns OK timeout-minutes: 10 run: | diff --git a/scripts/ci-release-policy-test.py b/scripts/ci-release-policy-test.py index 387739645..af3781a4a 100644 --- a/scripts/ci-release-policy-test.py +++ b/scripts/ci-release-policy-test.py @@ -1643,6 +1643,16 @@ def test_restored_inputs_are_verified_before_use(self): with self.subTest(mutation=name), self.assertRaises(AssertionError): validate_restores_are_verified(changed) + def test_intel_gateway_smoke_probes_the_binary_it_built(self): + build, = [step for step in steps("gateway-smoke-macos-intel") + if step.startswith("name: build the gateway binary\n")] + probe, = [step for step in steps("gateway-smoke-macos-intel") + if "scripts/gateway-healthz-smoke.sh" in step] + self.assertLess(build.index('export CARGO_TARGET_DIR="$RUNNER_TEMP/gateway-intel-target"'), + build.index("cargo build --locked --release")) + self.assertIn('test -x "$CARGO_TARGET_DIR/release/elastos"', build) + self.assertIn('scripts/gateway-healthz-smoke.sh "$CARGO_TARGET_DIR/release/elastos"', probe) + def test_github_runners_and_check_names_stay_fixed(self): expected = { "source-gate": ("source-gate", "ubuntu-24.04"), From 18a2a66f4a97d69074e80b719c42976e2c3c936c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 16 Oct 2026 11:53:17 +0000 Subject: [PATCH 03/12] ci: bind the Intel /healthz smoke to the process it starts The smoke picks a free numeric loopback port, rejects any other address, and accepts the two bytes OK only from the pid that owns the listen socket. It signals that process group on the way out and keeps the gateway log off stdout. MAC.md no longer tells a launcher to run another platform's build. Co-authored-by: Sash --- docs/MAC.md | 33 +++---- scripts/gateway-healthz-smoke-test.py | 130 +++++++++++++++++++++++++- scripts/gateway-healthz-smoke.sh | 49 ++++++---- 3 files changed, 170 insertions(+), 42 deletions(-) diff --git a/docs/MAC.md b/docs/MAC.md index f1b43bdd6..fcc03c760 100644 --- a/docs/MAC.md +++ b/docs/MAC.md @@ -6,41 +6,34 @@ artifacts, and `.dmg` packaging work. ## Intel Mac -An Intel Mac is `x86_64` (`darwin-x64` in launcher platform names, -`x86_64-darwin` in the release platform id, `darwin-amd64` in -`scripts/release-platforms.json`). The signed installer still stops on that -host with `macOS release lookup requires Apple silicon`. +The public release id for an Intel Mac is `x86_64-darwin`. The signed installer +stops on that host before a download lookup. The message is +`macOS release lookup requires Apple silicon`. This runbook's source-home path +is the local build. A signed download for that id is a separate release decision. -CI job `gateway-smoke-macos-intel` runs on the GitHub-hosted `macos-15-intel` -runner. It builds the native `elastos` binary, runs -`elastos gateway --addr 127.0.0.1:8090`, and requires `GET /healthz` to return -the body `OK`. That job is a readiness smoke. It does not publish a signed -release, and `ci.yml` still withholds release tarballs from GitHub Releases. +CI job `gateway-smoke-macos-intel` builds the native `elastos` binary on +`macos-15-intel` and requires `GET /healthz` to return the two bytes `OK` from +the process that job started. That job is a readiness smoke. It publishes no +signed release. -A native build on `macos-15-intel` does not need a cross compiler. GitHub -keeps that Intel image through the macOS 15 runner retirement. Admitting the -same host to the stable channel needs the signed release path opened together: +A signed Intel release opens only when these gates move together: - `scripts/release-signer.py` admits `x86_64-linux`, `aarch64-linux`, and - `aarch64-darwin`. An Intel platform id is refused there. + `aarch64-darwin`. It refuses `x86_64-darwin`. - `scripts/prepare-release-platform.sh` prepares Linux x86_64, Linux ARM64, and macOS ARM64. On Mac it requires the Rust host to be `aarch64-apple-darwin`. - `scripts/install.sh` selects `aarch64-darwin` and stops for every other Mac architecture. - `components.json` publishes `darwin-arm64` payloads. An Intel install needs its own payload set. -- The Mac Browser engine host is Apple silicon Virtualization.framework. An - Intel release needs an explicit remote-engine decision, the same shape as - Linux AMD64, before anyone claims a local engine. See - [Browser support](BROWSER_SUPPORT.md). +- The Mac Browser engine host is Apple silicon Virtualization.framework. See + [Browser support](BROWSER_SUPPORT.md). This runbook claims no local Intel + Browser engine. - `scripts/package-release-binaries.sh` accepts `Darwin-arm64` and rejects `Darwin-x86_64`. - `scripts/ci-release-policy-test.py` keeps the release-package matrix on the three signed platforms above. -Until those gates move together, the launcher treats Intel Mac as outside the -stable install set and uses the Apple silicon or Linux build. - ## From Fresh Mac To Home Install the host tools first: diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index c771e56c0..b352bbafb 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -16,29 +16,51 @@ STUB = textwrap.dedent( """\ #!/usr/bin/env python3 - import os, sys + import os, socket, sys from http.server import BaseHTTPRequestHandler, HTTPServer mode = os.environ.get("SMOKE_STUB", "ok") if mode == "exit": sys.exit(1) + if mode == "secret": + print("attach_secret=planted-secret", flush=True) + sys.exit(1) if mode == "sleep": import time time.sleep(30) sys.exit(0) + if mode == "fork": + import time + child = os.fork() + if child == 0: + with open(os.environ["SMOKE_CHILD_PID"], "w", encoding="utf-8") as handle: + handle.write(str(os.getpid())) + time.sleep(30) + sys.exit(0) + time.sleep(30) + sys.exit(0) args = sys.argv[1:] if args[:1] != ["gateway"] or "--addr" not in args: sys.exit(2) host, port = args[args.index("--addr") + 1].rsplit(":", 1) + if host.startswith("[") and host.endswith("]"): + host = host[1:-1] class Handler(BaseHTTPRequestHandler): def do_GET(self): - body = b"OK" if mode == "ok" else b"NO" + if mode == "newline": + body = b"OK\\n" + elif mode == "ok": + body = b"OK" + else: + body = b"NO" self.send_response(200) self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) def log_message(self, *args): return - HTTPServer((host, int(port)), Handler).serve_forever() + class Server(HTTPServer): + address_family = socket.AF_INET6 if host == "::1" else socket.AF_INET + Server((host, int(port)), Handler).serve_forever() """ ) @@ -81,7 +103,7 @@ def test_ok_body_exits_zero(self): def test_other_body_exits_one(self): result = self.run_smoke("other") self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("body is not OK", result.stderr) + self.assertIn("two bytes OK", result.stderr) def test_early_exit_exits_one(self): result = self.run_smoke("exit", deadline="5") @@ -108,6 +130,106 @@ def test_missing_binary_exits_one(self): ) self.assertEqual(result.returncode, 1, result.stderr) + def test_default_addr_uses_a_free_port(self): + env = os.environ.copy() + env["SMOKE_STUB"] = "ok" + env.pop("ELASTOS_GATEWAY_ADDR", None) + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "5" + result = subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, + capture_output=True, + text=True, + timeout=15, + ) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("two bytes OK from pid", result.stdout) + self.assertNotIn(":8090", result.stdout) + + def test_address_injection_exits_two(self): + result = self.run_smoke("ok", addr="127.0.0.1:1@example.com:80") + self.assertEqual(result.returncode, 2, result.stderr) + self.assertNotIn("example.com", result.stdout) + + def test_localhost_name_exits_two(self): + result = self.run_smoke("ok", addr="localhost:8090") + self.assertEqual(result.returncode, 2, result.stderr) + + def test_newline_body_exits_one(self): + result = self.run_smoke("newline") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("two bytes OK", result.stderr) + + def test_prebound_ok_is_not_this_process(self): + from http.server import BaseHTTPRequestHandler, HTTPServer + import threading + + class Handler(BaseHTTPRequestHandler): + def do_GET(self): + body = b"OK" + self.send_response(200) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, *args): + return + + server = HTTPServer(("127.0.0.1", self.port), Handler) + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + self.addCleanup(server.server_close) + self.addCleanup(server.shutdown) + result = self.run_smoke("sleep", deadline="3") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("not gateway pid", result.stderr) + + def test_process_group_is_stopped(self): + child_pid = Path(self.tmp.name) / "child.pid" + env = os.environ.copy() + env["SMOKE_STUB"] = "fork" + env["SMOKE_CHILD_PID"] = str(child_pid) + env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "1" + result = subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, + capture_output=True, + text=True, + timeout=15, + ) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertTrue(child_pid.exists(), result.stderr) + grandchild = int(child_pid.read_text()) + with self.assertRaises(ProcessLookupError): + os.kill(grandchild, 0) + + def test_log_is_kept_and_not_echoed(self): + log = Path(self.tmp.name) / "gateway.log" + env = os.environ.copy() + env["SMOKE_STUB"] = "secret" + env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + env["ELASTOS_GATEWAY_LOG"] = str(log) + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "3" + result = subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, + capture_output=True, + text=True, + timeout=15, + ) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertNotIn("planted-secret", result.stdout) + self.assertNotIn("planted-secret", result.stderr) + self.assertIn("planted-secret", log.read_text()) + + def test_ipv6_loopback_ok(self): + with socket.socket(socket.AF_INET6) as sock: + sock.bind(("::1", 0)) + port = sock.getsockname()[1] + result = self.run_smoke("ok", addr=f"[::1]:{port}") + self.assertEqual(result.returncode, 0, result.stderr + result.stdout) + if __name__ == "__main__": unittest.main() diff --git a/scripts/gateway-healthz-smoke.sh b/scripts/gateway-healthz-smoke.sh index c765047de..e85752991 100755 --- a/scripts/gateway-healthz-smoke.sh +++ b/scripts/gateway-healthz-smoke.sh @@ -1,6 +1,7 @@ #!/usr/bin/env bash # Start one elastos gateway and require the launcher readiness probe. -# The probe is GET /healthz with body OK. See docs/LAUNCHER_CONTRACT.md. +# The probe is GET /healthz with the two bytes OK from this process. +# See docs/LAUNCHER_CONTRACT.md. set -euo pipefail if [[ $# -ne 1 || -z "${1:-}" ]]; then @@ -9,16 +10,20 @@ if [[ $# -ne 1 || -z "${1:-}" ]]; then fi binary=$1 -addr=${ELASTOS_GATEWAY_ADDR:-127.0.0.1:8090} deadline=${ELASTOS_GATEWAY_HEALTH_DEADLINE:-120} -case "$addr" in - 127.0.0.1:*|localhost:*) ;; - *) - echo "gateway smoke binds loopback only: $addr" >&2 - exit 2 - ;; -esac +if [[ -z "${ELASTOS_GATEWAY_ADDR:-}" ]]; then + port=$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()') + addr="127.0.0.1:${port}" +else + addr=$ELASTOS_GATEWAY_ADDR +fi +# A numeric loopback address keeps the listener check on one socket. +# The product start command remains `elastos gateway --addr localhost:8090`. +if [[ ! "$addr" =~ ^(127\.0\.0\.1|\[::1\]):[0-9]+$ ]]; then + echo "gateway smoke binds a numeric loopback address: $addr" >&2 + exit 2 +fi if [[ ! -x "$binary" ]]; then echo "elastos binary is missing or is not executable: $binary" >&2 exit 1 @@ -31,13 +36,13 @@ stop_gateway() { if [[ -z "$pid" ]]; then return 0 fi - kill -TERM "$pid" 2>/dev/null || true + kill -TERM -"$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true local i for i in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$pid" 2>/dev/null || return 0 sleep 0.2 done - kill -KILL "$pid" 2>/dev/null || true + kill -KILL -"$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true wait "$pid" 2>/dev/null || true } cleanup() { @@ -55,29 +60,37 @@ export HOME="$root/home" export XDG_DATA_HOME="$root/home/.local/share" mkdir -p "$HOME" "$XDG_DATA_HOME" log="$root/gateway.log" +expect="$root/healthz-expect" +body="$root/healthz-body" +printf 'OK' >"$expect" -"$binary" gateway --addr "$addr" >"$log" 2>&1 & +# The new session is the process group. Cleanup signals that group. +python3 -c 'import os, sys; os.setsid(); os.execv(sys.argv[1], sys.argv[1:])' \ + "$binary" gateway --addr "$addr" >"$log" 2>&1 & pid=$! url="http://${addr}/healthz" +port="${addr##*:}" end=$((SECONDS + deadline)) while true; do if ! kill -0 "$pid" 2>/dev/null; then echo "gateway exited before /healthz returned OK" >&2 - cat "$log" >&2 || true exit 1 fi - if body=$(curl -fsS --max-time 2 "$url" 2>/dev/null); then - if [[ "$body" == "OK" ]]; then + if curl -fsS --max-time 2 -o "$body" "$url" 2>/dev/null; then + if cmp -s "$expect" "$body"; then + if ! lsof -a -p "$pid" -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then + echo "GET $url responder is not gateway pid $pid" >&2 + exit 1 + fi + echo "GET $url returned the two bytes OK from pid $pid" exit 0 fi - echo "GET $url body is not OK" >&2 - printf '%s\n' "$body" >&2 + echo "GET $url body is not the two bytes OK" >&2 exit 1 fi if (( SECONDS >= end )); then echo "GET $url did not return OK within ${deadline}s" >&2 - cat "$log" >&2 || true exit 1 fi sleep 1 From f770a05c4455a5ff6a51ee8bef637786979b8e15 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 17 Oct 2026 05:42:18 +0000 Subject: [PATCH 04/12] fix: make the Intel /healthz smoke match the owner check The smoke requires HTTP 200 and the two bytes OK from the process that owns the host lock. It says an empty Home is not provider readiness, and it leaves localhost:8090 as a stated gap. Cleanup signals the whole process group, including a child that ignores SIGTERM. Co-authored-by: Sash --- .github/workflows/ci.yml | 6 +- docs/MAC.md | 44 +++++------ scripts/gateway-healthz-smoke-test.py | 102 ++++++++++++++++++++++++-- scripts/gateway-healthz-smoke.sh | 56 ++++++++++---- 4 files changed, 163 insertions(+), 45 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 63afef588..e7c06488d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1560,9 +1560,9 @@ jobs: retention-days: 7 if-no-files-found: ignore - # Native Intel Mac proof of the launcher readiness probe. This job builds - # the gateway binary and requires GET /healthz to return OK. It is not a - # signed release. docs/MAC.md records the signer and installer gates. + # Native Intel Mac proof of the /healthz owner check. This job builds the + # gateway binary and requires HTTP 200 and the two bytes OK from that + # process. An empty Home can pass. It is not a signed release. gateway-smoke-macos-intel: name: gateway-smoke-macos-intel runs-on: macos-15-intel diff --git a/docs/MAC.md b/docs/MAC.md index fcc03c760..d21b3a2fb 100644 --- a/docs/MAC.md +++ b/docs/MAC.md @@ -6,33 +6,29 @@ artifacts, and `.dmg` packaging work. ## Intel Mac -The public release id for an Intel Mac is `x86_64-darwin`. The signed installer +The public release id for an Intel Mac is `x86_64-darwin`. `scripts/install.sh` stops on that host before a download lookup. The message is -`macOS release lookup requires Apple silicon`. This runbook's source-home path -is the local build. A signed download for that id is a separate release decision. +`macOS release lookup requires Apple silicon`. + +A person with an Intel Mac has no signed download. The next step is the signed +installer on an Apple silicon Mac. The source-home commands later in this +runbook are a developer build. They are not the installer, and this note does +not claim that build has passed on Intel. CI job `gateway-smoke-macos-intel` builds the native `elastos` binary on -`macos-15-intel` and requires `GET /healthz` to return the two bytes `OK` from -the process that job started. That job is a readiness smoke. It publishes no -signed release. - -A signed Intel release opens only when these gates move together: - -- `scripts/release-signer.py` admits `x86_64-linux`, `aarch64-linux`, and - `aarch64-darwin`. It refuses `x86_64-darwin`. -- `scripts/prepare-release-platform.sh` prepares Linux x86_64, Linux ARM64, and - macOS ARM64. On Mac it requires the Rust host to be `aarch64-apple-darwin`. -- `scripts/install.sh` selects `aarch64-darwin` and stops for every other Mac - architecture. -- `components.json` publishes `darwin-arm64` payloads. An Intel install needs - its own payload set. -- The Mac Browser engine host is Apple silicon Virtualization.framework. See - [Browser support](BROWSER_SUPPORT.md). This runbook claims no local Intel - Browser engine. -- `scripts/package-release-binaries.sh` accepts `Darwin-arm64` and rejects - `Darwin-x86_64`. -- `scripts/ci-release-policy-test.py` keeps the release-package matrix on the - three signed platforms above. +`macos-15-intel`. It requires `GET /healthz` to return HTTP 200 and the two +bytes `OK` from the process that owns `host-process.lock`. That is the owner +check in [the launcher contract](LAUNCHER_CONTRACT.md). The job uses an empty +Home, so a passing probe does not prove providers, capsules, or a signed +install. `elastos serve` reports operator status at `GET /api/health`. + +The product command is `elastos gateway --addr localhost:8090`. The smoke +binds one numeric loopback address on a free port. It does not open +`localhost:8090`. On macOS, `localhost` can resolve to `::1` while that bind +is `127.0.0.1` or `[::1]`. That name and port gap remains. + +This runbook claims no local Intel Browser engine. See +[Browser support](BROWSER_SUPPORT.md). The job uploads no release tarball. ## From Fresh Mac To Home diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index b352bbafb..3d69bc1db 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -38,6 +38,18 @@ sys.exit(0) time.sleep(30) sys.exit(0) + if mode == "ignore-term": + import signal + import time + child = os.fork() + if child == 0: + signal.signal(signal.SIGTERM, signal.SIG_IGN) + with open(os.environ["SMOKE_CHILD_PID"], "w", encoding="utf-8") as handle: + handle.write(str(os.getpid())) + time.sleep(30) + sys.exit(0) + time.sleep(30) + sys.exit(0) args = sys.argv[1:] if args[:1] != ["gateway"] or "--addr" not in args: sys.exit(2) @@ -47,12 +59,16 @@ class Handler(BaseHTTPRequestHandler): def do_GET(self): if mode == "newline": - body = b"OK\\n" + status, body = 200, b"OK\\n" + elif mode == "redirect": + status, body = 302, b"OK" + elif mode == "no-content": + status, body = 204, b"OK" elif mode == "ok": - body = b"OK" + status, body = 200, b"OK" else: - body = b"NO" - self.send_response(200) + status, body = 200, b"NO" + self.send_response(status) self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) @@ -143,7 +159,7 @@ def test_default_addr_uses_a_free_port(self): timeout=15, ) self.assertEqual(result.returncode, 0, result.stderr) - self.assertIn("two bytes OK from pid", result.stdout) + self.assertIn("HTTP 200 and the two bytes OK from pid", result.stdout) self.assertNotIn(":8090", result.stdout) def test_address_injection_exits_two(self): @@ -223,6 +239,82 @@ def test_log_is_kept_and_not_echoed(self): self.assertNotIn("planted-secret", result.stderr) self.assertIn("planted-secret", log.read_text()) + def test_deadline_must_be_a_positive_integer(self): + marker = Path(self.tmp.name) / "pwned" + for value in ("abc", "-5", "", "0", "x[$(touch %s)]" % marker): + with self.subTest(value=value): + result = self.run_smoke("ok", deadline=value) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertIn("ELASTOS_GATEWAY_HEALTH_DEADLINE", result.stderr) + self.assertFalse(marker.exists()) + + def test_redirect_and_no_content_are_not_success(self): + for stub in ("redirect", "no-content"): + with self.subTest(stub=stub): + result = self.run_smoke(stub) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("HTTP", result.stderr) + + def test_proxy_cannot_supply_the_ok_body(self): + import threading + + proxy = socket.socket() + proxy.bind(("127.0.0.1", 0)) + proxy.listen(1) + proxy_port = proxy.getsockname()[1] + + def serve_proxy(): + try: + connection, _ = proxy.accept() + except OSError: + return + connection.sendall(b"HTTP/1.0 200 OK\r\nContent-Length: 2\r\n\r\nOK") + connection.close() + + thread = threading.Thread(target=serve_proxy, daemon=True) + thread.start() + self.addCleanup(proxy.close) + env = os.environ.copy() + env["SMOKE_STUB"] = "other" + env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "3" + env["http_proxy"] = f"http://127.0.0.1:{proxy_port}" + env["HTTP_PROXY"] = env["http_proxy"] + result = subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, capture_output=True, text=True, timeout=15) + self.assertEqual(result.returncode, 1, result.stdout + result.stderr) + self.assertIn("two bytes OK", result.stderr) + + def test_child_ignoring_term_is_killed(self): + child_pid = Path(self.tmp.name) / "ignore.pid" + env = os.environ.copy() + env["SMOKE_STUB"] = "ignore-term" + env["SMOKE_CHILD_PID"] = str(child_pid) + env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "1" + result = subprocess.run( + ["bash", str(SMOKE), str(self.binary)], + env=env, capture_output=True, text=True, timeout=15) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertTrue(child_pid.exists(), result.stderr) + grandchild = int(child_pid.read_text()) + with self.assertRaises(ProcessLookupError): + os.kill(grandchild, 0) + + def test_contract_keeps_localhost_and_this_smoke_does_not_bind_it(self): + contract = (ROOT / "docs/LAUNCHER_CONTRACT.md").read_text() + self.assertIn("elastos gateway --addr localhost:8090", contract) + self.assertIn("host-process.lock", contract) + mac = (ROOT / "docs/MAC.md").read_text() + install = (ROOT / "scripts/install.sh").read_text() + self.assertIn('die "macOS release lookup requires Apple silicon"', install) + self.assertIn("macOS release lookup requires Apple silicon", mac) + self.assertIn("Apple silicon Mac", mac) + self.assertNotIn("gates move together", mac) + result = self.run_smoke("ok", addr="localhost:8090") + self.assertEqual(result.returncode, 2, result.stderr) + def test_ipv6_loopback_ok(self): with socket.socket(socket.AF_INET6) as sock: sock.bind(("::1", 0)) diff --git a/scripts/gateway-healthz-smoke.sh b/scripts/gateway-healthz-smoke.sh index e85752991..fb3cefb25 100755 --- a/scripts/gateway-healthz-smoke.sh +++ b/scripts/gateway-healthz-smoke.sh @@ -1,7 +1,13 @@ #!/usr/bin/env bash -# Start one elastos gateway and require the launcher readiness probe. -# The probe is GET /healthz with the two bytes OK from this process. -# See docs/LAUNCHER_CONTRACT.md. +# Start one elastos gateway and require the /healthz owner check. +# docs/LAUNCHER_CONTRACT.md: HTTP 200 and the two bytes OK when this process +# owns host-process.lock with role gateway or gateway-public. +# An empty Home can pass. This script does not prove providers, capsules, +# or a signed install. elastos serve uses GET /api/health for that status. +# The product command is `elastos gateway --addr localhost:8090`. This script +# binds one numeric loopback socket so the pid check has one listener. It does +# not prove localhost name resolution or port 8090. On macOS, localhost can +# resolve to ::1 while this bind is 127.0.0.1 or [::1]. set -euo pipefail if [[ $# -ne 1 || -z "${1:-}" ]]; then @@ -10,7 +16,19 @@ if [[ $# -ne 1 || -z "${1:-}" ]]; then fi binary=$1 -deadline=${ELASTOS_GATEWAY_HEALTH_DEADLINE:-120} +if [[ -z "${ELASTOS_GATEWAY_HEALTH_DEADLINE+x}" ]]; then + deadline=120 +else + deadline=$ELASTOS_GATEWAY_HEALTH_DEADLINE +fi +if [[ ! "$deadline" =~ ^[1-9][0-9]{0,3}$ ]]; then + echo "ELASTOS_GATEWAY_HEALTH_DEADLINE must be a positive integer" >&2 + exit 2 +fi +if ! command -v curl >/dev/null 2>&1 || ! command -v lsof >/dev/null 2>&1; then + echo "curl and lsof are required" >&2 + exit 2 +fi if [[ -z "${ELASTOS_GATEWAY_ADDR:-}" ]]; then port=$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()') @@ -19,7 +37,6 @@ else addr=$ELASTOS_GATEWAY_ADDR fi # A numeric loopback address keeps the listener check on one socket. -# The product start command remains `elastos gateway --addr localhost:8090`. if [[ ! "$addr" =~ ^(127\.0\.0\.1|\[::1\]):[0-9]+$ ]]; then echo "gateway smoke binds a numeric loopback address: $addr" >&2 exit 2 @@ -32,29 +49,38 @@ fi root=$(mktemp -d) pid= log= +group_alive() { + kill -0 -"$pid" 2>/dev/null +} stop_gateway() { if [[ -z "$pid" ]]; then return 0 fi - kill -TERM -"$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true + kill -TERM -"$pid" 2>/dev/null || true local i for i in 1 2 3 4 5 6 7 8 9 10; do - kill -0 "$pid" 2>/dev/null || return 0 + group_alive || { wait "$pid" 2>/dev/null || true; return 0; } sleep 0.2 done - kill -KILL -"$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true - wait "$pid" 2>/dev/null || true + kill -KILL -"$pid" 2>/dev/null || true + for i in 1 2 3 4 5 6 7 8 9 10; do + group_alive || { wait "$pid" 2>/dev/null || true; return 0; } + sleep 0.2 + done + echo "gateway process group $pid is still running" >&2 + return 1 } cleanup() { local status=$? - stop_gateway + trap - EXIT INT TERM HUP + stop_gateway || status=1 if [[ -n "${ELASTOS_GATEWAY_LOG:-}" && -f "$log" ]]; then cp "$log" "$ELASTOS_GATEWAY_LOG" 2>/dev/null || true fi rm -rf "$root" exit "$status" } -trap cleanup EXIT +trap cleanup EXIT INT TERM HUP export HOME="$root/home" export XDG_DATA_HOME="$root/home/.local/share" @@ -77,17 +103,21 @@ while true; do echo "gateway exited before /healthz returned OK" >&2 exit 1 fi - if curl -fsS --max-time 2 -o "$body" "$url" 2>/dev/null; then + code=$(curl --noproxy '*' -sS --max-time 2 -o "$body" -w '%{http_code}' "$url" 2>/dev/null || true) + if [[ "$code" == 200 ]]; then if cmp -s "$expect" "$body"; then if ! lsof -a -p "$pid" -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then echo "GET $url responder is not gateway pid $pid" >&2 exit 1 fi - echo "GET $url returned the two bytes OK from pid $pid" + echo "GET $url returned HTTP 200 and the two bytes OK from pid $pid" exit 0 fi echo "GET $url body is not the two bytes OK" >&2 exit 1 + elif [[ -n "$code" && "$code" != 000 ]]; then + echo "GET $url returned HTTP $code" >&2 + exit 1 fi if (( SECONDS >= end )); then echo "GET $url did not return OK within ${deadline}s" >&2 From a36616676a07850749ba6c48dc48caa4d9df4141 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 06:24:35 +0000 Subject: [PATCH 05/12] fix: prove contract readiness at localhost:8090 in the Intel smoke The smoke now runs the contract command `elastos gateway --addr localhost:8090` and polls GET http://localhost:8090/healthz. It passes only when the answer is HTTP 200 and the two bytes OK, the address curl reached is a listen socket of the gateway pid, and host-process.lock names that pid, a gateway role and the same addr. HTTP 503 is polled until the deadline; any other status fails. After that check it prints facts, not pass or fail: the localhost lookup order, the addresses the gateway listens on, and what /healthz returns at localhost, 127.0.0.1 and [::1]. `--addr localhost:8090` binds only the first address that resolves and binds (tokio TcpListener::bind), so on a host where localhost gives ::1 first, 127.0.0.1:8090 misses the gateway. A smoke stopped by SIGTERM exited 0. Each signal now has its own exit status, and cleanup signals both the group and the pid and waits until neither is alive. An unknown host OS, a missing tool, an out-of-range port and a deadline that is not 1 to 9999 seconds stop before the gateway starts. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- .github/workflows/ci.yml | 9 +- docs/MAC.md | 30 +- scripts/ci-release-policy-test.py | 2 + scripts/gateway-healthz-smoke-test.py | 530 +++++++++++++++----------- scripts/gateway-healthz-smoke.sh | 235 ++++++++---- 5 files changed, 501 insertions(+), 305 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e7c06488d..1aaabd3c7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1560,9 +1560,10 @@ jobs: retention-days: 7 if-no-files-found: ignore - # Native Intel Mac proof of the /healthz owner check. This job builds the - # gateway binary and requires HTTP 200 and the two bytes OK from that - # process. An empty Home can pass. It is not a signed release. + # Native Intel Mac proof of gateway readiness as docs/LAUNCHER_CONTRACT.md + # defines it: `elastos gateway --addr localhost:8090`, then + # GET http://localhost:8090/healthz returns HTTP 200 and OK while that pid + # owns host-process.lock. The Home is empty. This is not a signed release. gateway-smoke-macos-intel: name: gateway-smoke-macos-intel runs-on: macos-15-intel @@ -1591,7 +1592,7 @@ jobs: echo "CARGO_TARGET_DIR=$CARGO_TARGET_DIR" >> "$GITHUB_ENV" cargo build --locked --release --manifest-path elastos/Cargo.toml -p elastos-server --bin elastos test -x "$CARGO_TARGET_DIR/release/elastos" - - name: gateway /healthz returns OK + - name: gateway is ready at localhost:8090 with an empty Home timeout-minutes: 10 run: | set -euo pipefail diff --git a/docs/MAC.md b/docs/MAC.md index d21b3a2fb..b2020bd22 100644 --- a/docs/MAC.md +++ b/docs/MAC.md @@ -16,16 +16,26 @@ runbook are a developer build. They are not the installer, and this note does not claim that build has passed on Intel. CI job `gateway-smoke-macos-intel` builds the native `elastos` binary on -`macos-15-intel`. It requires `GET /healthz` to return HTTP 200 and the two -bytes `OK` from the process that owns `host-process.lock`. That is the owner -check in [the launcher contract](LAUNCHER_CONTRACT.md). The job uses an empty -Home, so a passing probe does not prove providers, capsules, or a signed -install. `elastos serve` reports operator status at `GET /api/health`. - -The product command is `elastos gateway --addr localhost:8090`. The smoke -binds one numeric loopback address on a free port. It does not open -`localhost:8090`. On macOS, `localhost` can resolve to `::1` while that bind -is `127.0.0.1` or `[::1]`. That name and port gap remains. +`macos-15-intel`. It runs `scripts/gateway-healthz-smoke.sh`, which starts the +command in [the launcher contract](LAUNCHER_CONTRACT.md) and requires the +readiness that contract defines. The probe uses `http://localhost:8090/healthz` +and passes only when all of these are true: + +- the answer is HTTP 200 with the two bytes `OK`, without a proxy, +- the address that answered is a listen socket of the gateway process, +- `host-process.lock` names that process, a gateway role and `localhost:8090`. + +The job uses an empty Home. A pass does not prove providers, capsules, +sign-in, or a signed install. `elastos serve` reports operator status at +`GET /api/health`. + +`--addr localhost:8090` binds one address only: the first address that the +system lookup gives for `localhost` and that can be bound. When `localhost` +gives `::1` first, `http://127.0.0.1:8090` does not reach the gateway, and +another process can hold that address. After the readiness check, the job log +prints facts, not pass or fail: that lookup order, the address the gateway +listens on, and what `GET /healthz` returns at `localhost:8090`, +`127.0.0.1:8090` and `[::1]:8090`. This runbook claims no local Intel Browser engine. See [Browser support](BROWSER_SUPPORT.md). The job uploads no release tarball. diff --git a/scripts/ci-release-policy-test.py b/scripts/ci-release-policy-test.py index af3781a4a..3652952eb 100644 --- a/scripts/ci-release-policy-test.py +++ b/scripts/ci-release-policy-test.py @@ -1652,6 +1652,8 @@ def test_intel_gateway_smoke_probes_the_binary_it_built(self): build.index("cargo build --locked --release")) self.assertIn('test -x "$CARGO_TARGET_DIR/release/elastos"', build) self.assertIn('scripts/gateway-healthz-smoke.sh "$CARGO_TARGET_DIR/release/elastos"', probe) + # The probe keeps the contract address localhost:8090 (the script default). + self.assertNotIn("ELASTOS_GATEWAY_ADDR", probe) def test_github_runners_and_check_names_stay_fixed(self): expected = { diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index 3d69bc1db..07fbd3bfb 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -1,13 +1,21 @@ #!/usr/bin/env python3 -"""The gateway smoke script accepts a loopback probe and rejects the other cases.""" +"""The gateway smoke accepts contract readiness and refuses every other case. + +Readiness is defined in docs/LAUNCHER_CONTRACT.md "Readiness and Home URL". +A stub stands in for the elastos binary so each refusal path runs on Linux. +""" import os +import signal import socket import stat import subprocess import tempfile import textwrap +import threading +import time import unittest +from http.server import BaseHTTPRequestHandler, HTTPServer from pathlib import Path ROOT = Path(__file__).resolve().parents[1] @@ -16,71 +24,127 @@ STUB = textwrap.dedent( """\ #!/usr/bin/env python3 - import os, socket, sys + import json, os, signal, socket, sys, time from http.server import BaseHTTPRequestHandler, HTTPServer mode = os.environ.get("SMOKE_STUB", "ok") + lock_mode = os.environ.get("SMOKE_LOCK", "good") + args = sys.argv[1:] + if "SMOKE_ARGS" in os.environ: + with open(os.environ["SMOKE_ARGS"], "w", encoding="utf-8") as handle: + json.dump(args, handle) + def fork_sleeper(ignore_term=False): + child = os.fork() + if child == 0: + if ignore_term: + signal.signal(signal.SIGTERM, signal.SIG_IGN) + with open(os.environ["SMOKE_CHILD_PID"], "w", encoding="utf-8") as handle: + handle.write(str(os.getpid())) + time.sleep(60) + os._exit(0) if mode == "exit": sys.exit(1) if mode == "secret": print("attach_secret=planted-secret", flush=True) sys.exit(1) if mode == "sleep": - import time time.sleep(30) sys.exit(0) - if mode == "fork": - import time - child = os.fork() - if child == 0: - with open(os.environ["SMOKE_CHILD_PID"], "w", encoding="utf-8") as handle: - handle.write(str(os.getpid())) - time.sleep(30) - sys.exit(0) - time.sleep(30) + if mode in ("fork", "ignore-term"): + fork_sleeper(ignore_term=(mode == "ignore-term")) + time.sleep(60) sys.exit(0) - if mode == "ignore-term": - import signal - import time - child = os.fork() - if child == 0: - signal.signal(signal.SIGTERM, signal.SIG_IGN) - with open(os.environ["SMOKE_CHILD_PID"], "w", encoding="utf-8") as handle: - handle.write(str(os.getpid())) - time.sleep(30) - sys.exit(0) - time.sleep(30) - sys.exit(0) - args = sys.argv[1:] - if args[:1] != ["gateway"] or "--addr" not in args: + if args[:2] != ["gateway", "--addr"] or len(args) != 3: sys.exit(2) - host, port = args[args.index("--addr") + 1].rsplit(":", 1) - if host.startswith("[") and host.endswith("]"): - host = host[1:-1] + addr = args[2] + host, port = addr.rsplit(":", 1) + host = host.strip("[]") + data = os.path.join(os.environ["XDG_DATA_HOME"], "elastos") + os.makedirs(data, exist_ok=True) + record = {"pid": os.getpid(), "role": "gateway", "addr": addr} + if lock_mode == "other-pid": + record["pid"] = os.getpid() + 100000 + elif lock_mode == "bad-role": + record["role"] = "serve" + elif lock_mode == "bad-addr": + record["addr"] = "127.0.0.1:1" + if lock_mode == "garbage": + with open(os.path.join(data, "host-process.lock"), "w") as handle: + handle.write("not json") + elif lock_mode != "none": + with open(os.path.join(data, "host-process.lock"), "w") as handle: + json.dump(record, handle) + if mode == "ok-fork": + fork_sleeper() + not_ready = int(os.environ.get("SMOKE_503_COUNT", "0")) class Handler(BaseHTTPRequestHandler): def do_GET(self): - if mode == "newline": - status, body = 200, b"OK\\n" + global not_ready + status, body = 200, b"OK" + if not_ready > 0: + not_ready -= 1 + status, body = 503, b"" + elif mode == "newline": + body = b"OK\\n" elif mode == "redirect": - status, body = 302, b"OK" + status = 302 elif mode == "no-content": - status, body = 204, b"OK" - elif mode == "ok": - status, body = 200, b"OK" - else: - status, body = 200, b"NO" + status = 204 + elif mode == "server-error": + status = 500 + elif mode == "other": + body = b"NO" + elif mode == "always-503": + status, body = 503, b"" self.send_response(status) self.send_header("Content-Length", str(len(body))) self.end_headers() self.wfile.write(body) def log_message(self, *args): return + if host == "localhost": + host = os.environ.get("SMOKE_LOCALHOST_BIND", "127.0.0.1") class Server(HTTPServer): - address_family = socket.AF_INET6 if host == "::1" else socket.AF_INET + address_family = socket.AF_INET6 if ":" in host else socket.AF_INET Server((host, int(port)), Handler).serve_forever() """ ) +def ipv6_loopback(): + try: + with socket.socket(socket.AF_INET6) as sock: + sock.bind(("::1", 0)) + return True + except OSError: + return False + + +def free_port(family=socket.AF_INET, host="127.0.0.1"): + with socket.socket(family) as sock: + sock.bind((host, 0)) + return sock.getsockname()[1] + + +def process_gone(pid): + try: + os.kill(pid, 0) + except ProcessLookupError: + return True + return False + + +class OkHandler(BaseHTTPRequestHandler): + def do_GET(self): + body = b"OK" + self.send_response(200) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def log_message(self, *args): + return + + class GatewayHealthzSmokeTest(unittest.TestCase): def setUp(self): self.tmp = tempfile.TemporaryDirectory() @@ -88,180 +152,162 @@ def setUp(self): self.binary = Path(self.tmp.name) / "elastos" self.binary.write_text(STUB) self.binary.chmod(self.binary.stat().st_mode | stat.S_IEXEC) - self.port = self.free_port() - - @staticmethod - def free_port(): - with socket.socket() as sock: - sock.bind(("127.0.0.1", 0)) - return sock.getsockname()[1] + self.port = free_port() + self.child_pid = Path(self.tmp.name) / "child.pid" - def run_smoke(self, stub, addr=None, deadline="3"): + def env(self, stub, addr=None, deadline="3", **extra): env = os.environ.copy() env["SMOKE_STUB"] = stub + env["SMOKE_CHILD_PID"] = str(self.child_pid) env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = deadline - if addr is not None: - env["ELASTOS_GATEWAY_ADDR"] = addr - else: - env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" + env["ELASTOS_GATEWAY_ADDR"] = addr if addr is not None else f"127.0.0.1:{self.port}" + env.update(extra) + return env + + def run_smoke(self, stub, addr=None, deadline="3", **extra): return subprocess.run( ["bash", str(SMOKE), str(self.binary)], - env=env, + env=self.env(stub, addr, deadline, **extra), capture_output=True, text=True, - timeout=15, + timeout=30, ) - def test_ok_body_exits_zero(self): - result = self.run_smoke("ok") - self.assertEqual(result.returncode, 0, result.stderr) + def serve_ok(self, family, host, port): + class Server(HTTPServer): + address_family = family - def test_other_body_exits_one(self): - result = self.run_smoke("other") - self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("two bytes OK", result.stderr) - - def test_early_exit_exits_one(self): - result = self.run_smoke("exit", deadline="5") - self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("exited before", result.stderr) - - def test_timeout_exits_one(self): - result = self.run_smoke("sleep", deadline="1") - self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("did not return OK", result.stderr) - - def test_non_loopback_addr_exits_two(self): - result = self.run_smoke("ok", addr="0.0.0.0:9") - self.assertEqual(result.returncode, 2, result.stderr) - self.assertIn("loopback", result.stderr) + server = Server((host, port), OkHandler) + threading.Thread(target=server.serve_forever, daemon=True).start() + self.addCleanup(server.server_close) + self.addCleanup(server.shutdown) - def test_missing_binary_exits_one(self): - missing = Path(self.tmp.name) / "missing" - result = subprocess.run( - ["bash", str(SMOKE), str(missing)], - capture_output=True, - text=True, - timeout=10, - ) - self.assertEqual(result.returncode, 1, result.stderr) + # Ready. - def test_default_addr_uses_a_free_port(self): - env = os.environ.copy() - env["SMOKE_STUB"] = "ok" - env.pop("ELASTOS_GATEWAY_ADDR", None) - env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "5" - result = subprocess.run( - ["bash", str(SMOKE), str(self.binary)], - env=env, - capture_output=True, - text=True, - timeout=15, - ) + def test_ok_with_owned_lock_is_ready(self): + result = self.run_smoke("ok") + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn(f"returned HTTP 200 and OK from gateway pid", result.stdout) + self.assertIn("host-process.lock names pid", result.stdout) + self.assertIn(f"listens on: 127.0.0.1:{self.port}", result.stdout) + self.assertRegex(result.stdout, rf"fact: GET http://127\.0\.0\.1:{self.port}/healthz: " + r"HTTP 200, body OK, from gateway pid \d+ on 127\.0\.0\.1:") + self.assertIn(f"fact: GET http://[::1]:{self.port}/healthz: no answer", result.stdout) + + def test_503_then_200_is_ready(self): + result = self.run_smoke("ok", deadline="10", SMOKE_503_COUNT="2") self.assertEqual(result.returncode, 0, result.stderr) - self.assertIn("HTTP 200 and the two bytes OK from pid", result.stdout) - self.assertNotIn(":8090", result.stdout) - - def test_address_injection_exits_two(self): - result = self.run_smoke("ok", addr="127.0.0.1:1@example.com:80") - self.assertEqual(result.returncode, 2, result.stderr) - self.assertNotIn("example.com", result.stdout) - - def test_localhost_name_exits_two(self): - result = self.run_smoke("ok", addr="localhost:8090") - self.assertEqual(result.returncode, 2, result.stderr) - def test_newline_body_exits_one(self): - result = self.run_smoke("newline") + def test_localhost_name_is_probed_as_given(self): + result = self.run_smoke("ok", addr=f"localhost:{self.port}") + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn(f"GET http://localhost:{self.port}/healthz", result.stdout) + self.assertIn("resolves localhost to", result.stdout) + + def test_default_is_the_contract_command(self): + args = Path(self.tmp.name) / "args.json" + env = self.env("exit", SMOKE_ARGS=str(args)) + env.pop("ELASTOS_GATEWAY_ADDR") + result = subprocess.run(["bash", str(SMOKE), str(self.binary)], env=env, + capture_output=True, text=True, timeout=30) self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("two bytes OK", result.stderr) + self.assertEqual(args.read_text(), '["gateway", "--addr", "localhost:8090"]') - def test_prebound_ok_is_not_this_process(self): - from http.server import BaseHTTPRequestHandler, HTTPServer - import threading + @unittest.skipUnless(ipv6_loopback(), "this host has no IPv6 loopback") + def test_ipv6_loopback_ok(self): + port = free_port(socket.AF_INET6, "::1") + result = self.run_smoke("ok", addr=f"[::1]:{port}") + self.assertEqual(result.returncode, 0, result.stderr + result.stdout) + self.assertIn(f"on [::1]:{port}", result.stdout) + + @unittest.skipUnless(ipv6_loopback(), "this host has no IPv6 loopback") + def test_facts_name_another_process_on_the_other_family(self): + # The macOS case: localhost gives ::1 first, so the gateway holds only + # [::1]. Another process on 127.0.0.1 then answers the IPv4 URL. + port = free_port() + self.serve_ok(socket.AF_INET, "127.0.0.1", port) + result = self.run_smoke("ok", addr=f"localhost:{port}", SMOKE_LOCALHOST_BIND="::1") + if f"answered on 127.0.0.1:{port}" in result.stderr: + self.skipTest("curl on this host chose 127.0.0.1 for localhost") + self.assertEqual(result.returncode, 0, result.stdout + result.stderr) + self.assertIn(f"listens on: [::1]:{port}", result.stdout) + self.assertIn(f"fact: GET http://127.0.0.1:{port}/healthz: HTTP 200, body OK, " + f"from another process on 127.0.0.1:{port}", result.stdout) + + # Not ready. + + def test_503_until_deadline_is_not_ready(self): + result = self.run_smoke("always-503", deadline="2") + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("last: HTTP 503", result.stderr) - class Handler(BaseHTTPRequestHandler): - def do_GET(self): - body = b"OK" - self.send_response(200) - self.send_header("Content-Length", str(len(body))) - self.end_headers() - self.wfile.write(body) + def test_other_status_codes_are_refused(self): + for stub in ("redirect", "no-content", "server-error"): + with self.subTest(stub=stub): + result = self.run_smoke(stub) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("Only 200 (ready) or 503 (not ready)", result.stderr) - def log_message(self, *args): - return + def test_other_body_is_refused(self): + for stub in ("other", "newline"): + with self.subTest(stub=stub): + result = self.run_smoke(stub) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("not the two bytes OK", result.stderr) + + def test_lock_that_is_not_this_gateway_is_refused(self): + cases = { + "other-pid": "not gateway pid", + "bad-role": "not gateway", + "bad-addr": "addr is '127.0.0.1:1'", + "none": "missing or is not JSON", + "garbage": "missing or is not JSON", + } + for lock_mode, message in cases.items(): + with self.subTest(lock=lock_mode): + result = self.run_smoke("ok", SMOKE_LOCK=lock_mode) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("host-process.lock", result.stderr) + self.assertIn(message, result.stderr) + self.assertNotIn("ready:", result.stdout) - server = HTTPServer(("127.0.0.1", self.port), Handler) - thread = threading.Thread(target=server.serve_forever, daemon=True) - thread.start() - self.addCleanup(server.server_close) - self.addCleanup(server.shutdown) - result = self.run_smoke("sleep", deadline="3") + def test_ok_from_another_process_on_the_port_is_refused(self): + self.serve_ok(socket.AF_INET, "127.0.0.1", self.port) + result = self.run_smoke("sleep") self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("not gateway pid", result.stderr) + self.assertIn("not a listen socket of gateway pid", result.stderr) + + @unittest.skipUnless(ipv6_loopback(), "this host has no IPv6 loopback") + def test_localhost_answer_on_another_family_is_refused(self): + # The gateway holds 127.0.0.1 and another process holds [::1] on the + # same port. curl tries ::1 first for localhost and gets that OK. + port = free_port() + try: + self.serve_ok(socket.AF_INET6, "::1", port) + except OSError: + self.skipTest("[::1] port is not free") + result = self.run_smoke("ok", addr=f"localhost:{port}", + SMOKE_LOCALHOST_BIND="127.0.0.1") + if "on 127.0.0.1:" in result.stdout: + self.skipTest("curl on this host chose 127.0.0.1 for localhost") + self.assertEqual(result.returncode, 1, result.stdout + result.stderr) + self.assertIn(f"answered on [::1]:{port}", result.stderr) - def test_process_group_is_stopped(self): - child_pid = Path(self.tmp.name) / "child.pid" - env = os.environ.copy() - env["SMOKE_STUB"] = "fork" - env["SMOKE_CHILD_PID"] = str(child_pid) - env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" - env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "1" - result = subprocess.run( - ["bash", str(SMOKE), str(self.binary)], - env=env, - capture_output=True, - text=True, - timeout=15, - ) + def test_early_exit_is_not_ready(self): + result = self.run_smoke("exit", deadline="5") self.assertEqual(result.returncode, 1, result.stderr) - self.assertTrue(child_pid.exists(), result.stderr) - grandchild = int(child_pid.read_text()) - with self.assertRaises(ProcessLookupError): - os.kill(grandchild, 0) + self.assertIn("exited before", result.stderr) - def test_log_is_kept_and_not_echoed(self): - log = Path(self.tmp.name) / "gateway.log" - env = os.environ.copy() - env["SMOKE_STUB"] = "secret" - env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" - env["ELASTOS_GATEWAY_LOG"] = str(log) - env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "3" - result = subprocess.run( - ["bash", str(SMOKE), str(self.binary)], - env=env, - capture_output=True, - text=True, - timeout=15, - ) + def test_no_answer_until_deadline_is_not_ready(self): + result = self.run_smoke("sleep", deadline="1") self.assertEqual(result.returncode, 1, result.stderr) - self.assertNotIn("planted-secret", result.stdout) - self.assertNotIn("planted-secret", result.stderr) - self.assertIn("planted-secret", log.read_text()) - - def test_deadline_must_be_a_positive_integer(self): - marker = Path(self.tmp.name) / "pwned" - for value in ("abc", "-5", "", "0", "x[$(touch %s)]" % marker): - with self.subTest(value=value): - result = self.run_smoke("ok", deadline=value) - self.assertEqual(result.returncode, 2, result.stderr) - self.assertIn("ELASTOS_GATEWAY_HEALTH_DEADLINE", result.stderr) - self.assertFalse(marker.exists()) - - def test_redirect_and_no_content_are_not_success(self): - for stub in ("redirect", "no-content"): - with self.subTest(stub=stub): - result = self.run_smoke(stub) - self.assertEqual(result.returncode, 1, result.stderr) - self.assertIn("HTTP", result.stderr) + self.assertIn("last: no answer", result.stderr) def test_proxy_cannot_supply_the_ok_body(self): - import threading - proxy = socket.socket() proxy.bind(("127.0.0.1", 0)) proxy.listen(1) - proxy_port = proxy.getsockname()[1] + self.addCleanup(proxy.close) def serve_proxy(): try: @@ -271,56 +317,100 @@ def serve_proxy(): connection.sendall(b"HTTP/1.0 200 OK\r\nContent-Length: 2\r\n\r\nOK") connection.close() - thread = threading.Thread(target=serve_proxy, daemon=True) - thread.start() - self.addCleanup(proxy.close) - env = os.environ.copy() - env["SMOKE_STUB"] = "other" - env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" - env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "3" - env["http_proxy"] = f"http://127.0.0.1:{proxy_port}" - env["HTTP_PROXY"] = env["http_proxy"] - result = subprocess.run( - ["bash", str(SMOKE), str(self.binary)], - env=env, capture_output=True, text=True, timeout=15) + threading.Thread(target=serve_proxy, daemon=True).start() + proxy_url = f"http://127.0.0.1:{proxy.getsockname()[1]}" + result = self.run_smoke("other", http_proxy=proxy_url, HTTP_PROXY=proxy_url, + all_proxy=proxy_url, ALL_PROXY=proxy_url) self.assertEqual(result.returncode, 1, result.stdout + result.stderr) - self.assertIn("two bytes OK", result.stderr) + self.assertIn("not the two bytes OK", result.stderr) + + # Input checks fail closed before the gateway starts. + + def test_deadline_must_be_a_whole_number_of_seconds(self): + marker = Path(self.tmp.name) / "pwned" + for value in ("abc", "-5", "", "0", "1.5", " 5", "10000", "07", + "x[$(touch %s)]" % marker): + with self.subTest(value=value): + result = self.run_smoke("ok", deadline=value) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertIn("ELASTOS_GATEWAY_HEALTH_DEADLINE", result.stderr) + self.assertFalse(marker.exists()) + + def test_address_must_be_loopback_host_and_port(self): + for addr in ("0.0.0.0:9", "example.com:80", "127.0.0.1:1@example.com:80", + "localhost", "localhost:0", "localhost:65536", "localhost:08090", + "[::]:8090", "127.0.0.2:8090", ""): + with self.subTest(addr=addr): + result = self.run_smoke("ok", addr=addr) + self.assertEqual(result.returncode, 2, result.stderr) + self.assertIn("loopback host:port", result.stderr) + + def test_missing_binary_exits_one(self): + missing = Path(self.tmp.name) / "missing" + result = subprocess.run(["bash", str(SMOKE), str(missing)], + capture_output=True, text=True, timeout=10) + self.assertEqual(result.returncode, 1, result.stderr) + + # Cleanup stops the whole process group on every exit path. + + def assert_child_stopped(self, result): + self.assertTrue(self.child_pid.exists(), result.stderr) + self.assertTrue(process_gone(int(self.child_pid.read_text())), + "a gateway group member survived the smoke") + + def test_group_is_stopped_after_success(self): + result = self.run_smoke("ok-fork") + self.assertEqual(result.returncode, 0, result.stderr) + self.assert_child_stopped(result) + + def test_group_is_stopped_after_timeout(self): + result = self.run_smoke("fork", deadline="1") + self.assertEqual(result.returncode, 1, result.stderr) + self.assert_child_stopped(result) def test_child_ignoring_term_is_killed(self): - child_pid = Path(self.tmp.name) / "ignore.pid" - env = os.environ.copy() - env["SMOKE_STUB"] = "ignore-term" - env["SMOKE_CHILD_PID"] = str(child_pid) - env["ELASTOS_GATEWAY_ADDR"] = f"127.0.0.1:{self.port}" - env["ELASTOS_GATEWAY_HEALTH_DEADLINE"] = "1" - result = subprocess.run( - ["bash", str(SMOKE), str(self.binary)], - env=env, capture_output=True, text=True, timeout=15) + result = self.run_smoke("ignore-term", deadline="1") self.assertEqual(result.returncode, 1, result.stderr) - self.assertTrue(child_pid.exists(), result.stderr) - grandchild = int(child_pid.read_text()) - with self.assertRaises(ProcessLookupError): - os.kill(grandchild, 0) + self.assert_child_stopped(result) + + def test_group_is_stopped_when_the_smoke_is_interrupted(self): + proc = subprocess.Popen(["bash", str(SMOKE), str(self.binary)], + env=self.env("fork", deadline="60"), + stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) + try: + for _ in range(100): + if self.child_pid.exists() and self.child_pid.read_text(): + break + time.sleep(0.1) + proc.send_signal(signal.SIGTERM) + _, stderr = proc.communicate(timeout=20) + finally: + if proc.poll() is None: + proc.kill() + self.assertEqual(proc.returncode, 143, stderr) + self.assertTrue(process_gone(int(self.child_pid.read_text()))) + + def test_log_is_kept_and_not_echoed(self): + log = Path(self.tmp.name) / "gateway.log" + result = self.run_smoke("secret", ELASTOS_GATEWAY_LOG=str(log)) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertNotIn("planted-secret", result.stdout) + self.assertNotIn("planted-secret", result.stderr) + self.assertIn("planted-secret", log.read_text()) + + # The smoke follows the contract text, which is the one source of truth. - def test_contract_keeps_localhost_and_this_smoke_does_not_bind_it(self): + def test_contract_names_the_command_and_url_this_smoke_uses(self): contract = (ROOT / "docs/LAUNCHER_CONTRACT.md").read_text() + smoke = SMOKE.read_text() self.assertIn("elastos gateway --addr localhost:8090", contract) + self.assertIn("GET http://localhost:8090/healthz", contract) self.assertIn("host-process.lock", contract) + self.assertIn("ELASTOS_GATEWAY_ADDR-localhost:8090", smoke) mac = (ROOT / "docs/MAC.md").read_text() install = (ROOT / "scripts/install.sh").read_text() self.assertIn('die "macOS release lookup requires Apple silicon"', install) self.assertIn("macOS release lookup requires Apple silicon", mac) - self.assertIn("Apple silicon Mac", mac) - self.assertNotIn("gates move together", mac) - result = self.run_smoke("ok", addr="localhost:8090") - self.assertEqual(result.returncode, 2, result.stderr) - - def test_ipv6_loopback_ok(self): - with socket.socket(socket.AF_INET6) as sock: - sock.bind(("::1", 0)) - port = sock.getsockname()[1] - result = self.run_smoke("ok", addr=f"[::1]:{port}") - self.assertEqual(result.returncode, 0, result.stderr + result.stdout) if __name__ == "__main__": diff --git a/scripts/gateway-healthz-smoke.sh b/scripts/gateway-healthz-smoke.sh index fb3cefb25..22e41c59b 100755 --- a/scripts/gateway-healthz-smoke.sh +++ b/scripts/gateway-healthz-smoke.sh @@ -1,46 +1,59 @@ #!/usr/bin/env bash -# Start one elastos gateway and require the /healthz owner check. -# docs/LAUNCHER_CONTRACT.md: HTTP 200 and the two bytes OK when this process -# owns host-process.lock with role gateway or gateway-public. -# An empty Home can pass. This script does not prove providers, capsules, -# or a signed install. elastos serve uses GET /api/health for that status. -# The product command is `elastos gateway --addr localhost:8090`. This script -# binds one numeric loopback socket so the pid check has one listener. It does -# not prove localhost name resolution or port 8090. On macOS, localhost can -# resolve to ::1 while this bind is 127.0.0.1 or [::1]. +# Start one elastos gateway and require the readiness that +# docs/LAUNCHER_CONTRACT.md "Readiness and Home URL" defines: +# GET http://localhost:8090/healthz returns HTTP 200 and the two bytes OK +# while this gateway pid owns {data}/host-process.lock with role gateway +# or gateway-public. +# By default the gateway gets the contract command +# `elastos gateway --addr localhost:8090` and the probe uses the contract URL. +# The probe passes only when: +# - curl gets HTTP 200 and the two bytes OK (no proxy, no redirect), +# - the address curl connected to is a listen socket of the gateway pid, +# - host-process.lock names that pid, a gateway role and the same addr. +# The script then prints facts, not pass or fail: the localhost lookup order, +# the addresses the gateway listens on, and what GET /healthz returns at +# localhost, 127.0.0.1 and [::1] on the same port. +# An empty Home can pass. This does not prove providers, capsules, sign-in, +# or a signed install. set -euo pipefail -if [[ $# -ne 1 || -z "${1:-}" ]]; then +usage() { echo "usage: gateway-healthz-smoke.sh /path/to/elastos" >&2 exit 2 -fi - +} +[[ $# -eq 1 && -n "${1:-}" ]] || usage binary=$1 -if [[ -z "${ELASTOS_GATEWAY_HEALTH_DEADLINE+x}" ]]; then - deadline=120 -else - deadline=$ELASTOS_GATEWAY_HEALTH_DEADLINE -fi + +deadline=${ELASTOS_GATEWAY_HEALTH_DEADLINE-120} if [[ ! "$deadline" =~ ^[1-9][0-9]{0,3}$ ]]; then - echo "ELASTOS_GATEWAY_HEALTH_DEADLINE must be a positive integer" >&2 - exit 2 -fi -if ! command -v curl >/dev/null 2>&1 || ! command -v lsof >/dev/null 2>&1; then - echo "curl and lsof are required" >&2 + echo "ELASTOS_GATEWAY_HEALTH_DEADLINE must be a whole number of seconds from 1 to 9999" >&2 exit 2 fi -if [[ -z "${ELASTOS_GATEWAY_ADDR:-}" ]]; then - port=$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1]); s.close()') - addr="127.0.0.1:${port}" -else - addr=$ELASTOS_GATEWAY_ADDR -fi -# A numeric loopback address keeps the listener check on one socket. -if [[ ! "$addr" =~ ^(127\.0\.0\.1|\[::1\]):[0-9]+$ ]]; then - echo "gateway smoke binds a numeric loopback address: $addr" >&2 +addr=${ELASTOS_GATEWAY_ADDR-localhost:8090} +# Loopback only. localhost is the contract name; the numeric forms are for +# tests that need a free port. +if [[ ! "$addr" =~ ^(localhost|127\.0\.0\.1|\[::1\]):([1-9][0-9]{0,4})$ ]] \ + || (( BASH_REMATCH[2] > 65535 )); then + echo "gateway smoke needs a loopback host:port (localhost, 127.0.0.1 or [::1]): $addr" >&2 exit 2 fi +port=${BASH_REMATCH[2]} + +for tool in curl lsof python3; do + if ! command -v "$tool" >/dev/null 2>&1; then + echo "gateway smoke needs $tool" >&2 + exit 2 + fi +done +case "$(uname -s)" in + Darwin) data_subdir="Library/Application Support/elastos" ;; + Linux) data_subdir=".local/share/elastos" ;; + *) + echo "gateway smoke does not know the data directory on $(uname -s)" >&2 + exit 2 + ;; +esac if [[ ! -x "$binary" ]]; then echo "elastos binary is missing or is not executable: $binary" >&2 exit 1 @@ -48,30 +61,36 @@ fi root=$(mktemp -d) pid= -log= -group_alive() { - kill -0 -"$pid" 2>/dev/null +log="$root/gateway.log" + +# kill -0 succeeds for the group while any member is alive, and for the pid +# until it exits. Check both, in case the group did not form. +gateway_alive() { + kill -0 -- "-$pid" 2>/dev/null || kill -0 "$pid" 2>/dev/null } -stop_gateway() { - if [[ -z "$pid" ]]; then - return 0 - fi - kill -TERM -"$pid" 2>/dev/null || true +signal_gateway() { + kill "-$1" -- "-$pid" 2>/dev/null || true + kill "-$1" "$pid" 2>/dev/null || true +} +wait_gone() { local i - for i in 1 2 3 4 5 6 7 8 9 10; do - group_alive || { wait "$pid" 2>/dev/null || true; return 0; } - sleep 0.2 - done - kill -KILL -"$pid" 2>/dev/null || true - for i in 1 2 3 4 5 6 7 8 9 10; do - group_alive || { wait "$pid" 2>/dev/null || true; return 0; } + for i in $(seq 1 25); do + gateway_alive || return 0 sleep 0.2 done - echo "gateway process group $pid is still running" >&2 + return 1 +} +stop_gateway() { + [[ -n "$pid" ]] || return 0 + signal_gateway TERM + wait_gone && return 0 + signal_gateway KILL + wait_gone && return 0 + echo "gateway process group $pid is still running after SIGKILL" >&2 return 1 } cleanup() { - local status=$? + local status=$1 trap - EXIT INT TERM HUP stop_gateway || status=1 if [[ -n "${ELASTOS_GATEWAY_LOG:-}" && -f "$log" ]]; then @@ -80,48 +99,122 @@ cleanup() { rm -rf "$root" exit "$status" } -trap cleanup EXIT INT TERM HUP +trap 'cleanup $?' EXIT +trap 'cleanup 130' INT +trap 'cleanup 143' TERM +trap 'cleanup 129' HUP export HOME="$root/home" -export XDG_DATA_HOME="$root/home/.local/share" +export XDG_DATA_HOME="$HOME/.local/share" mkdir -p "$HOME" "$XDG_DATA_HOME" -log="$root/gateway.log" +lock="$HOME/$data_subdir/host-process.lock" expect="$root/healthz-expect" body="$root/healthz-body" printf 'OK' >"$expect" -# The new session is the process group. Cleanup signals that group. +# The gateway leads a new session, so its pid is also its process group id. python3 -c 'import os, sys; os.setsid(); os.execv(sys.argv[1], sys.argv[1:])' \ "$binary" gateway --addr "$addr" >"$log" 2>&1 & pid=$! url="http://${addr}/healthz" -port="${addr##*:}" end=$((SECONDS + deadline)) +last="no answer" while true; do if ! kill -0 "$pid" 2>/dev/null; then - echo "gateway exited before /healthz returned OK" >&2 - exit 1 - fi - code=$(curl --noproxy '*' -sS --max-time 2 -o "$body" -w '%{http_code}' "$url" 2>/dev/null || true) - if [[ "$code" == 200 ]]; then - if cmp -s "$expect" "$body"; then - if ! lsof -a -p "$pid" -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then - echo "GET $url responder is not gateway pid $pid" >&2 - exit 1 - fi - echo "GET $url returned HTTP 200 and the two bytes OK from pid $pid" - exit 0 - fi - echo "GET $url body is not the two bytes OK" >&2 - exit 1 - elif [[ -n "$code" && "$code" != 000 ]]; then - echo "GET $url returned HTTP $code" >&2 + echo "gateway exited before GET $url was ready" >&2 exit 1 fi + : >"$body" + answer=$(curl --noproxy '*' --proto =http -sS --max-time 2 -o "$body" \ + -w '%{http_code} %{remote_ip}' "$url" 2>/dev/null || true) + code=${answer%% *} + remote_ip=${answer#* } + case "$code" in + 200) break ;; + 503) last="HTTP 503" ;; + "" | 000) last="no answer" ;; + *) + echo "GET $url returned HTTP $code. Only 200 (ready) or 503 (not ready) is allowed." >&2 + exit 1 + ;; + esac if (( SECONDS >= end )); then - echo "GET $url did not return OK within ${deadline}s" >&2 + echo "GET $url was not ready within ${deadline}s (last: $last)" >&2 exit 1 fi sleep 1 done + +if ! cmp -s "$expect" "$body"; then + echo "GET $url returned HTTP 200, but the body is not the two bytes OK" >&2 + exit 1 +fi +case "$remote_ip" in + 127.0.0.1) socket="127.0.0.1" ;; + ::1) socket="[::1]" ;; + *) + echo "GET $url connected to '$remote_ip', which is not a loopback address" >&2 + exit 1 + ;; +esac +if ! lsof -nP -a -p "$pid" -iTCP@"$socket":"$port" -sTCP:LISTEN >/dev/null 2>&1; then + echo "GET $url was answered on $socket:$port, which is not a listen socket of gateway pid $pid" >&2 + exit 1 +fi +if ! python3 - "$lock" "$pid" "$addr" <<'PY' +import json, sys +path, pid, addr = sys.argv[1], int(sys.argv[2]), sys.argv[3] +try: + with open(path, "rb") as handle: + meta = json.load(handle) +except (OSError, ValueError) as error: + sys.exit(f"host-process.lock is missing or is not JSON: {error}") +if not isinstance(meta, dict): + sys.exit("host-process.lock is not a JSON object") +if meta.get("pid") != pid: + sys.exit(f"host-process.lock names pid {meta.get('pid')!r}, not gateway pid {pid}") +if meta.get("role") not in ("gateway", "gateway-public"): + sys.exit(f"host-process.lock role is {meta.get('role')!r}, not gateway") +if meta.get("addr") != addr: + sys.exit(f"host-process.lock addr is {meta.get('addr')!r}, not {addr}") +PY +then + exit 1 +fi + +echo "ready: GET $url returned HTTP 200 and OK from gateway pid $pid on $socket:$port" +echo "ready: host-process.lock names pid $pid with role gateway and addr $addr" + +# Facts only, not pass or fail: what each loopback spelling of this port +# reaches. A client that uses a different spelling than the gateway's --addr +# can miss the gateway or reach another process. +listening=$(lsof -nP -a -p "$pid" -iTCP:"$port" -sTCP:LISTEN 2>/dev/null \ + | awk 'NR > 1 { print $(NF - 1) }' | sort -u | paste -sd ' ' - || true) +echo "fact: gateway pid $pid listens on: ${listening:-nothing}" +resolved=$(python3 -c 'import socket, sys +seen = [] +for info in socket.getaddrinfo("localhost", int(sys.argv[1]), type=socket.SOCK_STREAM): + if info[4][0] not in seen: + seen.append(info[4][0]) +print(" ".join(seen))' "$port" 2>/dev/null || echo "lookup failed") +echo "fact: this host resolves localhost to (in order): $resolved" +for probe in "localhost:$port" "127.0.0.1:$port" "[::1]:$port"; do + : >"$body" + answer=$(curl --noproxy '*' --proto =http -sS --max-time 2 -o "$body" \ + -w '%{http_code} %{remote_ip}' "http://$probe/healthz" 2>/dev/null || true) + code=${answer%% *} + ip=${answer#* } + if [[ -z "$code" || "$code" == 000 ]]; then + echo "fact: GET http://$probe/healthz: no answer" + continue + fi + case "$ip" in ::1) ip="[::1]" ;; esac + owner="another process" + if lsof -nP -a -p "$pid" -iTCP@"$ip":"$port" -sTCP:LISTEN >/dev/null 2>&1; then + owner="gateway pid $pid" + fi + shown="not OK" + cmp -s "$expect" "$body" && shown="OK" + echo "fact: GET http://$probe/healthz: HTTP $code, body $shown, from $owner on $ip:$port" +done From 0c8d6c72257485ceff79a16f36935d2e5fefa30e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 12:17:42 +0000 Subject: [PATCH 06/12] test: run the gateway smoke stub on macOS The stub always wrote host-process.lock under $XDG_DATA_HOME, but on macOS the smoke reads $HOME/Library/Application Support/elastos, as the real binary does (the dirs crate ignores XDG_DATA_HOME there). So every test that needs a matching lock failed on a Mac. The stub now picks the directory from `uname -s`, as the smoke does, and skips the HTTPServer reverse lookup that can be slow on macOS. Two new tests run the macOS path on Linux with a uname shim: the lock under Library/Application Support is accepted, and a lock under XDG_DATA_HOME is refused. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- scripts/gateway-healthz-smoke-test.py | 49 +++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index 07fbd3bfb..043a78ed5 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -2,10 +2,16 @@ """The gateway smoke accepts contract readiness and refuses every other case. Readiness is defined in docs/LAUNCHER_CONTRACT.md "Readiness and Home URL". -A stub stands in for the elastos binary so each refusal path runs on Linux. +A stub stands in for the elastos binary so each refusal path runs on Linux and +macOS. The stub keeps host-process.lock where the real binary does (the dirs +crate data_dir): $XDG_DATA_HOME/elastos on Linux and +$HOME/Library/Application Support/elastos on macOS, where XDG_DATA_HOME is not +read. It asks `uname -s`, as the smoke does, so a test can run the macOS path +on Linux with a uname shim. """ import os +import shutil import signal import socket import stat @@ -24,7 +30,7 @@ STUB = textwrap.dedent( """\ #!/usr/bin/env python3 - import json, os, signal, socket, sys, time + import json, os, signal, socket, socketserver, subprocess, sys, time from http.server import BaseHTTPRequestHandler, HTTPServer mode = os.environ.get("SMOKE_STUB", "ok") lock_mode = os.environ.get("SMOKE_LOCK", "good") @@ -58,7 +64,11 @@ def fork_sleeper(ignore_term=False): addr = args[2] host, port = addr.rsplit(":", 1) host = host.strip("[]") - data = os.path.join(os.environ["XDG_DATA_HOME"], "elastos") + system = subprocess.run(["uname", "-s"], capture_output=True, text=True).stdout.strip() + if system == "Darwin" and lock_mode != "xdg": + data = os.path.join(os.environ["HOME"], "Library", "Application Support", "elastos") + else: + data = os.path.join(os.environ["XDG_DATA_HOME"], "elastos") os.makedirs(data, exist_ok=True) record = {"pid": os.getpid(), "role": "gateway", "addr": addr} if lock_mode == "other-pid": @@ -105,6 +115,11 @@ def log_message(self, *args): host = os.environ.get("SMOKE_LOCALHOST_BIND", "127.0.0.1") class Server(HTTPServer): address_family = socket.AF_INET6 if ":" in host else socket.AF_INET + def server_bind(self): + # HTTPServer.server_bind also calls socket.getfqdn, a reverse + # lookup that can take seconds on macOS. The smoke does not need it. + socketserver.TCPServer.server_bind(self) + self.server_name, self.server_port = host, int(port) Server((host, int(port)), Handler).serve_forever() """ ) @@ -271,6 +286,34 @@ def test_lock_that_is_not_this_gateway_is_refused(self): self.assertIn(message, result.stderr) self.assertNotIn("ready:", result.stdout) + # macOS keeps the lock under Library/Application Support. A uname shim runs + # that path on Linux too, so Linux CI covers it. + + def darwin_path(self): + real_uname = shutil.which("uname") + self.assertIsNotNone(real_uname, "this host has no uname") + shim = Path(self.tmp.name) / "darwin-bin" + shim.mkdir() + uname = shim / "uname" + uname.write_text('#!/bin/sh\n' + 'if [ "$1" = "-s" ]; then echo Darwin; exit 0; fi\n' + f'exec "{real_uname}" "$@"\n') + uname.chmod(0o755) + return f"{shim}{os.pathsep}{os.environ.get('PATH', '')}" + + def test_macos_lock_is_read_from_application_support(self): + result = self.run_smoke("ok", PATH=self.darwin_path()) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("host-process.lock names pid", result.stdout) + + def test_macos_lock_under_xdg_is_refused(self): + # The real binary does not read XDG_DATA_HOME on macOS, so a lock + # there belongs to nothing this smoke started. + result = self.run_smoke("ok", SMOKE_LOCK="xdg", PATH=self.darwin_path()) + self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("host-process.lock is missing or is not JSON", result.stderr) + self.assertNotIn("ready:", result.stdout) + def test_ok_from_another_process_on_the_port_is_refused(self): self.serve_ok(socket.AF_INET, "127.0.0.1", self.port) result = self.run_smoke("sleep") From 02dcf5b14762661ba9f8cc403b4a4392885a0392 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 12:17:42 +0000 Subject: [PATCH 07/12] ci: run the gateway smoke tests on the Intel Mac runner source-gate runs them on Linux only. The Intel job now runs them before it builds, so the macOS lock path, lsof and localhost order are tested on a Mac. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- .github/workflows/ci.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1aaabd3c7..a898eb931 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1582,6 +1582,11 @@ jobs: [[ "$RUNNER_OS/$RUNNER_ARCH" == macOS/X64 ]] df -Pk . df -Pk . | awk 'NR == 2 { if ($4 < 8 * 1024 * 1024) { print "Intel runner has under 8 GiB free"; exit 1 } }' + # source-gate runs these tests on Linux. Run them here on macOS too, + # where the lock path, lsof and localhost order differ. + - name: smoke script tests on macOS + timeout-minutes: 5 + run: python3 scripts/gateway-healthz-smoke-test.py -v - name: build the gateway binary timeout-minutes: 70 run: | From c38125511df8f086dbf23057a1fdb341e42ff3e0 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 12:42:03 +0000 Subject: [PATCH 08/12] test: give the gateway smoke cleanup tests time to fork test_group_is_stopped_after_timeout and test_child_ignoring_term_is_killed used a 1 second deadline. On a busy host the smoke timed out before the stub had forked its child, so the test failed with no child pid file. It failed 1 of 12 runs here under CPU load, and hosted Intel Macs are slower. A 3 second deadline failed 0 of 12. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- scripts/gateway-healthz-smoke-test.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index 043a78ed5..134402aa4 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -406,13 +406,17 @@ def test_group_is_stopped_after_success(self): self.assertEqual(result.returncode, 0, result.stderr) self.assert_child_stopped(result) + # These two give the stub 3 seconds to start and fork before the smoke + # times out. With 1 second, a slow or busy host (such as a hosted Intel + # Mac) can time out before the child exists, and the test fails. + def test_group_is_stopped_after_timeout(self): - result = self.run_smoke("fork", deadline="1") + result = self.run_smoke("fork", deadline="3") self.assertEqual(result.returncode, 1, result.stderr) self.assert_child_stopped(result) def test_child_ignoring_term_is_killed(self): - result = self.run_smoke("ignore-term", deadline="1") + result = self.run_smoke("ignore-term", deadline="3") self.assertEqual(result.returncode, 1, result.stderr) self.assert_child_stopped(result) From 3cffaad4153e30317b0b8adea88945c580645893 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 17 Oct 2026 12:48:50 +0000 Subject: [PATCH 09/12] docs: state that the Intel smoke gateway listens on every localhost address MAC.md still said --addr localhost:8090 binds only the first address that localhost resolves to. Since ce5d187b (merged from the base) the gateway listens on every loopback address the launcher contract names for localhost. The doc now cites the contract instead of restating the old rule. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- docs/MAC.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/MAC.md b/docs/MAC.md index a00dd30f4..28f7a1b86 100644 --- a/docs/MAC.md +++ b/docs/MAC.md @@ -29,13 +29,11 @@ The job uses an empty Home. A pass does not prove providers, capsules, sign-in, or a signed install. `elastos serve` reports operator status at `GET /api/health`. -`--addr localhost:8090` binds one address only: the first address that the -system lookup gives for `localhost` and that can be bound. When `localhost` -gives `::1` first, `http://127.0.0.1:8090` does not reach the gateway, and -another process can hold that address. After the readiness check, the job log -prints facts, not pass or fail: that lookup order, the address the gateway -listens on, and what `GET /healthz` returns at `localhost:8090`, -`127.0.0.1:8090` and `[::1]:8090`. +For `--addr localhost:8090` the gateway listens on every loopback address that +[the launcher contract](LAUNCHER_CONTRACT.md) names for `localhost`. After the +readiness check, the job log prints facts, not pass or fail: the `localhost` +lookup order, the addresses the gateway listens on, and what `GET /healthz` +returns at `localhost:8090`, `127.0.0.1:8090` and `[::1]:8090`. This runbook claims no local Intel Browser engine. See [Browser support](BROWSER_SUPPORT.md). The job uploads no release tarball. From 630efc6dd749aaa8cf321f4e470d86ee331d3590 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 18 Oct 2026 02:37:19 +0000 Subject: [PATCH 10/12] test: keep the default-command smoke test off the real port 8090 test_default_is_the_contract_command runs the smoke without ELASTOS_GATEWAY_ADDR, so the smoke probes the contract URL http://localhost:8090/healthz. When another program on the test host listened on 8090, curl got its answer before the stub had written its arguments, the smoke stopped early, and the test failed reading args.json. The test now puts a curl on PATH that records its arguments and never connects. It checks the gateway command and that the smoke probed only http://localhost:8090/healthz. It passes with 8090 busy and free. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- scripts/gateway-healthz-smoke-test.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index 134402aa4..09557bf27 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -219,14 +219,35 @@ def test_localhost_name_is_probed_as_given(self): self.assertIn(f"GET http://localhost:{self.port}/healthz", result.stdout) self.assertIn("resolves localhost to", result.stdout) + def no_network_path(self, log): + # A curl that records its arguments and never connects. The default + # address is the contract's localhost:8090, and this test must not + # depend on whatever listens on that port on the test host. + shim = Path(self.tmp.name) / "no-network-bin" + shim.mkdir() + curl = shim / "curl" + curl.write_text('#!/bin/sh\n' + f'printf \'%s\\n\' "$@" >>"{log}"\n' + 'printf 000\n' + 'exit 7\n') + curl.chmod(0o755) + return f"{shim}{os.pathsep}{os.environ.get('PATH', '')}" + def test_default_is_the_contract_command(self): args = Path(self.tmp.name) / "args.json" - env = self.env("exit", SMOKE_ARGS=str(args)) + curl_log = Path(self.tmp.name) / "curl-args.txt" + env = self.env("exit", SMOKE_ARGS=str(args), PATH=self.no_network_path(curl_log)) env.pop("ELASTOS_GATEWAY_ADDR") result = subprocess.run(["bash", str(SMOKE), str(self.binary)], env=env, capture_output=True, text=True, timeout=30) self.assertEqual(result.returncode, 1, result.stderr) self.assertEqual(args.read_text(), '["gateway", "--addr", "localhost:8090"]') + self.assertIn("GET http://localhost:8090/healthz", result.stderr) + if curl_log.exists(): + urls = [line for line in curl_log.read_text().splitlines() + if line.startswith("http")] + self.assertTrue(urls, curl_log.read_text()) + self.assertEqual(set(urls), {"http://localhost:8090/healthz"}) @unittest.skipUnless(ipv6_loopback(), "this host has no IPv6 loopback") def test_ipv6_loopback_ok(self): From ac97a4aa5fb786baf2d4685dea5dd0c35b8b4e8d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 18 Oct 2026 02:39:02 +0000 Subject: [PATCH 11/12] docs: say the smoke checks that the gateway pid holds the host lock The smoke script header and the Intel Mac CI comment said the gateway pid "owns" host-process.lock. The launcher contract says the gateway holds the lock and that the lock proves possession, not identity. Use the contract's word. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- .github/workflows/ci.yml | 2 +- scripts/gateway-healthz-smoke.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a898eb931..5df8dcc4b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1563,7 +1563,7 @@ jobs: # Native Intel Mac proof of gateway readiness as docs/LAUNCHER_CONTRACT.md # defines it: `elastos gateway --addr localhost:8090`, then # GET http://localhost:8090/healthz returns HTTP 200 and OK while that pid - # owns host-process.lock. The Home is empty. This is not a signed release. + # holds host-process.lock. The Home is empty. This is not a signed release. gateway-smoke-macos-intel: name: gateway-smoke-macos-intel runs-on: macos-15-intel diff --git a/scripts/gateway-healthz-smoke.sh b/scripts/gateway-healthz-smoke.sh index 22e41c59b..b403e6961 100755 --- a/scripts/gateway-healthz-smoke.sh +++ b/scripts/gateway-healthz-smoke.sh @@ -2,7 +2,7 @@ # Start one elastos gateway and require the readiness that # docs/LAUNCHER_CONTRACT.md "Readiness and Home URL" defines: # GET http://localhost:8090/healthz returns HTTP 200 and the two bytes OK -# while this gateway pid owns {data}/host-process.lock with role gateway +# while this gateway pid holds {data}/host-process.lock with role gateway # or gateway-public. # By default the gateway gets the contract command # `elastos gateway --addr localhost:8090` and the probe uses the contract URL. From 914acb9a51d3f1e502d86512634bf726040acba3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 18 Oct 2026 14:16:08 +0000 Subject: [PATCH 12/12] test: end every gateway smoke test on an event, not a 3 s deadline The smoke tests gave the stub a 3 s ELASTOS_GATEWAY_HEALTH_DEADLINE. When python3 starts slowly (the macOS /usr/bin/python3 shim, a cold cache, a busy host), the stub needs more than 3 s to write args.json or to bind, the smoke stops it at the deadline, and the test fails. With each python3 start delayed by 1 to 2 s, test_default_is_the_contract_command failed 18 of 30 runs with port 8090 free and 19 of 30 with it busy (FileNotFoundError on args.json). Tests that end on an answer, a refusal or the stub's exit now give the smoke its largest deadline (9999 s), so the deadline cannot end them. The default-command test uses a stub that stays alive until the smoke has run curl once and then exits, so the smoke always ends on "gateway exited before GET http://localhost:8090/healthz was ready", and the test always checks the probed URL. Its curl never connects, so port 8090 does not matter. The four tests that need the deadline to pass (always 503, the two timeout cleanups) put a curl on PATH that waits until the stub listens or has forked, so the first probe always sees that state before the deadline is checked. The interrupt test waits for the child without a 10 s cap. The smoke script is unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01W6Qn9RX7LDqrwiAfNC2F2K --- scripts/gateway-healthz-smoke-test.py | 118 ++++++++++++++++++++------ 1 file changed, 90 insertions(+), 28 deletions(-) diff --git a/scripts/gateway-healthz-smoke-test.py b/scripts/gateway-healthz-smoke-test.py index 09557bf27..c2ef96a66 100644 --- a/scripts/gateway-healthz-smoke-test.py +++ b/scripts/gateway-healthz-smoke-test.py @@ -27,6 +27,16 @@ ROOT = Path(__file__).resolve().parents[1] SMOKE = ROOT / "scripts" / "gateway-healthz-smoke.sh" +# No test may depend on how fast the stub starts. A slow python3 start (the +# macOS /usr/bin/python3 shim, a cold cache, a busy host) can take seconds. +# Tests that end on an event (an answer, a refusal, the stub's exit) give the +# smoke the largest deadline it accepts, so the deadline never ends them. +# Tests that need the deadline to pass first wait for the stub's own event +# before the first probe (see gated_curl_path). HANG_GUARD only stops a hung +# run; no passing run comes near it. +NO_DEADLINE = "9999" +HANG_GUARD = 600 + STUB = textwrap.dedent( """\ #!/usr/bin/env python3 @@ -49,6 +59,14 @@ def fork_sleeper(ignore_term=False): os._exit(0) if mode == "exit": sys.exit(1) + if mode == "exit-after-probe": + # Stay alive until the smoke has run curl once, then exit. The smoke + # must then report the exit; no deadline decides the result. + probed = os.environ["SMOKE_PROBED"] + give_up = time.monotonic() + 600 + while not os.path.exists(probed) and time.monotonic() < give_up: + time.sleep(0.05) + sys.exit(1) if mode == "secret": print("attach_secret=planted-secret", flush=True) sys.exit(1) @@ -120,7 +138,12 @@ def server_bind(self): # lookup that can take seconds on macOS. The smoke does not need it. socketserver.TCPServer.server_bind(self) self.server_name, self.server_port = host, int(port) - Server((host, int(port)), Handler).serve_forever() + server = Server((host, int(port)), Handler) + if "SMOKE_READY" in os.environ: + # The socket is bound and listening, so a probe now reaches the stub. + with open(os.environ["SMOKE_READY"], "w") as handle: + handle.write("ready") + server.serve_forever() """ ) @@ -170,7 +193,7 @@ def setUp(self): self.port = free_port() self.child_pid = Path(self.tmp.name) / "child.pid" - def env(self, stub, addr=None, deadline="3", **extra): + def env(self, stub, addr=None, deadline=NO_DEADLINE, **extra): env = os.environ.copy() env["SMOKE_STUB"] = stub env["SMOKE_CHILD_PID"] = str(self.child_pid) @@ -179,15 +202,37 @@ def env(self, stub, addr=None, deadline="3", **extra): env.update(extra) return env - def run_smoke(self, stub, addr=None, deadline="3", **extra): + def run_smoke(self, stub, addr=None, deadline=NO_DEADLINE, **extra): return subprocess.run( ["bash", str(SMOKE), str(self.binary)], env=self.env(stub, addr, deadline, **extra), capture_output=True, text=True, - timeout=30, + timeout=HANG_GUARD, ) + def gated_curl_path(self, marker): + # A curl that waits until the stub has written to marker, then runs the + # real curl. The smoke checks its deadline only after a probe returns, + # so the first probe always sees the stub at that point, however slow + # the stub was to start. + real_curl = shutil.which("curl") + self.assertIsNotNone(real_curl, "this host has no curl") + shim = Path(self.tmp.name) / "gated-bin" + shim.mkdir() + curl = shim / "curl" + # The wait stops after HANG_GUARD seconds so a broken run cannot + # leave it behind. + curl.write_text('#!/bin/sh\n' + 'i=0\n' + f'while [ ! -s "{marker}" ] && [ "$i" -lt {HANG_GUARD * 20} ]; do\n' + ' sleep 0.05\n' + ' i=$((i + 1))\n' + 'done\n' + f'exec "{real_curl}" "$@"\n') + curl.chmod(0o755) + return f"{shim}{os.pathsep}{os.environ.get('PATH', '')}" + def serve_ok(self, family, host, port): class Server(HTTPServer): address_family = family @@ -210,7 +255,7 @@ def test_ok_with_owned_lock_is_ready(self): self.assertIn(f"fact: GET http://[::1]:{self.port}/healthz: no answer", result.stdout) def test_503_then_200_is_ready(self): - result = self.run_smoke("ok", deadline="10", SMOKE_503_COUNT="2") + result = self.run_smoke("ok", SMOKE_503_COUNT="2") self.assertEqual(result.returncode, 0, result.stderr) def test_localhost_name_is_probed_as_given(self): @@ -234,20 +279,25 @@ def no_network_path(self, log): return f"{shim}{os.pathsep}{os.environ.get('PATH', '')}" def test_default_is_the_contract_command(self): + # The stub writes its arguments first, stays alive until the smoke has + # probed once, then exits. The smoke ends on that exit, not on its + # deadline, so a slow stub start cannot change the result. Nothing + # listens or connects, so it passes whether port 8090 is free or not. args = Path(self.tmp.name) / "args.json" curl_log = Path(self.tmp.name) / "curl-args.txt" - env = self.env("exit", SMOKE_ARGS=str(args), PATH=self.no_network_path(curl_log)) + env = self.env("exit-after-probe", SMOKE_ARGS=str(args), + SMOKE_PROBED=str(curl_log), PATH=self.no_network_path(curl_log)) env.pop("ELASTOS_GATEWAY_ADDR") result = subprocess.run(["bash", str(SMOKE), str(self.binary)], env=env, - capture_output=True, text=True, timeout=30) + capture_output=True, text=True, timeout=HANG_GUARD) self.assertEqual(result.returncode, 1, result.stderr) self.assertEqual(args.read_text(), '["gateway", "--addr", "localhost:8090"]') - self.assertIn("GET http://localhost:8090/healthz", result.stderr) - if curl_log.exists(): - urls = [line for line in curl_log.read_text().splitlines() - if line.startswith("http")] - self.assertTrue(urls, curl_log.read_text()) - self.assertEqual(set(urls), {"http://localhost:8090/healthz"}) + self.assertIn("gateway exited before GET http://localhost:8090/healthz was ready", + result.stderr) + urls = [line for line in curl_log.read_text().splitlines() + if line.startswith("http")] + self.assertTrue(urls, curl_log.read_text()) + self.assertEqual(set(urls), {"http://localhost:8090/healthz"}) @unittest.skipUnless(ipv6_loopback(), "this host has no IPv6 loopback") def test_ipv6_loopback_ok(self): @@ -262,7 +312,9 @@ def test_facts_name_another_process_on_the_other_family(self): # [::1]. Another process on 127.0.0.1 then answers the IPv4 URL. port = free_port() self.serve_ok(socket.AF_INET, "127.0.0.1", port) - result = self.run_smoke("ok", addr=f"localhost:{port}", SMOKE_LOCALHOST_BIND="::1") + ready = Path(self.tmp.name) / "stub-ready" + result = self.run_smoke("ok", addr=f"localhost:{port}", SMOKE_LOCALHOST_BIND="::1", + SMOKE_READY=str(ready), PATH=self.gated_curl_path(ready)) if f"answered on 127.0.0.1:{port}" in result.stderr: self.skipTest("curl on this host chose 127.0.0.1 for localhost") self.assertEqual(result.returncode, 0, result.stdout + result.stderr) @@ -273,7 +325,11 @@ def test_facts_name_another_process_on_the_other_family(self): # Not ready. def test_503_until_deadline_is_not_ready(self): - result = self.run_smoke("always-503", deadline="2") + # The first probe waits until the stub listens, so it gets a 503 + # before the 1 s deadline can pass. + ready = Path(self.tmp.name) / "stub-ready" + result = self.run_smoke("always-503", deadline="1", SMOKE_READY=str(ready), + PATH=self.gated_curl_path(ready)) self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("last: HTTP 503", result.stderr) @@ -358,7 +414,7 @@ def test_localhost_answer_on_another_family_is_refused(self): self.assertIn(f"answered on [::1]:{port}", result.stderr) def test_early_exit_is_not_ready(self): - result = self.run_smoke("exit", deadline="5") + result = self.run_smoke("exit") self.assertEqual(result.returncode, 1, result.stderr) self.assertIn("exited before", result.stderr) @@ -412,7 +468,7 @@ def test_address_must_be_loopback_host_and_port(self): def test_missing_binary_exits_one(self): missing = Path(self.tmp.name) / "missing" result = subprocess.run(["bash", str(SMOKE), str(missing)], - capture_output=True, text=True, timeout=10) + capture_output=True, text=True, timeout=HANG_GUARD) self.assertEqual(result.returncode, 1, result.stderr) # Cleanup stops the whole process group on every exit path. @@ -427,31 +483,37 @@ def test_group_is_stopped_after_success(self): self.assertEqual(result.returncode, 0, result.stderr) self.assert_child_stopped(result) - # These two give the stub 3 seconds to start and fork before the smoke - # times out. With 1 second, a slow or busy host (such as a hosted Intel - # Mac) can time out before the child exists, and the test fails. + # These two need the deadline to pass after the stub has forked. The first + # probe waits until the child has written its pid, so the 1 s deadline can + # only pass after the child exists, however slow the host is. def test_group_is_stopped_after_timeout(self): - result = self.run_smoke("fork", deadline="3") + result = self.run_smoke("fork", deadline="1", + PATH=self.gated_curl_path(self.child_pid)) self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("was not ready within 1s", result.stderr) self.assert_child_stopped(result) def test_child_ignoring_term_is_killed(self): - result = self.run_smoke("ignore-term", deadline="3") + result = self.run_smoke("ignore-term", deadline="1", + PATH=self.gated_curl_path(self.child_pid)) self.assertEqual(result.returncode, 1, result.stderr) + self.assertIn("was not ready within 1s", result.stderr) self.assert_child_stopped(result) def test_group_is_stopped_when_the_smoke_is_interrupted(self): proc = subprocess.Popen(["bash", str(SMOKE), str(self.binary)], - env=self.env("fork", deadline="60"), + env=self.env("fork"), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) try: - for _ in range(100): - if self.child_pid.exists() and self.child_pid.read_text(): - break - time.sleep(0.1) + # Signal only after the child exists, however long that takes. + guard = time.monotonic() + HANG_GUARD + while not (self.child_pid.exists() and self.child_pid.read_text()): + self.assertIsNone(proc.poll(), "the smoke ended before the stub forked") + self.assertLess(time.monotonic(), guard, "the stub never forked") + time.sleep(0.05) proc.send_signal(signal.SIGTERM) - _, stderr = proc.communicate(timeout=20) + _, stderr = proc.communicate(timeout=HANG_GUARD) finally: if proc.poll() is None: proc.kill()