EmbeddedProto 4.0.0b1__py3-none-any.whl

EmbeddedProto/config.py

@@ -0,0 +1,173 @@
+#
+# Copyright (C) 2020-2026 Embedded AMS B.V. - All Rights Reserved
+#
+# This file is part of Embedded Proto.
+#
+# Embedded Proto is dual licensed. You may use it under the terms of the
+# GNU General Public License version 3 (GPLv3) as published by the Free
+# Software Foundation, or under a commercial license from Embedded AMS B.V.
+#
+# Under the GPLv3 you must release the source code of
+# any product you distribute that includes Embedded Proto or code
+# generated by it. A commercial license removes that obligation.
+# See <https://embeddedproto.com/pricing/>.
+#
+# Embedded Proto is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the LICENSE file in the root of the repository for details.
+#
+# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-EmbeddedProto-Commercial
+#
+# Embedded AMS B.V., Hoorn, the Netherlands - info at EmbeddedProto dot com
+#
+
+"""Read and write the EmbeddedProto user config file.
+
+A single per-user INI file holds non-secret defaults for the license plugin:
+the optional build token and the license server URL. It lives at
+``${XDG_CONFIG_HOME:-~/.config}/embeddedproto/config.ini`` (POSIX) or
+``%APPDATA%\\embeddedproto\\config.ini`` (Windows).
+
+The file is optional in every sense: a missing file means "use the built-in
+defaults", and an exported ``EMBEDDEDPROTO_*`` environment variable always wins
+over the file (see ``custom_header.py``). INI is used so the whole thing stays
+in the standard library (``configparser``) with no extra dependency; TOML has no
+standard-library writer and ``tomllib`` only reads on Python 3.11+.
+"""
+
+import configparser
+import os
+import sys
+
+# The default license server. Defined here (the lowest-level module) so both
+# the config template and custom_header.py can reference one source of truth.
+DEFAULT_SERVER_URL = "https://license.embeddedproto.com/v1/header"
+
+_SECTION = "license"
+
+# The commented template written on first run / when (re)setting values. The two
+# placeholders are filled with the current token and server URL. Keeping the file
+# rendered from this template (rather than via configparser.write) preserves the
+# explanatory comments across updates.
+_TEMPLATE = """\
+[{section}]
+# Your build token. Leave empty to read EMBEDDEDPROTO_BUILD_TOKEN from the
+# environment instead (recommended for CI / shared machines).
+token = {token}
+
+# License server endpoint (must be https://). Point at a staging server to test.
+server_url = {server_url}
+"""
+
+
+def _warn(message):
+    """Write a hygiene warning to stderr. Never includes the token value."""
+    sys.stderr.write("EmbeddedProto license config: " + message + "\n")
+
+
+def _config_dir():
+    """Platform path to the per-user EmbeddedProto config directory."""
+    if os.name == "nt":
+        base = os.environ.get("APPDATA")
+        return os.path.join(base, "embeddedproto") if base else None
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(
+        os.path.expanduser("~"), ".config")
+    return os.path.join(base, "embeddedproto")
+
+
+def config_path():
+    """Full path to ``config.ini`` or None when no config dir can be resolved."""
+    directory = _config_dir()
+    return os.path.join(directory, "config.ini") if directory else None
+
+
+def _check_owner_only(path):
+    """True if ``path`` is safe to read a secret from (POSIX owner-only).
+
+    On non-POSIX systems we cannot check reliably, so we allow the read.
+    """
+    if os.name != "posix":
+        return True
+    try:
+        mode = os.stat(path).st_mode
+    except OSError:
+        return False
+    if mode & 0o077:
+        _warn("ignoring inline token in config (readable by group/other; "
+              "tighten permissions to 0600): " + path)
+        return False
+    return True
+
+
+def _render(token, server_url):
+    return _TEMPLATE.format(section=_SECTION, token=token, server_url=server_url)
+
+
+def _atomic_write(path, text):
+    """Write ``text`` via a temp file + rename, owner-only on POSIX."""
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as handle:
+        handle.write(text)
+    if os.name == "posix":
+        os.chmod(tmp, 0o600)
+    os.replace(tmp, path)
+
+
+def load(check_perms=True):
+    """Return ``{"token": str|None, "server_url": str|None}`` from the config.
+
+    A missing/unreadable file yields all-None. The ``server_url`` is non-secret
+    and always returned; the inline ``token`` is only returned when the file
+    passes the owner-only permission check (unless ``check_perms`` is False, used
+    internally to preserve a value while rewriting the file).
+    """
+    result = {"token": None, "server_url": None}
+    path = config_path()
+    if not path or not os.path.exists(path):
+        return result
+    parser = configparser.ConfigParser(interpolation=None)
+    try:
+        parser.read(path, encoding="utf-8")
+    except (configparser.Error, OSError, UnicodeDecodeError):
+        return result
+    if not parser.has_section(_SECTION):
+        return result
+    result["server_url"] = parser.get(_SECTION, "server_url", fallback="").strip() or None
+    token = parser.get(_SECTION, "token", fallback="").strip()
+    if token and (not check_perms or _check_owner_only(path)):
+        result["token"] = token
+    return result
+
+
+def ensure_default():
+    """Best-effort: write the commented default config if none exists.
+
+    Used as a zero-touch first-run scaffold by the plugin. Never raises and never
+    overwrites an existing file, so it cannot disturb a configured machine or fail
+    a build on a read-only home.
+    """
+    path = config_path()
+    if not path or os.path.exists(path):
+        return
+    try:
+        _atomic_write(path, _render("", DEFAULT_SERVER_URL))
+    except OSError:
+        pass  # scaffolding is a convenience, never fatal
+
+
+def set_values(token=None, server_url=None):
+    """Update ``token`` and/or ``server_url`` in the config, preserving the other.
+
+    Returns the path written. Raises ``RuntimeError`` if no config path can be
+    resolved (so the caller can report it).
+    """
+    path = config_path()
+    if not path:
+        raise RuntimeError("cannot determine the EmbeddedProto config location")
+    current = load(check_perms=False)
+    new_token = token if token is not None else (current["token"] or "")
+    new_url = (server_url if server_url is not None
+               else (current["server_url"] or DEFAULT_SERVER_URL))
+    _atomic_write(path, _render(new_token, new_url))
+    return path

EmbeddedProto/custom_header.py

@@ -0,0 +1,513 @@
+#
+# Copyright (C) 2020-2026 Embedded AMS B.V. - All Rights Reserved
+#
+# This file is part of Embedded Proto.
+#
+# Embedded Proto is dual licensed. You may use it under the terms of the
+# GNU General Public License version 3 (GPLv3) as published by the Free
+# Software Foundation, or under a commercial license from Embedded AMS B.V.
+#
+# Under the GPLv3 you must release the source code of
+# any product you distribute that includes Embedded Proto or code
+# generated by it. A commercial license removes that obligation.
+# See <https://embeddedproto.com/pricing/>.
+#
+# Embedded Proto is distributed WITHOUT ANY WARRANTY; without even the
+# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See the LICENSE file in the root of the repository for details.
+#
+# SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-EmbeddedProto-Commercial
+#
+# Embedded AMS B.V., Hoorn, the Netherlands - info at EmbeddedProto dot com
+#
+
+"""Resolve an optional custom header to place at the top of generated files.
+
+The header text is fetched from a configurable server for builds that present a
+build token, and cached locally so repeated builds reuse it without a network
+round-trip. Everything in this module is best-effort: a missing token, an
+unreachable server, a slow response, or any malformed reply all resolve to "no
+custom header" and the generator falls back to its default banner. Nothing here
+ever raises into, blocks, or slows a build beyond a single short timeout.
+"""
+
+import contextlib
+import hashlib
+import json
+import os
+import re
+import socket
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+
+try:
+    import fcntl  # POSIX advisory file locking; absent on Windows.
+except ImportError:  # pragma: no cover - exercised only on non-POSIX platforms
+    fcntl = None
+
+from EmbeddedProto import config
+
+# --- Contract constants (see the server-side API contract) --------------------
+
+# Re-exported from config (the lowest-level module) so there is a single
+# source of truth for the default endpoint.
+DEFAULT_SERVER_URL = config.DEFAULT_SERVER_URL
+TOKEN_RE = re.compile(r"^[A-Za-z0-9._:-]{16,256}$")
+
+_ENV_TOKEN = "EMBEDDEDPROTO_BUILD_TOKEN"
+_ENV_URL = "EMBEDDEDPROTO_LICENSE_URL"
+_ENV_INTERVAL = "EMBEDDEDPROTO_LICENSE_CHECKIN_INTERVAL"
+_ENV_DISABLE = "EMBEDDEDPROTO_LICENSE_DISABLE_CHECKIN"
+
+_DEFAULT_INTERVAL = 300            # 5 minutes
+_DEFAULT_GRACE = 86400             # offline-grace default when server omits ttl
+_GRACE_MIN = 300
+_GRACE_MAX = 2592000
+_TIMEOUT = 5                       # seconds; single attempt, no retry
+_MAX_HEADER_BYTES = 8192
+_FREE_MARKER = "free-install.json"
+
+
+# --- Small helpers ------------------------------------------------------------
+
+def _warn(message):
+    """Write a hygiene warning to stderr. Never includes the token value."""
+    sys.stderr.write("EmbeddedProto custom header: " + message + "\n")
+
+
+def _env_truthy(value):
+    return bool(value) and value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _cache_dir():
+    """Platform path to the per-token cache directory."""
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA")
+        return os.path.join(base, "embeddedproto", "licenses") if base else None
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(
+        os.path.expanduser("~"), ".cache")
+    return os.path.join(base, "embeddedproto", "licenses")
+
+
+def _cache_file(token):
+    directory = _cache_dir()
+    if not directory:
+        return None
+    digest = hashlib.sha256(token.encode("utf-8")).hexdigest()
+    return os.path.join(directory, digest + ".json")
+
+
+def _checkin_interval():
+    raw = os.environ.get(_ENV_INTERVAL, "").strip()
+    if not raw:
+        return _DEFAULT_INTERVAL
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return _DEFAULT_INTERVAL
+
+
+def _server_url():
+    env_url = os.environ.get(_ENV_URL, "").strip()
+    if env_url:
+        return env_url
+    # check_perms=False: we only need the (non-secret) URL here, so do not run the
+    # token permission check (and its warning) for an inline token we won't read.
+    return config.load(check_perms=False).get("server_url") or DEFAULT_SERVER_URL
+
+
+def _atomic_write_json(path, payload):
+    """Write JSON via a temp file + rename so a reader never sees a torn file."""
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle)
+        os.replace(tmp, path)
+    except OSError:
+        pass  # caching is an optimisation, never fatal
+
+
+@contextlib.contextmanager
+def _file_lock(path):
+    """Best-effort exclusive lock, used to serialise concurrent check-ins.
+
+    A single build commonly runs the plugin once per .proto file, in parallel
+    (e.g. ``make -j``). Without coordination every one of those processes finds
+    an empty cache and checks in, so the per-token throttle is bypassed and the
+    server sees one request per file. Holding this lock around the resolve makes
+    the first process fetch and cache the header while the rest wait briefly and
+    then read the warm cache - collapsing a parallel build to a single check-in.
+
+    Best-effort and non-fatal: without a path, or if the lock cannot be taken
+    (no fcntl on this platform, an OSError, ...), it degrades to no locking
+    rather than blocking or failing a build. The lock is released automatically
+    if the holder dies, so a crash cannot wedge other builds.
+    """
+    if not path:
+        yield
+        return
+    handle = None
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        handle = open(path, "a+")
+    except OSError:
+        yield
+        return
+    locked = False
+    try:
+        if fcntl is not None:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            locked = True
+    except OSError:
+        pass  # proceed unsynchronised rather than fail the build
+    try:
+        yield
+    finally:
+        try:
+            if locked:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        except OSError:
+            pass
+        handle.close()
+
+
+# --- Token discovery ----------------------------------------------------------
+
+def resolve_token():
+    """Return a validated build token, or None when none is configured.
+
+    Priority: the EMBEDDEDPROTO_BUILD_TOKEN environment variable, then the inline
+    token in the user config file. A malformed value is treated as absent.
+    """
+    try:
+        token = os.environ.get(_ENV_TOKEN, "").strip()
+        if not token:
+            token = (config.load().get("token") or "").strip()
+        if not token:
+            return None
+        if not TOKEN_RE.match(token):
+            _warn("ignoring malformed build token")
+            return None
+        return token
+    except Exception:  # pragma: no cover - defensive: never break a build
+        return None
+
+
+# --- Header sanitisation ------------------------------------------------------
+
+def _sanitize_header(text):
+    """Apply the contract's header rules; return None if the text is unusable."""
+    if not isinstance(text, str):
+        return None
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    if len(text.encode("utf-8")) > _MAX_HEADER_BYTES:
+        return None
+    for char in text:
+        if char in ("\n", "\t"):
+            continue
+        code = ord(char)
+        if code < 0x20 or code == 0x7F:
+            return None
+    return text
+
+
+def _clamp_grace(ttl_seconds):
+    try:
+        ttl = int(ttl_seconds)
+    except (TypeError, ValueError):
+        return _DEFAULT_GRACE
+    return max(_GRACE_MIN, min(_GRACE_MAX, ttl))
+
+
+# --- Cache --------------------------------------------------------------------
+
+def _read_cache(path):
+    """Return the cache dict or None.
+
+    Keys: ``header`` (str or None for an attempt-only marker), ``fetched_at``,
+    ``expires_at`` and ``last_attempt_at`` (floats). ``last_attempt_at`` records
+    the time of the last check-in attempt regardless of its outcome, and is what
+    throttles the next attempt.
+    """
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        if not isinstance(data, dict):
+            return None
+        header = data.get("header")
+        if header is not None and not isinstance(header, str):
+            header = None
+        return {
+            "header": header,
+            "fetched_at": float(data.get("fetched_at", 0)),
+            "expires_at": float(data.get("expires_at", 0)),
+            "last_attempt_at": float(data.get("last_attempt_at", 0)),
+        }
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def _write_cache(path, header, fetched_at, expires_at, last_attempt_at):
+    """Persist the cache dict (best-effort; see _atomic_write_json)."""
+    if path:
+        _atomic_write_json(path, {
+            "header": header,
+            "fetched_at": fetched_at,
+            "expires_at": expires_at,
+            "last_attempt_at": last_attempt_at,
+        })
+
+
+def _usable_header(cached, now):
+    """The cached header if still within its offline-grace window, else None."""
+    if cached is not None and cached["header"] is not None and now < cached["expires_at"]:
+        return cached["header"]
+    return None
+
+
+# --- Network ------------------------------------------------------------------
+
+def _post_json(url, payload):
+    """POST a JSON body. Return (status, parsed_dict_or_None). Never raises.
+
+    A status of None means the request did not complete (timeout, DNS, TLS,
+    connection error). HTTPS is mandatory; a non-HTTPS URL is refused.
+    """
+    if not url.lower().startswith("https://"):
+        _warn("server URL must use https; skipping request")
+        return None, None
+    body = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        url, data=body, method="POST",
+        headers={"Content-Type": "application/json"})
+    context = ssl.create_default_context()
+    try:
+        with urllib.request.urlopen(request, timeout=_TIMEOUT,
+                                    context=context) as response:
+            status = response.getcode()
+            raw = response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, None
+    except (urllib.error.URLError, socket.timeout, OSError, ValueError):
+        return None, None
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        return status, None
+    return status, parsed if isinstance(parsed, dict) else None
+
+
+def _payload(token, plugin_version):
+    payload = {}
+    if token is not None:
+        payload["token"] = token
+    if plugin_version:
+        payload["plugin_version"] = plugin_version
+    return payload
+
+
+# --- Free-install check-in (throttled, opt-out) -------------------------------
+
+def _free_marker_path():
+    directory = _cache_dir()
+    return os.path.join(directory, _FREE_MARKER) if directory else None
+
+
+def _free_install_due(now):
+    """True if no token is present and the throttle window has elapsed.
+
+    Without a cache directory there is nowhere to throttle, so we decline rather
+    than risk a check-in on every build.
+    """
+    path = _free_marker_path()
+    if not path:
+        return False
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            pinged_at = float(json.load(handle).get("pinged_at", 0))
+    except (OSError, ValueError, TypeError):
+        pinged_at = 0.0
+    return (now - pinged_at) >= _checkin_interval()
+
+
+def _free_install_checkin(now, plugin_version):
+    """Send the throttled, opt-out, best-effort tokenless check-in."""
+    if _env_truthy(os.environ.get(_ENV_DISABLE)):
+        return
+    path = _free_marker_path()
+    if path is None:
+        return  # no cache dir: nowhere to throttle, so decline rather than ping
+    # Serialise parallel invocations (as for the token path) so a single build
+    # checks in once; re-test the throttle inside the lock so the winner pings
+    # and the rest observe the fresh marker.
+    with _file_lock(path + ".lock"):
+        if not _free_install_due(now):
+            return
+        _post_json(_server_url(), _payload(None, plugin_version))
+        # Record the attempt regardless of outcome so a down server cannot turn
+        # the throttle off and cause a check-in on every build.
+        _atomic_write_json(path, {"pinged_at": now})
+
+
+# --- Public entry point -------------------------------------------------------
+
+def resolve_custom_header(token, plugin_version=""):
+    """Return a sanitized custom-header string, or None to use the default.
+
+    Never raises. Flow:
+      * no token            -> throttled free-install check-in, return None
+      * within the check-in
+        interval             -> return the cached header without a network call
+      * otherwise            -> best-effort check-in; on success use/refresh the
+                                header, on failure fall back to the cached header
+                                within its offline-grace window, else None
+    """
+    try:
+        return _resolve(token, plugin_version)
+    except Exception:  # pragma: no cover - defensive: never break a build
+        return None
+
+
+def check_token(token, url=None, plugin_version=""):
+    """Probe the server for ``token`` and return ``(status, parsed_dict_or_None)``.
+
+    A one-shot POST used by the configuration command to verify a token. The
+    HTTPS guard and 5s timeout of ``_post_json`` apply. ``status`` is None when the
+    request did not complete (timeout/DNS/TLS). Never raises.
+    """
+    try:
+        return _post_json(url or _server_url(), _payload(token, plugin_version))
+    except Exception:  # pragma: no cover - defensive
+        return None, None
+
+
+# CLI color helpers (best-effort ANSI; harmless when the terminal ignores them).
+_C_OK = "\033[92m"
+_C_WARN = "\033[93m"
+_C_ERR = "\033[91m"
+_C_END = "\033[0m"
+
+
+def _describe_check(status, data):
+    """Map a check_token result to ``(color, message)`` for display."""
+    if status == 200 and isinstance(data, dict) and isinstance(data.get("header"), str):
+        size = len(data["header"].encode("utf-8"))
+        return _C_OK, "License active - custom header retrieved (%d bytes)." % size
+    if status == 200:
+        return _C_WARN, "Server returned 200 but no usable header; build uses the default."
+    if status == 204:
+        return _C_WARN, ("Server reachable, but this token returned no header (unknown or "
+                         "inactive token). Builds still work with the default header.")
+    if status == 400:
+        return _C_ERR, "Server rejected the request as malformed."
+    if status is None:
+        return _C_WARN, ("Could not reach the server (network/TLS/timeout). Settings saved; "
+                         "builds still work and will retry later.")
+    return _C_WARN, "Unexpected server response (status %s)." % status
+
+
+def configure(token=None, server_url=None, check_only=False, plugin_version=""):
+    """Save token/url to the user config and probe the server. Returns an exit code.
+
+    Shared by ``embeddedproto --set-token`` and ``install.py``. With ``check_only``
+    nothing is written and the already-configured token/url is probed. A malformed
+    token or a non-https URL is a hard error (returns 1, nothing written). A failed
+    connectivity check is reported but returns 0 - a build is never blocked by it.
+    """
+    if token is not None:
+        token = token.strip()
+        if not TOKEN_RE.match(token):
+            sys.stdout.write(_C_ERR + "Invalid token format; nothing was saved." + _C_END + "\n")
+            return 1
+    if server_url is not None:
+        server_url = server_url.strip()
+        if not server_url.lower().startswith("https://"):
+            sys.stdout.write(_C_ERR + "Server URL must start with https://; nothing was saved."
+                             + _C_END + "\n")
+            return 1
+
+    if not check_only and (token is not None or server_url is not None):
+        try:
+            path = config.set_values(token=token, server_url=server_url)
+            sys.stdout.write("Saved license settings to " + path + "\n")
+        except (OSError, RuntimeError) as error:
+            sys.stdout.write(_C_ERR + "Could not write config: " + str(error) + _C_END + "\n")
+            return 1
+
+    probe_token = token if token is not None else resolve_token()
+    if not probe_token:
+        sys.stdout.write(_C_WARN + "No token configured; skipping server check." + _C_END + "\n")
+        return 0
+
+    status, data = check_token(probe_token, url=server_url, plugin_version=plugin_version)
+    color, message = _describe_check(status, data)
+    sys.stdout.write(color + message + _C_END + "\n")
+    return 0
+
+
+def _resolve(token, plugin_version):
+    now = time.time()
+
+    # Zero-touch first run: drop a commented default config so the user can find
+    # and edit it. Skipped when a token is supplied via the environment (e.g. CI),
+    # and a no-op when a config already exists. Best-effort; never blocks a build.
+    if not os.environ.get(_ENV_TOKEN, "").strip():
+        config.ensure_default()
+
+    if token is None:
+        _free_install_checkin(now, plugin_version)
+        return None
+
+    cache_path = _cache_file(token)
+    if cache_path is None:
+        # No cache directory (e.g. no home): nowhere to lock or cache, so fall
+        # back to a single unsynchronised best-effort check-in.
+        return _checkin(token, None, None, plugin_version, now)
+
+    # Serialise concurrent invocations (a parallel build generating many .proto
+    # files at once) so they collapse to a single check-in: the lock holder
+    # fetches and caches the header, the rest wait briefly then read the warm
+    # cache. Re-read inside the lock to observe a sibling's fresh write.
+    with _file_lock(cache_path + ".lock"):
+        now = time.time()
+        cached = _read_cache(cache_path)
+
+        # Throttle the check-in (one network call + one usage signal) by the
+        # interval, gated on the last *attempt* (recorded regardless of outcome).
+        # This collapses rapid repeats within a single build and stops a down
+        # server from stalling every build. The cached header keeps serving in
+        # the meantime.
+        if cached is not None and (now - cached["last_attempt_at"]) < _checkin_interval():
+            return _usable_header(cached, now)
+        return _checkin(token, cache_path, cached, plugin_version, now)
+
+
+def _checkin(token, cache_path, cached, plugin_version, now):
+    """Perform one server check-in and return the header (or None).
+
+    Invoked with the per-token lock held (when a cache directory exists) so only
+    one process per build makes the network round-trip. On success the header is
+    sanitised and cached. On failure (or no usable header) the cached header
+    keeps serving within its offline-grace window and the attempt time is
+    recorded, so a down server still throttles the next build; with no usable
+    cache a header-less marker is written to throttle the retry the same way.
+    """
+    status, data = _post_json(_server_url(), _payload(token, plugin_version))
+    if status == 200 and data is not None:
+        header = _sanitize_header(data.get("header"))
+        if header is not None:
+            grace = _clamp_grace(data.get("ttl_seconds", _DEFAULT_GRACE))
+            _write_cache(cache_path, header, now, now + grace, now)
+            return header
+
+    if cached is not None:
+        _write_cache(cache_path, cached["header"], cached["fetched_at"],
+                     cached["expires_at"], now)
+        return _usable_header(cached, now)
+
+    _write_cache(cache_path, None, 0, 0, now)
+    return None