nullforge 0.1.0__py3-none-any.whl

nullforge/smithy/github.py

@@ -0,0 +1,256 @@
+"""GitHub release metadata helpers for NullForge.
+
+These run on the *control node* at plan time (like `fetch_github_keys`), not on the
+target. They resolve checksums and detect the right asset for a release so that the
+target-side installers in `smithy/install.py` can verify downloads and, optionally,
+pick assets without a hand-written URL per tool.
+
+Everything degrades gracefully: if the API is unreachable or rate-limited, resolvers
+return ``None`` and callers fall back to their existing (unverified) behaviour. Set
+``GITHUB_TOKEN`` (or ``GH_TOKEN``) in the control-node environment to raise the API
+rate limit from 60 to 5000 requests/hour.
+"""
+
+import json
+import logging
+import os
+import re
+from contextlib import suppress
+
+from nullforge.smithy.arch import arch_id
+from nullforge.smithy.http import fetch_text
+
+
+LOG = logging.getLogger("pyinfra")
+
+GITHUB_API = "https://api.github.com"
+"""REST API base; queried from the control node only."""
+
+_DOWNLOAD_URL_RE = re.compile(
+    r"^https://github\.com/(?P<repo>[^/]+/[^/]+)/releases/"
+    r"(?:download/(?P<tag>[^/]+)|(?P<latest>latest)/download)/(?P<asset>[^/]+)$"
+)
+"""Matches the release-asset URLs produced by `Versions._release_url`."""
+
+_CHECKSUM_HINTS = ("checksum", "sha256", "sha256sums", "sha256sum")
+"""Substrings that flag an assets-wide checksums manifest."""
+
+_SHA256_RE = re.compile(r"\b[0-9a-f]{64}\b")
+
+_RELEASE_CACHE: dict[tuple[str, str], dict | None] = {}
+"""Per-run cache so a single deploy hits the API at most once per (repo, tag)."""
+
+# Arch/OS token synonyms, mirroring how release assets are commonly named.
+_ARCH_TOKENS: dict[str, tuple[str, ...]] = {
+    "x86_64": ("x86_64", "amd64", "x64", "64bit"),
+    "arm64": ("arm64", "aarch64"),
+}
+_ALL_ARCH_TOKENS = {token for tokens in _ARCH_TOKENS.values() for token in tokens}
+_OS_TOKENS: dict[str, tuple[str, ...]] = {
+    "linux": ("linux",),
+    "darwin": ("darwin", "macos", "apple"),
+    "windows": ("windows", "win"),
+}
+_ALL_OS_TOKENS = {token for tokens in _OS_TOKENS.values() for token in tokens}
+
+# Assets that are never the binary we want.
+_NON_BINARY_SUFFIXES = (".sha256", ".sha256sum", ".sig", ".asc", ".pem", ".pub", ".txt", ".sbom", ".json")
+
+
+def _token() -> str | None:
+    return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
+def _headers() -> dict[str, str]:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    token = _token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def fetch_release(repo: str, tag: str) -> dict | None:
+    """Fetch release metadata for ``owner/repo`` at ``tag`` (``"latest"`` supported).
+
+    Returns the parsed JSON object, or ``None`` on any failure (unreachable API,
+    rate limit, unknown tag). Results are cached for the duration of the run.
+    """
+
+    cache_key = (repo, tag)
+    if cache_key in _RELEASE_CACHE:
+        return _RELEASE_CACHE[cache_key]
+
+    path = "releases/latest" if tag == "latest" else f"releases/tags/{tag}"
+    url = f"{GITHUB_API}/repos/{repo}/{path}"
+    release: dict | None = None
+    try:
+        release = json.loads(fetch_text(url, headers=_headers()))
+    except Exception as exc:  # noqa: BLE001 - network/JSON errors all degrade to None
+        LOG.warning(f"GitHub release lookup failed for {repo}@{tag}: {exc}")
+
+    _RELEASE_CACHE[cache_key] = release
+    return release
+
+
+def _find_asset(release: dict, asset_name: str) -> dict | None:
+    for asset in release.get("assets", []):
+        if asset.get("name") == asset_name:
+            return asset
+    return None
+
+
+def _digest_sha256(asset: dict) -> str | None:
+    """Read the API-provided ``digest`` field (``"sha256:<hex>"``) if present."""
+
+    digest = asset.get("digest") or ""
+    prefix = "sha256:"
+    if digest.startswith(prefix):
+        candidate = digest[len(prefix) :].strip().lower()
+        if _SHA256_RE.fullmatch(candidate):
+            return candidate
+    return None
+
+
+def _sha256_from_manifest(release: dict, asset_name: str) -> str | None:
+    """Locate a checksums asset in the release and parse the line for ``asset_name``."""
+
+    for asset in release.get("assets", []):
+        name = (asset.get("name") or "").lower()
+        is_per_asset = name == f"{asset_name.lower()}.sha256"
+        is_manifest = any(hint in name for hint in _CHECKSUM_HINTS)
+        if not (is_per_asset or is_manifest):
+            continue
+
+        url = asset.get("browser_download_url")
+        if not url:
+            continue
+        with suppress(Exception):
+            body = fetch_text(url)
+            found = _parse_checksums(body, asset_name)
+            if found:
+                return found
+    return None
+
+
+def _parse_checksums(body: str, asset_name: str) -> str | None:
+    """Extract the sha256 for ``asset_name`` from a checksums file body.
+
+    Supports both multi-asset manifests (``<hex>  <name>`` / ``<hex> *<name>``) and
+    single-asset files that contain only the hash (optionally with a filename).
+    """
+
+    target = asset_name.rsplit("/", 1)[-1]
+    lone: str | None = None
+    for raw in body.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        match = _SHA256_RE.search(line)
+        if not match:
+            continue
+        digest = match.group(0).lower()
+        rest = (line[: match.start()] + line[match.end() :]).strip().lstrip("*").strip()
+        if not rest:
+            lone = digest  # bare "<hex>" — remember as a single-asset fallback
+            continue
+        if rest.rsplit("/", 1)[-1].lstrip("*") == target:
+            return digest
+    return lone
+
+
+def asset_sha256(release: dict, asset_name: str) -> str | None:
+    """Best-effort sha256 for ``asset_name``: API digest first, then a checksums file."""
+
+    asset = _find_asset(release, asset_name)
+    if asset is not None:
+        digest = _digest_sha256(asset)
+        if digest:
+            return digest
+    return _sha256_from_manifest(release, asset_name)
+
+
+def parse_download_url(url: str) -> tuple[str, str, str] | None:
+    """Split a GitHub release-asset URL into ``(repo, tag, asset_name)``.
+
+    Returns ``None`` for anything that is not a matching GitHub release URL (including
+    non-string input), so callers degrade to "no checksum" rather than raising.
+    """
+
+    if not isinstance(url, str):
+        return None
+    match = _DOWNLOAD_URL_RE.match(url)
+    if not match:
+        return None
+    tag = "latest" if match.group("latest") else match.group("tag")
+    return match.group("repo"), tag, match.group("asset")
+
+
+def sha256_for_download_url(url: str) -> str | None:
+    """Resolve the sha256 for a release-asset download URL, or ``None`` if unavailable.
+
+    This is the ergonomic entry point: any URL from `Versions` (e.g. ``telemt_tar()``)
+    can be verified without knowing its repo/tag/asset separately.
+    """
+
+    parsed = parse_download_url(url)
+    if parsed is None:
+        return None
+    repo, tag, asset_name = parsed
+    release = fetch_release(repo, tag)
+    if release is None:
+        return None
+    return asset_sha256(release, asset_name)
+
+
+def select_asset(
+    release: dict,
+    *,
+    arch: str | None = None,
+    os_name: str = "linux",
+    include: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+) -> dict | None:
+    """Pick the release asset best matching the current arch/OS (bin-style matcher).
+
+    Scores each asset by OS/arch token match and ``include`` hints, rejecting assets
+    that clearly target a different OS or arch. Returns the highest-scoring asset dict,
+    or ``None`` when nothing matches. Useful for tools whose asset names are awkward to
+    template, or for resolving a concrete asset from a ``latest`` release.
+    """
+
+    want_arch = arch or arch_id()
+    arch_tokens = _ARCH_TOKENS.get(want_arch, (want_arch,))
+    os_tokens = _OS_TOKENS.get(os_name, (os_name,))
+
+    best: dict | None = None
+    best_score = 0
+    for asset in release.get("assets", []):
+        name = (asset.get("name") or "").lower()
+        if not name or name.endswith(_NON_BINARY_SUFFIXES):
+            continue
+        if any(bad in name for bad in exclude):
+            continue
+
+        # Reject assets that name a different OS/arch than the one we want.
+        if any(tok in name for tok in _ALL_OS_TOKENS) and not any(tok in name for tok in os_tokens):
+            continue
+        if any(tok in name for tok in _ALL_ARCH_TOKENS) and not any(tok in name for tok in arch_tokens):
+            continue
+
+        score = 1
+        if any(tok in name for tok in os_tokens):
+            score += 2
+        if any(tok in name for tok in arch_tokens):
+            score += 2
+        score += sum(1 for hint in include if hint.lower() in name)
+        # Prefer gnu over musl when both are published, all else equal.
+        if "gnu" in name:
+            score += 1
+
+        if score > best_score:
+            best, best_score = asset, score
+
+    return best

nullforge/smithy/http.py

@@ -0,0 +1,85 @@
+"""HTTP utilities for NullForge."""
+
+import logging
+import urllib.request
+
+from pyinfra.context import host
+from pyinfra.facts.server import Command
+
+
+LOG = logging.getLogger("pyinfra")
+
+
+CURL_FLAGS = (
+    "--compressed",
+    "--fail",
+    "--retry-connrefused",
+    "--tlsv1.2",
+)
+"""Curl options that take no value."""
+
+CURL_ARGS = {
+    "--retry": "3",
+    "--connect-timeout": "10",
+    "--max-time": "120",
+    "--proto": "=https",
+}
+"""Robust curl options for reliable downloads."""
+
+CURL_ARGS_STR = " ".join((*CURL_FLAGS, *(f"{k} {v}" for k, v in CURL_ARGS.items())))
+"""String representation of curl arguments."""
+
+GITHUB_KEYS_URL = "https://github.com/{user}.keys"
+"""Public endpoint serving user's authorized SSH public keys."""
+
+
+def reachable_address(hostname: str, port: int = 443) -> str | None:
+    """First address of `hostname` this host can actually talk HTTPS to, if any."""
+
+    cache_key = f"_nullforge_reachable_{hostname}"
+    if hasattr(host.data, cache_key):
+        return getattr(host.data, cache_key)
+
+    address = None
+    listed = host.get_fact(Command, f"getent ahostsv4 {hostname} | awk '{{print $1}}' | sort -u || true")
+    for candidate in str(listed or "").split():
+        # HTTPS answer proves path works; status code is irrelevant
+        probe = f"curl -sS -o /dev/null --connect-timeout 5 --resolve {hostname}:{port}:{candidate} https://{hostname}/"
+        if str(host.get_fact(Command, f"{probe} >/dev/null 2>&1 && echo reachable || true") or "").strip():
+            address = candidate
+            break
+
+    setattr(host.data, cache_key, address)
+    return address
+
+
+def pin_host_args(hostname: str, port: int = 443) -> dict[str, str]:
+    address = reachable_address(hostname, port)
+    return {"--resolve": f"{hostname}:{port}:{address}"} if address else {}
+
+
+def fetch_text(url: str, *, timeout: int = 10, headers: dict[str, str] | None = None) -> str:
+    """Fetch text from HTTPS URL on control node."""
+
+    if not url.startswith("https://"):
+        raise ValueError(f"Refusing non-HTTPS URL: {url}")
+
+    headers = headers or {}
+    request = urllib.request.Request(url, headers=headers)  # noqa: S310 - https-only guard above
+    with urllib.request.urlopen(request, timeout=timeout) as resp:  # noqa: S310 - https-only guard above
+        return resp.read().decode("utf-8")
+
+
+def fetch_github_keys(username: str | None) -> list[str]:
+    """Fetch public SSH keys for GitHub user."""
+
+    if not username:
+        return []
+
+    try:
+        contents = fetch_text(GITHUB_KEYS_URL.format(user=username))
+    except Exception as e:
+        LOG.warning(f"Failed to fetch GitHub SSH keys for '{username}': {e}")
+        return []
+
+    return contents.splitlines()

nullforge/smithy/install.py

@@ -0,0 +1,149 @@
+"""Release-binary installation helper for NullForge.
+
+`install_release_binary` "centralises download -> verify -> extract -> locate -> install"
+dance that every pinned-tool rune used to hand-roll.
+
+- auto-detect archive format from URL (tar.gz/xz/bz2, plain tar, zip, gzip, or raw/AppImage binary)
+- verifies download against sha256, resolving it from GitHub release metadata when not supplied
+- extracts and locates executable inside the archive, and installs it to `dest` with requested mode
+"""
+
+import shlex
+from pathlib import PurePosixPath
+
+from pyinfra import logger
+from pyinfra.api.operation import OperationMeta
+from pyinfra.operations import files, server
+
+from nullforge.smithy.github import sha256_for_download_url
+from nullforge.smithy.versions import Versions
+
+
+STAGING_DIR = "/var/lib/nullforge/staging"
+"""Scratch space for archives and their extracted contents."""
+
+
+# Archive kind -> the tar/unzip/gunzip commands that unpack it into `workdir`.
+_TAR_FLAGS = {
+    "tar.gz": "-xzf",
+    "tar.xz": "-xJf",
+    "tar.bz2": "-xjf",
+    "tar": "-xf",
+}
+# Ordered longest-suffix-first so `.tar.gz` wins over `.gz`.
+_SUFFIX_KINDS: tuple[tuple[str, str], ...] = (
+    (".tar.gz", "tar.gz"),
+    (".tgz", "tar.gz"),
+    (".tar.xz", "tar.xz"),
+    (".txz", "tar.xz"),
+    (".tar.bz2", "tar.bz2"),
+    (".tbz2", "tar.bz2"),
+    (".tar", "tar"),
+    (".zip", "zip"),
+    (".appimage", "raw"),
+    (".gz", "gzip"),
+)
+
+
+def detect_archive(url_or_name: str) -> str:
+    """Classify URL/filename as `tar.gz`/`tar.xz`/`tar.bz2`/`tar`/`zip`/`gzip`/`raw`."""
+
+    name = url_or_name.rsplit("/", 1)[-1].lower()
+    for suffix, kind in _SUFFIX_KINDS:
+        if name.endswith(suffix):
+            return kind
+    return "raw"
+
+
+def _extract_commands(kind: str, archive: str, workdir: str, binary_name: str) -> list[str]:
+    if kind in _TAR_FLAGS:
+        return [f"tar {_TAR_FLAGS[kind]} {shlex.quote(archive)} -C {shlex.quote(workdir)}"]
+    if kind == "zip":
+        return [f"unzip -o {shlex.quote(archive)} -d {shlex.quote(workdir)}"]
+    if kind == "gzip":
+        target = f"{workdir}/{binary_name}"
+        return [f"gunzip -c {shlex.quote(archive)} > {shlex.quote(target)}"]
+    raise ValueError(f"{kind} is not an extractable archive kind")
+
+
+def install_release_binary(
+    *,
+    name: str,
+    url: str,
+    dest: str,
+    binary_name: str | None = None,
+    sha256: str | None = None,
+    verify: bool = True,
+    archive: str | None = None,
+    mode: str = "0755",
+    sudo: bool = True,
+    retries: int = 3,
+    retry_delay: int = 10,
+) -> OperationMeta:
+    """Download, verify, extract and install release binary; return install operation.
+
+    `url` is a release-asset URL, usually straight from `Versions` builder,
+    and `dest` is absolute path executable ends up at; `name` is what pyinfra prints for install op.
+
+    Integrity is best-effort by design: `sha256` pins checksum, and leaving it unset has `verify`
+    resolve one from `url`'s GitHub release metadata instead.
+    A repo that publishes no checksums therefore installs unverified.
+
+    Archive kind is detected from `url` unless `archive` forces one, and executable is picked out
+    of it by `binary_name`, which defaults to `dest` basename.
+    """
+
+    binary_name = binary_name or PurePosixPath(dest).name
+    kind = archive or detect_archive(url)
+    checksum = sha256 if sha256 is not None else (sha256_for_download_url(url) if verify else None)
+    if verify and checksum is None:
+        logger.warning(f"No sha256 could be resolved for {url}; installing {name} without integrity verification")
+    curl_args = Versions.release_curl_args()
+
+    if kind == "raw":
+        return files.download(
+            name=name,
+            src=url,
+            dest=dest,
+            mode=mode,
+            force=True,
+            sha256sum=checksum,
+            extra_curl_args=curl_args,
+            _sudo=sudo,
+            _retries=retries,
+            _retry_delay=retry_delay,
+        )
+
+    download_path = f"{STAGING_DIR}/{PurePosixPath(url).name}"
+    workdir = f"{STAGING_DIR}/{binary_name}"
+
+    files.directory(
+        name=f"Ensure staging directory for {name}",
+        path=STAGING_DIR,
+        mode="0700",
+        _sudo=sudo,
+    )
+
+    files.download(
+        name=f"Download {name}",
+        src=url,
+        dest=download_path,
+        force=True,
+        sha256sum=checksum,
+        extra_curl_args=curl_args,
+        _sudo=sudo,
+        _retries=retries,
+        _retry_delay=retry_delay,
+    )
+
+    located = f'"$(find {shlex.quote(workdir)} -type f -name {shlex.quote(binary_name)} | head -n1)"'
+    return server.shell(
+        name=name,
+        commands=[
+            f"rm -rf {shlex.quote(workdir)} && mkdir -p {shlex.quote(workdir)}",
+            *_extract_commands(kind, download_path, workdir, binary_name),
+            f"install -D -m {mode} {located} {shlex.quote(dest)}",
+            f"rm -rf {shlex.quote(workdir)} {shlex.quote(download_path)}",
+        ],
+        _sudo=sudo,
+    )

nullforge/smithy/monitoring/__init__.py

@@ -0,0 +1 @@
+"""Monitoring backend provisioning helpers for NullForge."""

nullforge/smithy/monitoring/nezha/agent.py

@@ -0,0 +1,54 @@
+"""Nezha monitoring agent install builders."""
+
+from __future__ import annotations
+
+import shlex
+import uuid
+
+
+def agent_uuid_for_hostname(hostname: str, namespace: uuid.UUID | str | None = None) -> str:
+    if not isinstance(hostname, (str, bytes)):
+        hostname = str(hostname) if hostname is not None else ""
+    if namespace is None:
+        ns = uuid.NAMESPACE_DNS
+    elif isinstance(namespace, uuid.UUID):
+        ns = namespace
+    else:
+        ns = uuid.UUID(namespace)
+    return str(uuid.uuid5(ns, hostname))
+
+
+def build_nezha_install_command(
+    *,
+    install_url: str,
+    curl_args: str,
+    server: str,
+    tls: bool,
+    client_secret: str,
+    agent_uuid: str,
+    disable_auto_update: bool = False,
+    disable_command_execute: bool = False,
+) -> str:
+    """Build shell one-liner that downloads and runs official Nezha agent installer."""
+
+    env = {
+        "NZ_SERVER": server,
+        "NZ_TLS": "true" if tls else "false",
+        "NZ_CLIENT_SECRET": client_secret,
+        "NZ_UUID": agent_uuid,
+        "NZ_DISABLE_AUTO_UPDATE": "true" if disable_auto_update else "false",
+        "NZ_DISABLE_COMMAND_EXECUTE": "true" if disable_command_execute else "false",
+    }
+    env_str = " ".join(f"{key}={shlex.quote(value)}" for key, value in env.items())
+    script = '"$script"'
+
+    # if github download fails, retry the same install via mirror
+    run_install = f"env {env_str} {script} || env CN=true {env_str} {script}"
+
+    return (
+        f"script=$(mktemp) "
+        f"&& curl -L {curl_args} {shlex.quote(install_url)} -o {script} "
+        f"&& chmod +x {script} "
+        f"&& {{ {run_install}; }}; "
+        f"rc=$?; rm -f {script}; exit $rc"
+    )

nullforge/smithy/monitoring/nezha/dashboard.py

@@ -0,0 +1,137 @@
+"""Nezha dashboard REST client."""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.request
+from time import sleep
+from typing import Any
+
+
+LOG = logging.getLogger("pyinfra")
+
+REGISTER_POLL_ATTEMPTS = 20
+"""How many times to poll dashboard for freshly-registered agent."""
+
+REGISTER_POLL_DELAY = 3
+"""Seconds between registration polls."""
+
+HTTP_TIMEOUT = 10
+"""Request timeout, in seconds, for dashboard API calls."""
+
+USER_AGENT = "nullforge-nezha-client/1.0"
+"""Sent on every dashboard request."""
+
+
+def _api_request(
+    url: str,
+    token: str,
+    *,
+    method: str = "GET",
+    payload: dict[str, object] | None = None,
+) -> dict[str, Any]:
+    """Issue authenticated dashboard API request and return parsed envelope."""
+
+    if not url.startswith(("https://", "http://")):
+        raise ValueError(f"Refusing dashboard URL with unsupported scheme: {url}")
+    if url.startswith("http://"):
+        LOG.warning(f"Dashboard URL {url} is not HTTPS - the API token is sent in cleartext")
+
+    data = json.dumps(payload).encode("utf-8") if payload is not None else None
+    request = urllib.request.Request(url, data=data, method=method)  # noqa: S310 - scheme checked above
+    request.add_header("Authorization", f"Bearer {token}")
+    request.add_header("User-Agent", USER_AGENT)
+    if data is not None:
+        request.add_header("Content-Type", "application/json")
+
+    try:
+        with urllib.request.urlopen(request, timeout=HTTP_TIMEOUT) as response:  # noqa: S310 - scheme checked above
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", "replace").strip()
+        raise RuntimeError(
+            f"Dashboard API {method} {url} failed ({e.code} {e.reason}): {detail or '<empty body>'}"
+        ) from e
+
+    parsed: Any = json.loads(body) if body else {}
+    if not isinstance(parsed, dict):
+        raise ValueError(f"Unexpected dashboard response shape from {url}: {type(parsed)!r}")
+    if parsed.get("success") is False:
+        raise RuntimeError(f"Dashboard API error from {url}: {parsed.get('error', 'unknown error')}")
+    return parsed
+
+
+def _find_server(list_url: str, token: str, agent_uuid: str) -> tuple[int | None, str | None]:
+    envelope = _api_request(list_url, token)
+    servers = envelope.get("data")
+    if not isinstance(servers, list):
+        return None, None
+
+    for entry in servers:
+        if isinstance(entry, dict) and entry.get("uuid") == agent_uuid:
+            server_id = entry.get("id")
+            name = entry.get("name")
+            if isinstance(server_id, int):
+                return server_id, (name if isinstance(name, str) else None)
+    return None, None
+
+
+def server_name_matches(
+    *,
+    dashboard_url: str,
+    api_token: str,
+    agent_uuid: str,
+    desired_name: str,
+) -> bool:
+    """Whether the dashboard already lists `agent_uuid` under `desired_name`."""
+
+    try:
+        server_id, current_name = _find_server(f"{dashboard_url}/api/v1/server", api_token, agent_uuid)
+    except (RuntimeError, ValueError, OSError, json.JSONDecodeError) as e:
+        LOG.warning(f"Could not read Nezha dashboard entry for {agent_uuid}: {e}")
+        return False
+
+    return server_id is not None and current_name == desired_name
+
+
+def rename_nezha_server(
+    *,
+    dashboard_url: str,
+    api_token: str,
+    agent_uuid: str,
+    desired_name: str,
+) -> None:
+    """Rename auto-registered dashboard entry for `agent_uuid` to `desired_name`."""
+
+    list_url = f"{dashboard_url}/api/v1/server"
+
+    server_id: int | None = None
+    current_name: str | None = None
+    for attempt in range(REGISTER_POLL_ATTEMPTS):
+        # _api_request raises RuntimeError (with the dashboard's error body) on HTTP
+        # errors such as 403; a hard failure propagates instead of pointlessly polling.
+        server_id, current_name = _find_server(list_url, api_token, agent_uuid)
+        if server_id is not None:
+            break
+        if attempt < REGISTER_POLL_ATTEMPTS - 1:
+            sleep(REGISTER_POLL_DELAY)
+
+    if server_id is None:
+        LOG.warning(
+            f"Nezha agent {agent_uuid} did not register within {REGISTER_POLL_ATTEMPTS * REGISTER_POLL_DELAY}s; "
+            f"skipping rename to {desired_name}",
+        )
+        return
+
+    if current_name == desired_name:
+        return
+
+    _api_request(
+        f"{dashboard_url}/api/v1/server/{server_id}",
+        api_token,
+        method="PATCH",
+        payload={"name": desired_name},
+    )
+    LOG.info(f"Renamed Nezha server {server_id} to {desired_name}")